# bitstruct-annotated - Annotate fields with bitstruct un/packing instructions
This package provides metadata classes that can be used to annotate fields with
un/packing instructions for the [bitstruct](https://github.com/eerimoq/bitstruct)
package. In particular, this package is intended to be used in conjunction with
either [`dataclasses`](https://docs.python.org/3/library/dataclasses.html) or
Pydantic's [`BaseModel`](https://pydantic-docs.helpmanual.io/usage/models/).
Besides metadata classes for each format type supported by `bitstruct`, this
package also provides a metadata class to indicate nested structures.
Functions are provided to un/pack instances by calling `bitstruct` with the
format string, that is assembled from the metadata annotations.
## Installation
`bitstruct-annotated` can be installed from PyPI using pip:
```bash
pip install bitstruct-annotated
```
## Usage
The metadata classes provided by this package can be used in conjunction with
Python's built-in
[`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated)
type annotation:
```python
from dataclasses import dataclass
from typing import Annotated
import bitstruct_annotated as ba
@dataclass
class MyDataClass:
other_field: int
integer_field: Annotated[int, ba.Unsigned(size=8, msb_first=True)]
padding_field: Annotated[int, ba.PaddingZeros(size=7, order='first')]
boolean_field: Annotated[bool, ba.Bool(size=1, order='after:padding_field')]
mdc = MyDataClass(12, 34, 0, True)
packed = ba.pack(mdc)
# packed == b'\x01\x22'
```
In the example above, `Annotated` is used to include the un/packing
instructions as additional metadata in the field's type annotations. Fields
without annotation are ignored by the `bitstruct_annotated.pack` and
`bitstruct_annotated.unpack` functions.
While the `size` argument indicates the numbers of bits to be used for the field,
the `order` argument indicates the order in which the fields should be packed.
Here, the `padding_field` will be packed first, followed by the `boolean_field`.
The `msb_first` argument (default is `True`) can be set to `False` to reverse the
bit order of a field. Currently, the `bitstruct` package does not support alternate
byte orders. If required, the user has to swap bytes after packing by themselves.
The `bitstruct_annotated.format_string` function can be used to generate and
inspect the resulting bitstruct format string. To obtain values to be packed
from an instance, the `bitstruct_annotated.field_values` function can be used:
```python
# ... continued from the previous example
format_string = ba.format_string(MyDataClass)
# format_string == '>p7b1u8'
values = ba.field_values(mdc)
# values == (True, 34)
```
A similar example using Pydantic's `BaseModel`:
```python
from pydantic import BaseModel
from typing import Annotated
import bitstruct_annotated as ba
class MyPydanticModel(BaseModel):
other_field: int
integer_field: Annotated[int, ba.Unsigned(size=8, msb_first=True)]
padding_field: Annotated[int, ba.PaddingZeros(size=7, order='first')]
boolean_field: Annotated[bool, ba.Bool(size=1, order='after:padding_field')]
m = MyPydanticModel(other_field=0, integer_field=34, padding_field=0, boolean_field=True)
packed = ba.pack(m)
# packed == b'\x01\x22'
```
The following metadata classes are provided by this package:
- `Bool`: Boolean field.
- `Float`: To be used for floating-point field.
- `PaddingOnes`: A padding field filled with ones.
- `PaddingZeros`: A padding field filled with zeros.
- `Raw`: Contains raw data (bytes).
- `Signed`: Signed integer field.
- `Text`: Used for text fields (strings).
- `Unsigned`: Unsigned integer field.
- `Nested`: Nested structure - `bitstruct_annotated` will recurse into the
field's type to look for additional annotations.
The following functions are provided by this package:
- `format_string`: Generate a bitstruct format string from a class.
- `field_values`: Extract values from an instance to be packed.
- `pack`: Pack an instance into a byte string.
- `unpack`: Unpack a byte string into an instance.
Note that the instance has to have been initialized first when unpacking.
This is necessary, because the `bitstruct_annotated.unpack` function does
not make any assumptions about the class' constructor.
For further information, refer to the docstrings of the functions and metadata
classes.
## Contributing
Currently, this project does not accept contributions.
Raw data
{
"_id": null,
"home_page": null,
"name": "bitstruct-annotated",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "bitstruct, struct, annotated, packing, serialization",
"author": null,
"author_email": "Oliver Kleinke <oliver.kleinke@c-01a.de>",
"download_url": "https://files.pythonhosted.org/packages/9b/17/7f8c46cc2eaf90a6117e5258854f975982df6fc1943caa639169e3f5362b/bitstruct_annotated-0.1.2.tar.gz",
"platform": null,
"description": "# bitstruct-annotated - Annotate fields with bitstruct un/packing instructions\n\nThis package provides metadata classes that can be used to annotate fields with\nun/packing instructions for the [bitstruct](https://github.com/eerimoq/bitstruct)\npackage. In particular, this package is intended to be used in conjunction with\neither [`dataclasses`](https://docs.python.org/3/library/dataclasses.html) or\nPydantic's [`BaseModel`](https://pydantic-docs.helpmanual.io/usage/models/).\n\nBesides metadata classes for each format type supported by `bitstruct`, this\npackage also provides a metadata class to indicate nested structures.\n\nFunctions are provided to un/pack instances by calling `bitstruct` with the\nformat string, that is assembled from the metadata annotations.\n\n## Installation\n\n`bitstruct-annotated` can be installed from PyPI using pip:\n\n```bash\npip install bitstruct-annotated\n```\n\n## Usage\n\nThe metadata classes provided by this package can be used in conjunction with\nPython's built-in\n[`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated) \ntype annotation:\n\n```python\nfrom dataclasses import dataclass\nfrom typing import Annotated\nimport bitstruct_annotated as ba\n\n@dataclass\nclass MyDataClass:\n other_field: int\n integer_field: Annotated[int, ba.Unsigned(size=8, msb_first=True)]\n padding_field: Annotated[int, ba.PaddingZeros(size=7, order='first')]\n boolean_field: Annotated[bool, ba.Bool(size=1, order='after:padding_field')]\n\nmdc = MyDataClass(12, 34, 0, True)\npacked = ba.pack(mdc)\n# packed == b'\\x01\\x22'\n```\n\nIn the example above, `Annotated` is used to include the un/packing\ninstructions as additional metadata in the field's type annotations. Fields\nwithout annotation are ignored by the `bitstruct_annotated.pack` and\n`bitstruct_annotated.unpack` functions.\n\nWhile the `size` argument indicates the numbers of bits to be used for the field,\nthe `order` argument indicates the order in which the fields should be packed.\nHere, the `padding_field` will be packed first, followed by the `boolean_field`.\n\nThe `msb_first` argument (default is `True`) can be set to `False` to reverse the\nbit order of a field. Currently, the `bitstruct` package does not support alternate\nbyte orders. If required, the user has to swap bytes after packing by themselves.\n\nThe `bitstruct_annotated.format_string` function can be used to generate and\ninspect the resulting bitstruct format string. To obtain values to be packed\nfrom an instance, the `bitstruct_annotated.field_values` function can be used:\n\n```python\n# ... continued from the previous example\nformat_string = ba.format_string(MyDataClass)\n# format_string == '>p7b1u8'\nvalues = ba.field_values(mdc)\n# values == (True, 34)\n```\n\nA similar example using Pydantic's `BaseModel`:\n\n```python\nfrom pydantic import BaseModel\nfrom typing import Annotated\nimport bitstruct_annotated as ba\n\nclass MyPydanticModel(BaseModel):\n other_field: int\n integer_field: Annotated[int, ba.Unsigned(size=8, msb_first=True)]\n padding_field: Annotated[int, ba.PaddingZeros(size=7, order='first')]\n boolean_field: Annotated[bool, ba.Bool(size=1, order='after:padding_field')]\n\n\nm = MyPydanticModel(other_field=0, integer_field=34, padding_field=0, boolean_field=True)\npacked = ba.pack(m)\n# packed == b'\\x01\\x22'\n```\n\nThe following metadata classes are provided by this package:\n- `Bool`: Boolean field.\n- `Float`: To be used for floating-point field.\n- `PaddingOnes`: A padding field filled with ones.\n- `PaddingZeros`: A padding field filled with zeros.\n- `Raw`: Contains raw data (bytes).\n- `Signed`: Signed integer field.\n- `Text`: Used for text fields (strings).\n- `Unsigned`: Unsigned integer field.\n- `Nested`: Nested structure - `bitstruct_annotated` will recurse into the\n field's type to look for additional annotations.\n\nThe following functions are provided by this package:\n- `format_string`: Generate a bitstruct format string from a class.\n- `field_values`: Extract values from an instance to be packed.\n- `pack`: Pack an instance into a byte string.\n- `unpack`: Unpack a byte string into an instance.\n\nNote that the instance has to have been initialized first when unpacking.\nThis is necessary, because the `bitstruct_annotated.unpack` function does\nnot make any assumptions about the class' constructor.\n\nFor further information, refer to the docstrings of the functions and metadata\nclasses.\n\n## Contributing\n\nCurrently, this project does not accept contributions.\n",
"bugtrack_url": null,
"license": null,
"summary": "Annotate fields with bitstruct un/packing instructions",
"version": "0.1.2",
"project_urls": null,
"split_keywords": [
"bitstruct",
" struct",
" annotated",
" packing",
" serialization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2089cdd958ab83609b231d968bcfbd37a538f6402a249bd7c17fc0ef210db0e0",
"md5": "d8ba009e313af9b67e136081dd782dd0",
"sha256": "542e448c4842fa0702cf52fc9220ac4e0f0b0bde5ad9bddd9c8391010b6b636d"
},
"downloads": -1,
"filename": "bitstruct_annotated-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8ba009e313af9b67e136081dd782dd0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19217,
"upload_time": "2025-01-01T14:40:23",
"upload_time_iso_8601": "2025-01-01T14:40:23.603933Z",
"url": "https://files.pythonhosted.org/packages/20/89/cdd958ab83609b231d968bcfbd37a538f6402a249bd7c17fc0ef210db0e0/bitstruct_annotated-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9b177f8c46cc2eaf90a6117e5258854f975982df6fc1943caa639169e3f5362b",
"md5": "5d3cac35dac2923021d1af69d95e56bf",
"sha256": "ab46fa8ea98e05abad0903fa70194701228019a4391283df60fbdc83837ebc10"
},
"downloads": -1,
"filename": "bitstruct_annotated-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "5d3cac35dac2923021d1af69d95e56bf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 23214,
"upload_time": "2025-01-01T14:40:24",
"upload_time_iso_8601": "2025-01-01T14:40:24.939689Z",
"url": "https://files.pythonhosted.org/packages/9b/17/7f8c46cc2eaf90a6117e5258854f975982df6fc1943caa639169e3f5362b/bitstruct_annotated-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-01 14:40:24",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "bitstruct-annotated"
}
JSON