From 06328419237113a3ff7c3f1295e837cfadf57730 Mon Sep 17 00:00:00 2001 From: Forrest Williams Date: Mon, 27 Mar 2023 08:11:10 -0500 Subject: [PATCH 1/4] update readme --- README.md | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 6517d9d..f205ffb 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,13 @@ `zran` is a Python extension that wraps the [zran](https://github.com/madler/zlib/blob/master/examples/zran.h) library, which was created by Mark Adler (the creator of `zlib`). This utility allows you to create an index that allows you begin decompressing DEFLATE-compressed data (ZLIB, GZIP, or DEFLATE format) from compression block boundaries. This effectively allows you to randomly access DEFLATE-compressed data once the index is created. ## Installation -In your preferred python environment: +`zran` can be installed in your preferred Python environment via pip: + ```bash -git clone https://github.com/forrestfwilliams/zran.git -cd zran -python -m pip install . +python -m pip install zran ``` -As far as I can tell, pip installing with the `--editable` command is not valid when the code needs to be compiled, so you will need to re-install the package if you make any changes. + +Currently, only macOS/Linux x86_64 and ARM64 architectures are supported. Please open an issue or submit a PR if you would like to see support for other platforms! ## Usage To use `zran`, you need to: @@ -37,3 +37,24 @@ data = zran.decompress(compressed_file, index, start, length) ``` That's it! + +## Contributing +We use the standard GitHub flow to manage contributions to this project. Check out this [documentation](https://docs.github.com/en/get-started/quickstart/github-flow) if you are unfamiliar with this process. + +You can install a development version of `zran` via pip as well: +```bash +git clone https://github.com/forrestfwilliams/zran.git +cd zran +python -m pip install . +``` +Then, run `pytest` to ensure that all tests are passing. We use [black](https://black.readthedocs.io/en/stable/) with `line-length 120` for formatting and [ruff](https://beta.ruff.rs/docs/) for linting. Please ensure that your code is correctly formatted and linted before submitting a PR. As far as I can tell, pip installing with the `--editable` command is not valid when the code needs to be compiled, so you will need to re-install the package if you make any changes. + +## Similar Projects +If you prefer to work in the C programming language, you may want to work directly with the `zran` source C code in the [zlib](https://github.com/madler/zlib) library. Paul McCarthy's [`indexed_gzip`](https://github.com/pauldmccarthy/indexed_gzip) library was a huge inspiration for this project, and in particular was a huge help while creating the `setup.py` file for this project. If you plan to work exclusively with gzip files, you may be better served by the `indexed_gzip` library. However, this project has some unique functionality that sets it apart: + +* Use of the most up-to-date of the `zran` C library +* Support for ZLIB, GZIP, and DEFLATE formatted data +* Greater visibility into the contents of indexes +* Compression of the indexes when written to a file, leading to smaller index file sizes +* The ability to modify the points contained within an index via the `Index.create_modified_index()` method + From 8f7add4d7a554453574ad511c44e4b8d27aa3140 Mon Sep 17 00:00:00 2001 From: Forrest Williams Date: Mon, 27 Mar 2023 08:14:56 -0500 Subject: [PATCH 2/4] setup.py add contribution note --- setup.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/setup.py b/setup.py index 6db1e87..69813b7 100644 --- a/setup.py +++ b/setup.py @@ -1,5 +1,9 @@ #!/usr/bin/env python """Setup script for zran package. + +This script was modified from the setup.py file created by +Paul McCarthy for the indexed_gzip project. You can find the +project at this link: https://github.com/pauldmccarthy/indexed_gzip. """ import glob From 4f23ffd9a7d9843bc8de43a1e453ad473c268198 Mon Sep 17 00:00:00 2001 From: Forrest Williams Date: Mon, 27 Mar 2023 08:15:17 -0500 Subject: [PATCH 3/4] update changelog --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0c90839..87dac76 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [PEP 440](https://www.python.org/dev/peps/pep-0440/) and uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.0.4] +### Added +* New information to the README.md concerning contributions and similar projects +* Contribution note to setup.py ## [0.0.3] ### Fixed From 3aaae50964a520f7d6a73d7d7230d7d7cd8e2463 Mon Sep 17 00:00:00 2001 From: Forrest Williams Date: Mon, 27 Mar 2023 08:37:27 -0500 Subject: [PATCH 4/4] readme: fix typos --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f205ffb..22cba32 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # ZRAN -## Random read access for gzip and zip files +## Random read access for ZLIB, GZIP and DEFLATE file formats ## Description -`zran` is a Python extension that wraps the [zran](https://github.com/madler/zlib/blob/master/examples/zran.h) library, which was created by Mark Adler (the creator of `zlib`). This utility allows you to create an index that allows you begin decompressing DEFLATE-compressed data (ZLIB, GZIP, or DEFLATE format) from compression block boundaries. This effectively allows you to randomly access DEFLATE-compressed data once the index is created. +`zran` is a Python extension that wraps the [zran](https://github.com/madler/zlib/blob/master/examples/zran.h) library, which was created by Mark Adler (the creator of `zlib`). This utility will create an index that will allow you to begin decompressing DEFLATE-compressed data (ZLIB, GZIP, or DEFLATE format) from compression block boundaries on subsequent reads. This effectively allows you to randomly access DEFLATE-compressed data once the index is created. ## Installation `zran` can be installed in your preferred Python environment via pip: @@ -50,9 +50,9 @@ python -m pip install . Then, run `pytest` to ensure that all tests are passing. We use [black](https://black.readthedocs.io/en/stable/) with `line-length 120` for formatting and [ruff](https://beta.ruff.rs/docs/) for linting. Please ensure that your code is correctly formatted and linted before submitting a PR. As far as I can tell, pip installing with the `--editable` command is not valid when the code needs to be compiled, so you will need to re-install the package if you make any changes. ## Similar Projects -If you prefer to work in the C programming language, you may want to work directly with the `zran` source C code in the [zlib](https://github.com/madler/zlib) library. Paul McCarthy's [`indexed_gzip`](https://github.com/pauldmccarthy/indexed_gzip) library was a huge inspiration for this project, and in particular was a huge help while creating the `setup.py` file for this project. If you plan to work exclusively with gzip files, you may be better served by the `indexed_gzip` library. However, this project has some unique functionality that sets it apart: +If you prefer to work in the C programming language, you may want to work directly with the `zran` source C code in the [zlib](https://github.com/madler/zlib) library. Paul McCarthy's [`indexed_gzip`](https://github.com/pauldmccarthy/indexed_gzip) library was a huge inspiration for this project, and in particular was a huge help while creating our `setup.py` file. If you plan to work exclusively with gzip files, you may be better served by the `indexed_gzip` library. However, this project has some unique functionality that sets it apart: -* Use of the most up-to-date of the `zran` C library +* Use of the most up-to-date version of the `zran` C library * Support for ZLIB, GZIP, and DEFLATE formatted data * Greater visibility into the contents of indexes * Compression of the indexes when written to a file, leading to smaller index file sizes