 [](https://travis-ci.com/qchateau/cbitstruct)
# About
`cbitstruct` is a C implementation of the `bitstruct` library. Credits to Erik Moqvist for the original `bitstruct` library available on [Github](https://github.com/eerimoq/bitstruct) and [pip](https://pypi.org/project/bitstruct/).
The goal is to provide the same API an idealy to be able to interchange `import bitstruct` and `import cbitstruct as bitstruct`.
Obvious increased performance comes with limitations described below.
# Installation
```bash
pip3 install cbitstruct
```
# Documentation
Please refer to the [`bitstruct` documentation](https://bitstruct.readthedocs.io/en/latest/) as the aim of this library is to provide the same API with increased performance.
If you are not used to `bitstruct`, you should seriously consider using it first, before migrating to this library if you require higher performance.
# Limitations
| Limitation | Will it be lifted ? |
|------------|---------------------|
| All types except padding are limited to 64 bits | Maybe for 'raw' and 'text' types |
| May not work on big-endian architectures | Maybe |
| Exceptions differ from `bitstruct` | Probably not |
| CPython only | Probably not |
| Error messages are unclear | Will never be as clear as `bitstruct` |
| Python >= 3.5 | No |
Some limitations are there because I did not get the time or motivation to lift them up. Some other are deeply rooted into this library and may never be lifted.
# Performance
## Comparing to `bitstruct`
The script available in `tests/test_perf.py` measures performance comparing to the `bitstruct` library.
Here are the result "on my machine" (Ubuntu in Virtualbox on a laptop):
```
byteswap list of int | x 8.779 ( 8.638us -> 0.984us)
byteswap str | x 17.466 ( 9.158us -> 0.524us)
calcsize | x139.330 ( 61.060us -> 0.438us)
compiled pack | x 47.389 ( 35.968us -> 0.759us)
compiled pack_dict | x 27.184 ( 34.588us -> 1.272us)
compiled pack_into | x 32.037 ( 38.650us -> 1.206us)
compiled pack_into_dict | x 27.343 ( 37.718us -> 1.379us)
compiled unpack | x 33.928 ( 31.278us -> 0.922us)
compiled unpack_dict | x 21.627 ( 31.597us -> 1.461us)
compiled unpack_from | x 30.622 ( 29.977us -> 0.979us)
compiled unpack_from_dict | x 20.479 ( 30.936us -> 1.511us)
pack | x 77.003 ( 103.030us -> 1.338us)
pack_dict | x 53.254 ( 103.255us -> 1.939us)
pack_into | x 82.829 ( 119.373us -> 1.441us)
pack_into_dict | x 52.173 ( 108.135us -> 2.073us)
unpack | x 78.459 ( 91.896us -> 1.171us)
unpack_dict | x 40.287 ( 89.300us -> 2.217us)
unpack_from | x 77.027 ( 91.202us -> 1.184us)
unpack_from_dict | x 39.467 ( 88.043us -> 2.231us)
```
*Disclaimer:* these results may and will vary largely depending on the number of elements and types you pack/unpack. This script is provided as-is, and I will gladly accept an improved script providing more reliable results.
## The dict API
The `dict` API is marginally slower than the traditional one. As the packing/unpacking performance is quite high, the overhead of performing dictionary lookups and hashing significantly increas pack and unpacking duration.
Raw data
{
"_id": null,
"home_page": "https://github.com/qchateau/cbitstruct",
"name": "cbitstruct",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "bit,pack,unpack,struct,bitfield,bit parsing,bit unpack,bit pack,C",
"author": "Quentin CHATEAU",
"author_email": "quentin.chateau@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a1/d5/b3bceb3515e71df2d7a3493e3a4f2e050ec5eac30ac957c8e2f4c2e9216f/cbitstruct-1.1.0.tar.gz",
"platform": null,
"description": " [](https://travis-ci.com/qchateau/cbitstruct)\n\n# About\n\n`cbitstruct` is a C implementation of the `bitstruct` library. Credits to Erik Moqvist for the original `bitstruct` library available on [Github](https://github.com/eerimoq/bitstruct) and [pip](https://pypi.org/project/bitstruct/).\n\nThe goal is to provide the same API an idealy to be able to interchange `import bitstruct` and `import cbitstruct as bitstruct`.\n\nObvious increased performance comes with limitations described below.\n\n# Installation\n\n```bash\npip3 install cbitstruct\n```\n\n# Documentation\n\nPlease refer to the [`bitstruct` documentation](https://bitstruct.readthedocs.io/en/latest/) as the aim of this library is to provide the same API with increased performance.\n\nIf you are not used to `bitstruct`, you should seriously consider using it first, before migrating to this library if you require higher performance.\n\n# Limitations\n\n| Limitation | Will it be lifted ? |\n|------------|---------------------|\n| All types except padding are limited to 64 bits | Maybe for 'raw' and 'text' types |\n| May not work on big-endian architectures | Maybe |\n| Exceptions differ from `bitstruct` | Probably not |\n| CPython only | Probably not |\n| Error messages are unclear | Will never be as clear as `bitstruct` |\n| Python >= 3.5 | No |\n\nSome limitations are there because I did not get the time or motivation to lift them up. Some other are deeply rooted into this library and may never be lifted.\n\n# Performance\n\n## Comparing to `bitstruct`\n\nThe script available in `tests/test_perf.py` measures performance comparing to the `bitstruct` library.\n\nHere are the result \"on my machine\" (Ubuntu in Virtualbox on a laptop):\n```\nbyteswap list of int | x 8.779 ( 8.638us -> 0.984us)\nbyteswap str | x 17.466 ( 9.158us -> 0.524us)\ncalcsize | x139.330 ( 61.060us -> 0.438us)\ncompiled pack | x 47.389 ( 35.968us -> 0.759us)\ncompiled pack_dict | x 27.184 ( 34.588us -> 1.272us)\ncompiled pack_into | x 32.037 ( 38.650us -> 1.206us)\ncompiled pack_into_dict | x 27.343 ( 37.718us -> 1.379us)\ncompiled unpack | x 33.928 ( 31.278us -> 0.922us)\ncompiled unpack_dict | x 21.627 ( 31.597us -> 1.461us)\ncompiled unpack_from | x 30.622 ( 29.977us -> 0.979us)\ncompiled unpack_from_dict | x 20.479 ( 30.936us -> 1.511us)\npack | x 77.003 ( 103.030us -> 1.338us)\npack_dict | x 53.254 ( 103.255us -> 1.939us)\npack_into | x 82.829 ( 119.373us -> 1.441us)\npack_into_dict | x 52.173 ( 108.135us -> 2.073us)\nunpack | x 78.459 ( 91.896us -> 1.171us)\nunpack_dict | x 40.287 ( 89.300us -> 2.217us)\nunpack_from | x 77.027 ( 91.202us -> 1.184us)\nunpack_from_dict | x 39.467 ( 88.043us -> 2.231us)\n```\n\n*Disclaimer:* these results may and will vary largely depending on the number of elements and types you pack/unpack. This script is provided as-is, and I will gladly accept an improved script providing more reliable results.\n\n\n## The dict API\nThe `dict` API is marginally slower than the traditional one. As the packing/unpacking performance is quite high, the overhead of performing dictionary lookups and hashing significantly increas pack and unpacking duration.\n",
"bugtrack_url": null,
"license": "MPL-2.0",
"summary": "Faster C implementation of bitstruct",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/qchateau/cbitstruct"
},
"split_keywords": [
"bit",
"pack",
"unpack",
"struct",
"bitfield",
"bit parsing",
"bit unpack",
"bit pack",
"c"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d316b5046c62c11ebfaa397749333c21ff23cbfcafbcfc6bf9636c924952d282",
"md5": "ff793eea3c1524dfdde8ebb4080c56e1",
"sha256": "c9c38dcd23e82d9aa77766841976fe5189d45e222cf1e516ba4a53ce349db560"
},
"downloads": -1,
"filename": "cbitstruct-1.1.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "ff793eea3c1524dfdde8ebb4080c56e1",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.6",
"size": 69614,
"upload_time": "2023-12-09T21:02:22",
"upload_time_iso_8601": "2023-12-09T21:02:22.259070Z",
"url": "https://files.pythonhosted.org/packages/d3/16/b5046c62c11ebfaa397749333c21ff23cbfcafbcfc6bf9636c924952d282/cbitstruct-1.1.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e88361eea15181c8e2a226085f4f9b01d06fff7785d8783990fbf7e31d63aaa5",
"md5": "8d954fc02a4efc90a929ae77750045b5",
"sha256": "c4197911d32659e89b7699428d19e6eb7ba37eb585227eb691587cd87be5150e"
},
"downloads": -1,
"filename": "cbitstruct-1.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "8d954fc02a4efc90a929ae77750045b5",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.6",
"size": 71559,
"upload_time": "2023-12-09T21:02:23",
"upload_time_iso_8601": "2023-12-09T21:02:23.680334Z",
"url": "https://files.pythonhosted.org/packages/e8/83/61eea15181c8e2a226085f4f9b01d06fff7785d8783990fbf7e31d63aaa5/cbitstruct-1.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b776114378e8ea70ccd2681bd5a489b5729b400de586d8553f2708e60749977a",
"md5": "cfcd131732f4a2ba100c212d95fa7226",
"sha256": "83712fb7758e8f99823ae2be629d78fa92e3879ba4d329d22651ef76c562fb61"
},
"downloads": -1,
"filename": "cbitstruct-1.1.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "cfcd131732f4a2ba100c212d95fa7226",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.6",
"size": 72541,
"upload_time": "2023-12-09T21:02:24",
"upload_time_iso_8601": "2023-12-09T21:02:24.908112Z",
"url": "https://files.pythonhosted.org/packages/b7/76/114378e8ea70ccd2681bd5a489b5729b400de586d8553f2708e60749977a/cbitstruct-1.1.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9b410d8f27276e463be7e5a3c3e5b18e5c2d7e5f6fddeee9443f29670b0f7c83",
"md5": "107c1ce68c9466f88f9807e448d9a36d",
"sha256": "6ff61e58a494c92573d6db19c2a3d2384810d85c354f0fc735b368ac219e7e21"
},
"downloads": -1,
"filename": "cbitstruct-1.1.0-cp36-cp36m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "107c1ce68c9466f88f9807e448d9a36d",
"packagetype": "bdist_wheel",
"python_version": "cp36",
"requires_python": ">=3.6",
"size": 68242,
"upload_time": "2023-12-09T21:02:26",
"upload_time_iso_8601": "2023-12-09T21:02:26.596025Z",
"url": "https://files.pythonhosted.org/packages/9b/41/0d8f27276e463be7e5a3c3e5b18e5c2d7e5f6fddeee9443f29670b0f7c83/cbitstruct-1.1.0-cp36-cp36m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c611f740ccf65c50b20104550ebf15e2ad2b2062464f6138abf10ca915d6d782",
"md5": "f7a10f6141a778fe30c3d5660122c855",
"sha256": "d8bd95afce3327a675ac819878605d22eda0bb2a978528b367305603672dc4d2"
},
"downloads": -1,
"filename": "cbitstruct-1.1.0-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "f7a10f6141a778fe30c3d5660122c855",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.6",
"size": 68239,
"upload_time": "2023-12-09T21:02:27",
"upload_time_iso_8601": "2023-12-09T21:02:27.790062Z",
"url": "https://files.pythonhosted.org/packages/c6/11/f740ccf65c50b20104550ebf15e2ad2b2062464f6138abf10ca915d6d782/cbitstruct-1.1.0-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "679e989e8b95c1b45e92bd2c59d848f85f9f0d7fcddc48ce1daba07ad935adc5",
"md5": "931d86621c19a5ad5439ca405b9996bf",
"sha256": "47e805f5300fc064d7d24a86e96617edb2bf85da598c8dfeaba939c3eeafefc0"
},
"downloads": -1,
"filename": "cbitstruct-1.1.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "931d86621c19a5ad5439ca405b9996bf",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": ">=3.6",
"size": 69517,
"upload_time": "2023-12-09T21:02:28",
"upload_time_iso_8601": "2023-12-09T21:02:28.811320Z",
"url": "https://files.pythonhosted.org/packages/67/9e/989e8b95c1b45e92bd2c59d848f85f9f0d7fcddc48ce1daba07ad935adc5/cbitstruct-1.1.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f4d326ca71738c8f143918aed224c285f4dda62507b8efc299d5c3b9c1f1c702",
"md5": "ed2d269004aa6b2d70a947ffdfbfbf60",
"sha256": "13359a61531d7ebce2298362e38c7145005eceefa32d01dac2ec53cea2ec3725"
},
"downloads": -1,
"filename": "cbitstruct-1.1.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "ed2d269004aa6b2d70a947ffdfbfbf60",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.6",
"size": 69464,
"upload_time": "2023-12-09T21:02:29",
"upload_time_iso_8601": "2023-12-09T21:02:29.794589Z",
"url": "https://files.pythonhosted.org/packages/f4/d3/26ca71738c8f143918aed224c285f4dda62507b8efc299d5c3b9c1f1c702/cbitstruct-1.1.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a1d5b3bceb3515e71df2d7a3493e3a4f2e050ec5eac30ac957c8e2f4c2e9216f",
"md5": "310864f07251cd415dd95b380a015d78",
"sha256": "43b8d11b4c8042eb2273018698653b49573f97d0f9816e825ff2e89e2e835e39"
},
"downloads": -1,
"filename": "cbitstruct-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "310864f07251cd415dd95b380a015d78",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 29278,
"upload_time": "2023-12-09T21:02:31",
"upload_time_iso_8601": "2023-12-09T21:02:31.551834Z",
"url": "https://files.pythonhosted.org/packages/a1/d5/b3bceb3515e71df2d7a3493e3a4f2e050ec5eac30ac957c8e2f4c2e9216f/cbitstruct-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-09 21:02:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "qchateau",
"github_project": "cbitstruct",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cbitstruct"
}
JSON
