Merge pull request #31 from forrestfwilliams/develop

Release v0.0.4

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

README.md

@@ -1,18 +1,18 @@
 # 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
-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 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 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
+* The ability to modify the points contained within an index via the `Index.create_modified_index()` method
+

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