PyHeatshrink
============
Compression using the `Heatshrink algorithm
<https://github.com/atomicobject/heatshrink>`__ in Python 3.
Installation
------------
From PyPI:
.. code-block::
$ pip install heatshrink2
Usage
-----
Files/Streams
^^^^^^^^^^^^^
The file interface attempts to imitate the behaviour of the built-in
`file` object and other file-like objects (E.g. :code:`bz2.BZ2File`),
thus you can expect all methods implemented in :code:`file` to also be
available.
You can open a heatshrink file by using the :code:`open` function:
.. code-block:: python
>>> import heatshrink2
>>> with heatshrink2.open('data.bin', 'wb') as fout:
... fout.write(b"Is there anybody in there?")
...
26
>>>
You can also use :code:`HeatshrinkFile` directly:
.. code-block:: python
>>> from heatshrink2 import HeatshrinkFile
>>> with HeatshrinkFile('data.bin') as fin:
... print(fin.read(256))
...
b'Is there anybody in there?'
>>> with HeatshrinkFile('data.bin') as fin:
... for line in fin:
... print(line)
...
b'Is there anybody in there?'
>>>
Byte strings
^^^^^^^^^^^^
The encoder accepts any iterable and returns a byte string
containing encoded (compressed) data.
.. code-block:: python
>>> import heatshrink2
>>> heatshrink2.compress(b'a string')
b'\xb0\xc8.wK\x95\xa6\xddg'
>>>
The decoder accepts any object that implements the buffer protocol and
returns a byte representation of the decoded data.
.. code-block:: python
>>> import heatshrink2
>>> heatshrink2.decompress(b'\xb0\xc8.wK\x95\xa6\xddg')
b'a string'
>>>
Parameters
^^^^^^^^^^
Both the encoder and decoder allow providing :code:`window_sz2` and
:code:`lookahead_sz2` keywords:
:code:`window_sz2` - The window size determines how far back in the
input can be searched for repeated patterns. A window_sz2 of 8 will
only use 256 bytes (2^8), while a window_sz2 of 10 will use 1024 bytes
(2^10). The latter uses more memory, but may also compress more
effectively by detecting more repetition.
:code:`lookahead_sz2` - The lookahead size determines the max length
for repeated patterns that are found. If the lookahead_sz2 is 4, a
50-byte run of 'a' characters will be represented as several repeated
16-byte patterns (2^4 is 16), whereas a larger lookahead_sz2 may be
able to represent it all at once. The number of bits used for the
lookahead size is fixed, so an overly large lookahead size can reduce
compression by adding unused size bits to small patterns.
:code:`input_buffer_size` - How large an input buffer to use for the
decoder. This impacts how much work the decoder can do in a single
step, and a larger buffer will use more memory. An extremely small
buffer (say, 1 byte) will add overhead due to lots of suspend/resume
function calls, but should not change how well data compresses.
Check out the `heatshrink configuration page
<https://github.com/atomicobject/heatshrink#configuration>`__ for more
details.
For more use cases, please refer to the `tests folder
<https://github.com/eerimoq/pyheatshrink/blob/master/tests>`__.
Command line
------------
The command line tool can compress and decompress files.
Below is an example of the compress and decompress subcommands.
.. code-block::
$ ls -l tests/files/foo.txt
-rw-rw-r-- 1 erik erik 3970 jan 5 12:23 tests/files/foo.txt
$ python -m heatshrink2 compress tests/files/foo.txt foo.hs
$ ls -l foo.hs
-rw-rw-r-- 1 erik erik 2727 jan 5 12:24 foo.hs
$ python -m heatshrink2 decompress foo.hs foo.txt
$ cmp tests/files/foo.txt foo.txt
Benchmarks
----------
The benchmarks check compression/decompression against a ~6MB file:
.. code-block::
$ python scripts/benchmark.py
Testing
-------
Running tests is as simple as doing:
.. code-block::
$ python setup.py build_ext -b .
$ python -m unittest
License
-------
ISC license
Raw data
{
"_id": null,
"home_page": "https://github.com/eerimoq/pyheatshrink",
"name": "heatshrink2",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "compression binding heatshrink LZSS",
"author": "Antonis Kalou @ JOHAN Sports, Erik Moqvist",
"author_email": "antonis@johan-sports.com, erik.moqvist@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f8/39/bedf839008c775307c3655a9a446ad853ee379bde537cc21c5257aa6efeb/heatshrink2-0.12.0.tar.gz",
"platform": null,
"description": "PyHeatshrink\n============\n\nCompression using the `Heatshrink algorithm\n<https://github.com/atomicobject/heatshrink>`__ in Python 3.\n\nInstallation\n------------\n\nFrom PyPI:\n\n.. code-block::\n\n $ pip install heatshrink2\n\nUsage\n-----\n\nFiles/Streams\n^^^^^^^^^^^^^\n\nThe file interface attempts to imitate the behaviour of the built-in\n`file` object and other file-like objects (E.g. :code:`bz2.BZ2File`),\nthus you can expect all methods implemented in :code:`file` to also be\navailable.\n\nYou can open a heatshrink file by using the :code:`open` function:\n\n.. code-block:: python\n\n >>> import heatshrink2\n >>> with heatshrink2.open('data.bin', 'wb') as fout:\n ... fout.write(b\"Is there anybody in there?\")\n ...\n 26\n >>>\n\nYou can also use :code:`HeatshrinkFile` directly:\n\n.. code-block:: python\n\n >>> from heatshrink2 import HeatshrinkFile\n >>> with HeatshrinkFile('data.bin') as fin:\n ... print(fin.read(256))\n ...\n b'Is there anybody in there?'\n >>> with HeatshrinkFile('data.bin') as fin:\n ... for line in fin:\n ... print(line)\n ...\n b'Is there anybody in there?'\n >>>\n\nByte strings\n^^^^^^^^^^^^\n\nThe encoder accepts any iterable and returns a byte string\ncontaining encoded (compressed) data.\n\n.. code-block:: python\n\n >>> import heatshrink2\n >>> heatshrink2.compress(b'a string')\n b'\\xb0\\xc8.wK\\x95\\xa6\\xddg'\n >>>\n\nThe decoder accepts any object that implements the buffer protocol and\nreturns a byte representation of the decoded data.\n\n.. code-block:: python\n\n >>> import heatshrink2\n >>> heatshrink2.decompress(b'\\xb0\\xc8.wK\\x95\\xa6\\xddg')\n b'a string'\n >>>\n\nParameters\n^^^^^^^^^^\n\nBoth the encoder and decoder allow providing :code:`window_sz2` and\n:code:`lookahead_sz2` keywords:\n\n:code:`window_sz2` - The window size determines how far back in the\ninput can be searched for repeated patterns. A window_sz2 of 8 will\nonly use 256 bytes (2^8), while a window_sz2 of 10 will use 1024 bytes\n(2^10). The latter uses more memory, but may also compress more\neffectively by detecting more repetition.\n\n:code:`lookahead_sz2` - The lookahead size determines the max length\nfor repeated patterns that are found. If the lookahead_sz2 is 4, a\n50-byte run of 'a' characters will be represented as several repeated\n16-byte patterns (2^4 is 16), whereas a larger lookahead_sz2 may be\nable to represent it all at once. The number of bits used for the\nlookahead size is fixed, so an overly large lookahead size can reduce\ncompression by adding unused size bits to small patterns.\n\n:code:`input_buffer_size` - How large an input buffer to use for the\ndecoder. This impacts how much work the decoder can do in a single\nstep, and a larger buffer will use more memory. An extremely small\nbuffer (say, 1 byte) will add overhead due to lots of suspend/resume\nfunction calls, but should not change how well data compresses.\n\nCheck out the `heatshrink configuration page\n<https://github.com/atomicobject/heatshrink#configuration>`__ for more\ndetails.\n\nFor more use cases, please refer to the `tests folder\n<https://github.com/eerimoq/pyheatshrink/blob/master/tests>`__.\n\nCommand line\n------------\n\nThe command line tool can compress and decompress files.\n\nBelow is an example of the compress and decompress subcommands.\n\n.. code-block::\n\n $ ls -l tests/files/foo.txt\n -rw-rw-r-- 1 erik erik 3970 jan 5 12:23 tests/files/foo.txt\n $ python -m heatshrink2 compress tests/files/foo.txt foo.hs\n $ ls -l foo.hs\n -rw-rw-r-- 1 erik erik 2727 jan 5 12:24 foo.hs\n $ python -m heatshrink2 decompress foo.hs foo.txt\n $ cmp tests/files/foo.txt foo.txt\n\nBenchmarks\n----------\n\nThe benchmarks check compression/decompression against a ~6MB file:\n\n.. code-block::\n\n $ python scripts/benchmark.py\n\nTesting\n-------\n\nRunning tests is as simple as doing:\n\n.. code-block::\n\n $ python setup.py build_ext -b .\n $ python -m unittest\n\nLicense\n-------\n\nISC license\n",
"bugtrack_url": null,
"license": "ISC",
"summary": "Python bindings to the heatshrink library",
"version": "0.12.0",
"split_keywords": [
"compression",
"binding",
"heatshrink",
"lzss"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7e619ad0635267c447395b8abe7a860a9300d9c320463a4cb68351fbf013d452",
"md5": "59efbcb0452dad1e590595d5382a8150",
"sha256": "1b6e735be1fcf422c1142737e1e496e244ebb695fe1870a5ea5c457b67620db3"
},
"downloads": -1,
"filename": "heatshrink2-0.12.0-cp310-cp310-win32.whl",
"has_sig": false,
"md5_digest": "59efbcb0452dad1e590595d5382a8150",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": null,
"size": 47866,
"upload_time": "2023-01-31T13:43:02",
"upload_time_iso_8601": "2023-01-31T13:43:02.637379Z",
"url": "https://files.pythonhosted.org/packages/7e/61/9ad0635267c447395b8abe7a860a9300d9c320463a4cb68351fbf013d452/heatshrink2-0.12.0-cp310-cp310-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9e8f905b7ce7def5608c9ba72368b91d2919f5ee462894ac4f8b6f842387944e",
"md5": "0e6bd6c199216339136d65a149e5688b",
"sha256": "a7870220edf23053ff94cc3c020744989f79ed8e3491d9571b65915bd0c35ab5"
},
"downloads": -1,
"filename": "heatshrink2-0.12.0-cp310-cp310-win_amd64.whl",
"has_sig": false,
"md5_digest": "0e6bd6c199216339136d65a149e5688b",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": null,
"size": 52374,
"upload_time": "2023-01-31T13:43:47",
"upload_time_iso_8601": "2023-01-31T13:43:47.771867Z",
"url": "https://files.pythonhosted.org/packages/9e/8f/905b7ce7def5608c9ba72368b91d2919f5ee462894ac4f8b6f842387944e/heatshrink2-0.12.0-cp310-cp310-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c0d0009c775a133271b26a9c53515c2ddc6d9372acf35f883a1ec10a1f304895",
"md5": "8f5c082cab13d271a47090df3f77a5ad",
"sha256": "f03f9ee716782ff3fc282b8093a92f9208d89c6472ec08372b37ce7a063eadfe"
},
"downloads": -1,
"filename": "heatshrink2-0.12.0-cp311-cp311-win32.whl",
"has_sig": false,
"md5_digest": "8f5c082cab13d271a47090df3f77a5ad",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": null,
"size": 47548,
"upload_time": "2023-01-31T13:44:39",
"upload_time_iso_8601": "2023-01-31T13:44:39.616877Z",
"url": "https://files.pythonhosted.org/packages/c0/d0/009c775a133271b26a9c53515c2ddc6d9372acf35f883a1ec10a1f304895/heatshrink2-0.12.0-cp311-cp311-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "122e490c0239e460c64d662cceee6427649b5a3eb0bddfdd1fe4e38d23a21cc9",
"md5": "5b7b9316a9a48fd1c4f92e8194c5e62a",
"sha256": "9a3725281b011cf80f162c5ccf0ec1f8653100f4f1863b89be6a911994d940e0"
},
"downloads": -1,
"filename": "heatshrink2-0.12.0-cp311-cp311-win_amd64.whl",
"has_sig": false,
"md5_digest": "5b7b9316a9a48fd1c4f92e8194c5e62a",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": null,
"size": 51986,
"upload_time": "2023-01-31T13:45:22",
"upload_time_iso_8601": "2023-01-31T13:45:22.126554Z",
"url": "https://files.pythonhosted.org/packages/12/2e/490c0239e460c64d662cceee6427649b5a3eb0bddfdd1fe4e38d23a21cc9/heatshrink2-0.12.0-cp311-cp311-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0d11e465d5407579568f47af9c39c7fc3ed74ca22feba7d1cd6d467ca81682c6",
"md5": "594f9d52c931519986b9f47bb47fb009",
"sha256": "a5abada1906a59647d83e57220c09b4513a9bd2be00a4634ebd53112eda7358d"
},
"downloads": -1,
"filename": "heatshrink2-0.12.0-cp37-cp37m-win32.whl",
"has_sig": false,
"md5_digest": "594f9d52c931519986b9f47bb47fb009",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": null,
"size": 52766,
"upload_time": "2023-01-31T13:38:06",
"upload_time_iso_8601": "2023-01-31T13:38:06.454015Z",
"url": "https://files.pythonhosted.org/packages/0d/11/e465d5407579568f47af9c39c7fc3ed74ca22feba7d1cd6d467ca81682c6/heatshrink2-0.12.0-cp37-cp37m-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "237b073e0f09c736468621a71f81e9c3462a7995eaa032a9cda7384fc5020248",
"md5": "3d1fbeaa764b400e117881f781445f4c",
"sha256": "cf227384c540f7527b7f7b8fc1513748cb747847bf8e74cc8eec06454d15460a"
},
"downloads": -1,
"filename": "heatshrink2-0.12.0-cp37-cp37m-win_amd64.whl",
"has_sig": false,
"md5_digest": "3d1fbeaa764b400e117881f781445f4c",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": null,
"size": 60168,
"upload_time": "2023-01-31T13:38:56",
"upload_time_iso_8601": "2023-01-31T13:38:56.377332Z",
"url": "https://files.pythonhosted.org/packages/23/7b/073e0f09c736468621a71f81e9c3462a7995eaa032a9cda7384fc5020248/heatshrink2-0.12.0-cp37-cp37m-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f4caa8a41aeed8f356906becdb03d47cd4c4d13633a686e4bdc474362ae79a88",
"md5": "199d6d268c70a1eb81c16bda4c286b1c",
"sha256": "d958f0712147d8224d86923f65b7867a1c5ea67cec5b6a4bdff4af4b72536c1b"
},
"downloads": -1,
"filename": "heatshrink2-0.12.0-cp38-cp38-win32.whl",
"has_sig": false,
"md5_digest": "199d6d268c70a1eb81c16bda4c286b1c",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": null,
"size": 53666,
"upload_time": "2023-01-31T13:39:46",
"upload_time_iso_8601": "2023-01-31T13:39:46.864838Z",
"url": "https://files.pythonhosted.org/packages/f4/ca/a8a41aeed8f356906becdb03d47cd4c4d13633a686e4bdc474362ae79a88/heatshrink2-0.12.0-cp38-cp38-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d34c50bcd8db919f76f7760aaa566df074f6b60db4dc10d1380677aa7b855486",
"md5": "2983d8869b1cc61bfc28fa58f143979d",
"sha256": "dbcdc2c09cfe30a029c1e8e6acac2e4e87c6bc8fa805f72f0a9485689cd041f3"
},
"downloads": -1,
"filename": "heatshrink2-0.12.0-cp38-cp38-win_amd64.whl",
"has_sig": false,
"md5_digest": "2983d8869b1cc61bfc28fa58f143979d",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": null,
"size": 61306,
"upload_time": "2023-01-31T13:40:40",
"upload_time_iso_8601": "2023-01-31T13:40:40.426554Z",
"url": "https://files.pythonhosted.org/packages/d3/4c/50bcd8db919f76f7760aaa566df074f6b60db4dc10d1380677aa7b855486/heatshrink2-0.12.0-cp38-cp38-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "62554c0f9e62acd625e4d06a78ea6ad6055bed7de5d159003889ebc12507ffaf",
"md5": "fea9ec16a77777baf1e238b95bca3845",
"sha256": "ba19f3ac2315bbfcac76637701fae2145315f137caaee410ba2bd8d19209dbf6"
},
"downloads": -1,
"filename": "heatshrink2-0.12.0-cp39-cp39-win32.whl",
"has_sig": false,
"md5_digest": "fea9ec16a77777baf1e238b95bca3845",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": null,
"size": 53667,
"upload_time": "2023-01-31T13:41:31",
"upload_time_iso_8601": "2023-01-31T13:41:31.309119Z",
"url": "https://files.pythonhosted.org/packages/62/55/4c0f9e62acd625e4d06a78ea6ad6055bed7de5d159003889ebc12507ffaf/heatshrink2-0.12.0-cp39-cp39-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8b0f342546d972fc3818fc990bc42fdd06b7b5315f8d18e2f516e6ff20ede35a",
"md5": "224dbe06786102047c2b262ad46f4318",
"sha256": "0b0f4d086c2acc3c917253722535e49531b1a89232446ae7c5c36cb5398de427"
},
"downloads": -1,
"filename": "heatshrink2-0.12.0-cp39-cp39-win_amd64.whl",
"has_sig": false,
"md5_digest": "224dbe06786102047c2b262ad46f4318",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": null,
"size": 61292,
"upload_time": "2023-01-31T13:42:13",
"upload_time_iso_8601": "2023-01-31T13:42:13.208019Z",
"url": "https://files.pythonhosted.org/packages/8b/0f/342546d972fc3818fc990bc42fdd06b7b5315f8d18e2f516e6ff20ede35a/heatshrink2-0.12.0-cp39-cp39-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f839bedf839008c775307c3655a9a446ad853ee379bde537cc21c5257aa6efeb",
"md5": "6c2ab9d23b29874aa429c45a8a528357",
"sha256": "6fb36a9d8d3e7df350ec777f2a86c7a84d3f6aaa3154d201fe8407ac050df351"
},
"downloads": -1,
"filename": "heatshrink2-0.12.0.tar.gz",
"has_sig": false,
"md5_digest": "6c2ab9d23b29874aa429c45a8a528357",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 111276,
"upload_time": "2023-01-31T13:33:43",
"upload_time_iso_8601": "2023-01-31T13:33:43.590525Z",
"url": "https://files.pythonhosted.org/packages/f8/39/bedf839008c775307c3655a9a446ad853ee379bde537cc21c5257aa6efeb/heatshrink2-0.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-31 13:33:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "eerimoq",
"github_project": "pyheatshrink",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"appveyor": true,
"requirements": [],
"lcname": "heatshrink2"
}
JSON
