{"id":18913574,"url":"https://github.com/eerimoq/bitstruct","last_synced_at":"2025-05-14T20:07:25.021Z","repository":{"id":31043661,"uuid":"34602308","full_name":"eerimoq/bitstruct","owner":"eerimoq","description":"Python bit pack/unpack package.","archived":false,"fork":false,"pushed_at":"2025-02-22T12:00:21.000Z","size":195,"stargazers_count":128,"open_issues_count":13,"forks_count":31,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-13T14:07:05.420Z","etag":null,"topics":["python"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eerimoq.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"eerimoq"}},"created_at":"2015-04-26T07:32:59.000Z","updated_at":"2025-02-22T12:00:24.000Z","dependencies_parsed_at":"2023-02-15T15:16:52.388Z","dependency_job_id":"dd43c816-0749-4c97-a7dd-0d47e21ef76a","html_url":"https://github.com/eerimoq/bitstruct","commit_stats":{"total_commits":187,"total_committers":8,"mean_commits":23.375,"dds":0.07486631016042777,"last_synced_commit":"60ca5983d99aee0a2205f5b19892565c9ea06190"},"previous_names":[],"tags_count":65,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eerimoq%2Fbitstruct","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eerimoq%2Fbitstruct/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eerimoq%2Fbitstruct/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eerimoq%2Fbitstruct/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eerimoq","download_url":"https://codeload.github.com/eerimoq/bitstruct/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248724639,"owners_count":21151561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python"],"created_at":"2024-11-08T10:08:18.055Z","updated_at":"2025-04-13T14:07:09.449Z","avatar_url":"https://github.com/eerimoq.png","language":"C","funding_links":["https://github.com/sponsors/eerimoq"],"categories":[],"sub_categories":[],"readme":"About\n=====\n\nThis module is intended to have a similar interface as the python\nstruct module, but working on bits instead of primitive data types\n(char, int, ...).\n\nProject homepage: https://github.com/eerimoq/bitstruct\n\nDocumentation: https://bitstruct.readthedocs.io\n\nInstallation\n============\n\n.. code-block:: python\n\n   pip install bitstruct\n\nPerformance\n===========\n\nParts of this package has been re-implemented in C for faster pack and\nunpack operations. There are two independent C implementations;\n`bitstruct.c`, which is part of this package, and the standalone\npackage `cbitstruct`_. These implementations are only available in\nCPython 3, and must be explicitly imported. By default the pure Python\nimplementation is used.\n\nTo use `bitstruct.c`, do ``import bitstruct.c as bitstruct``.\n\nTo use `cbitstruct`_, do ``import cbitstruct as bitstruct``.\n\n`bitstruct.c` has a few limitations compared to the pure Python\nimplementation:\n\n- Integers and booleans must be 64 bits or less.\n\n- Text and raw must be a multiple of 8 bits.\n\n- Bit endianness and byte order are not yet supported.\n\n- ``byteswap()`` can only swap 1, 2, 4 and 8 bytes.\n\nSee `cbitstruct`_ for its limitations.\n\nMicroPython\n===========\n\nThe C implementation has been ported to `MicroPython`_. See\n`bitstruct-micropython`_ for more details.\n\nExample usage\n=============\n\nA basic example of `packing`_ and `unpacking`_ four integers using the\nformat string ``'u1u3u4s16'``:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from bitstruct import *\n    \u003e\u003e\u003e pack('u1u3u4s16', 1, 2, 3, -4)\n    b'\\xa3\\xff\\xfc'\n    \u003e\u003e\u003e unpack('u1u3u4s16', b'\\xa3\\xff\\xfc')\n    (1, 2, 3, -4)\n    \u003e\u003e\u003e calcsize('u1u3u4s16')\n    24\n\nAn example `compiling`_ the format string once, and use it to `pack`_\nand `unpack`_ data:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e import bitstruct\n    \u003e\u003e\u003e cf = bitstruct.compile('u1u3u4s16')\n    \u003e\u003e\u003e cf.pack(1, 2, 3, -4)\n    b'\\xa3\\xff\\xfc'\n    \u003e\u003e\u003e cf.unpack(b'\\xa3\\xff\\xfc')\n    (1, 2, 3, -4)\n\nUse the `pack into`_ and `unpack from`_ functions to pack/unpack\nvalues at a bit offset into the data, in this example the bit offset\nis 5:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from bitstruct import *\n    \u003e\u003e\u003e data = bytearray(b'\\x00\\x00\\x00\\x00')\n    \u003e\u003e\u003e pack_into('u1u3u4s16', data, 5, 1, 2, 3, -4)\n    \u003e\u003e\u003e data\n    bytearray(b'\\x05\\x1f\\xff\\xe0')\n    \u003e\u003e\u003e unpack_from('u1u3u4s16', data, 5)\n    (1, 2, 3, -4)\n\nThe unpacked values can be named by assigning them to variables or by\nwrapping the result in a named tuple:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from bitstruct import *\n    \u003e\u003e\u003e from collections import namedtuple\n    \u003e\u003e\u003e MyName = namedtuple('myname', ['a', 'b', 'c', 'd'])\n    \u003e\u003e\u003e unpacked = unpack('u1u3u4s16', b'\\xa3\\xff\\xfc')\n    \u003e\u003e\u003e myname = MyName(*unpacked)\n    \u003e\u003e\u003e myname\n    myname(a=1, b=2, c=3, d=-4)\n    \u003e\u003e\u003e myname.c\n    3\n\nUse the `pack_dict`_ and `unpack_dict`_ functions to pack/unpack\nvalues in dictionaries:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from bitstruct import *\n    \u003e\u003e\u003e names = ['a', 'b', 'c', 'd']\n    \u003e\u003e\u003e pack_dict('u1u3u4s16', names, {'a': 1, 'b': 2, 'c': 3, 'd': -4})\n    b'\\xa3\\xff\\xfc'\n    \u003e\u003e\u003e unpack_dict('u1u3u4s16', names, b'\\xa3\\xff\\xfc')\n    {'a': 1, 'b': 2, 'c': 3, 'd': -4}\n\nAn example of `packing`_ and `unpacking`_ an unsigned integer, a\nsigned integer, a float, a boolean, a byte string and a string:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from bitstruct import *\n    \u003e\u003e\u003e pack('u5s5f32b1r13t40', 1, -1, 3.75, True, b'\\xff\\xff', 'hello')\n    b'\\x0f\\xd0\\x1c\\x00\\x00?\\xffhello'\n    \u003e\u003e\u003e unpack('u5s5f32b1r13t40', b'\\x0f\\xd0\\x1c\\x00\\x00?\\xffhello')\n    (1, -1, 3.75, True, b'\\xff\\xf8', 'hello')\n    \u003e\u003e\u003e calcsize('u5s5f32b1r13t40')\n    96\n\nThe same format string and values as in the previous example, but\nusing LSB (Least Significant Bit) first instead of the default MSB\n(Most Significant Bit) first:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from bitstruct import *\n    \u003e\u003e\u003e pack('\u003cu5s5f32b1r13t40', 1, -1, 3.75, True, b'\\xff\\xff', 'hello')\n    b'\\x87\\xc0\\x00\\x03\\x80\\xbf\\xff\\xf666\\xa6\\x16'\n    \u003e\u003e\u003e unpack('\u003cu5s5f32b1r13t40', b'\\x87\\xc0\\x00\\x03\\x80\\xbf\\xff\\xf666\\xa6\\x16')\n    (1, -1, 3.75, True, b'\\xff\\xf8', 'hello')\n    \u003e\u003e\u003e calcsize('\u003cu5s5f32b1r13t40')\n    96\n\nAn example of `unpacking`_ values from a hexstring and a binary file:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from bitstruct import *\n    \u003e\u003e\u003e from binascii import unhexlify\n    \u003e\u003e\u003e unpack('s17s13r24', unhexlify('0123456789abcdef'))\n    (582, -3751, b'\\xe2j\\xf3')\n    \u003e\u003e\u003e with open(\"test.bin\", \"rb\") as fin:\n    ...     unpack('s17s13r24', fin.read(8))\n    ...\n    ...\n    (582, -3751, b'\\xe2j\\xf3')\n\nChange endianness of the data with `byteswap`_, and then unpack the\nvalues:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from bitstruct import *\n    \u003e\u003e\u003e packed = pack('u1u3u4s16', 1, 2, 3, 1)\n    \u003e\u003e\u003e unpack('u1u3u4s16', byteswap('12', packed))\n    (1, 2, 3, 256)\n\nA basic example of `packing`_ and `unpacking`_ four integers using the\nformat string ``'u1u3u4s16'`` using the C implementation:\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from bitstruct.c import *\n    \u003e\u003e\u003e pack('u1u3u4s16', 1, 2, 3, -4)\n    b'\\xa3\\xff\\xfc'\n    \u003e\u003e\u003e unpack('u1u3u4s16', b'\\xa3\\xff\\xfc')\n    (1, 2, 3, -4)\n\nContributing\n============\n\n#. Fork the repository.\n\n#. Install prerequisites.\n\n   .. code-block:: text\n\n      pip install -r requirements.txt\n\n#. Implement the new feature or bug fix.\n\n#. Implement test case(s) to ensure that future changes do not break\n   legacy.\n\n#. Run the tests.\n\n   .. code-block:: text\n\n      make test\n\n#. Create a pull request.\n\n.. _packing: http://bitstruct.readthedocs.io/en/latest/#bitstruct.pack\n\n.. _unpacking: http://bitstruct.readthedocs.io/en/latest/#bitstruct.unpack\n\n.. _pack: http://bitstruct.readthedocs.io/en/latest/#bitstruct.CompiledFormat.pack\n\n.. _unpack: http://bitstruct.readthedocs.io/en/latest/#bitstruct.CompiledFormat.unpack\n\n.. _pack into: http://bitstruct.readthedocs.io/en/latest/#bitstruct.pack_into\n\n.. _unpack from: http://bitstruct.readthedocs.io/en/latest/#bitstruct.unpack_from\n\n.. _pack_dict: http://bitstruct.readthedocs.io/en/latest/#bitstruct.pack_dict\n\n.. _unpack_dict: http://bitstruct.readthedocs.io/en/latest/#bitstruct.unpack_dict\n\n.. _byteswap: http://bitstruct.readthedocs.io/en/latest/#bitstruct.byteswap\n\n.. _compiling: http://bitstruct.readthedocs.io/en/latest/#bitstruct.compile\n\n.. _cbitstruct: https://github.com/qchateau/cbitstruct\n\n.. _MicroPython: https://github.com/micropython/micropython\n\n.. _bitstruct-micropython: https://github.com/peterzuger/bitstruct-micropython\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feerimoq%2Fbitstruct","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feerimoq%2Fbitstruct","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feerimoq%2Fbitstruct/lists"}