| Name | bitdict JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | BitDict is a Python library for creating custom bit-packed data structures with dynamically defined substructures. |
| upload_time | 2025-02-23 19:53:09 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
bitstruct
bitfield
bitpacked
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# bitdict
[](https://github.com/Shapedsundew9/bitdict/actions/workflows/python-package.yml)
[](https://codecov.io/gh/Shapedsundew9/bitdict)
[](https://snyk.io/test/github/shapedsundew9/bitdict)
[](https://codeclimate.com/github/Shapedsundew9/bitdict/maintainability)
[](https://github.com/psf/black)
[](https://pypi.org/project/bitdict/)
BitDict is a Python library for creating custom bit-packed data structures with dynamically defined substructures. It allows you to define and manipulate data structures where individual fields occupy specific bit ranges, similar to a struct in C. This is particularly useful for parsing and generating binary data formats, representing hardware registers, and implementing data structures with specific bit-level packing requirements.
## Installation
```bash
pip install bitdict
```
## Concept and Use Case
BitDict provides a flexible way to define and interact with data structures where individual fields occupy specific bit ranges. It supports various data types, including integers (signed and unsigned), booleans, and nested BitDict instances, enabling complex data layouts to be easily managed.
### Example Use Case
Consider a scenario where you need to parse a binary data format with specific bit-level packing requirements. BitDict allows you to define the structure of this data format and provides methods to access and manipulate individual fields within the structure.
## Simple Configuration and Usage Example
Here's a simple example of how to define and use a BitDict:
```python
from bitdict import bitdict_factory
# Define the configuration for the BitDict
config = {
"enabled": {"start": 0, "width": 1, "type": "bool"},
"mode": {"start": 1, "width": 2, "type": "uint"},
"value": {"start": 3, "width": 5, "type": "int"},
}
# Create a BitDict class using the factory function
MyBitDict = bitdict_factory(config, "MyBitDict")
# Create an instance of the BitDict
bd = MyBitDict()
# Set and access bit fields
bd["enabled"] = True
bd["mode"] = 2
bd["value"] = -5
# Get the integer representation
value = bd.to_int()
print(value) # Output: 221
# Create an instance from an integer
bd2 = MyBitDict(value)
print(bd2.to_json()) # Output: {'value': -5, 'mode': 2, 'enabled': True}
```
## Configuration
The configuration for a BitDict is a dictionary that defines the structure of the bit fields. Each key in the dictionary represents a field name, and the value is another dictionary with the following keys:
- `start` (int): The starting bit position (LSB = 0).
- `width` (int): The width of the bit field in bits.
- `type` (str): The data type of the bit field. Can be one of: 'bool', 'uint', 'int', 'reserved', 'bitdict'.
- `default` (optional): The default value for the bit field. If not provided, defaults to False for 'bool', 0 for 'uint' and 'int'.
- `subtype` (list of dict, optional): Required for 'bitdict' type. Ignored for other types. A list of sub-bitdict configurations to select from based on the value of the selector property.
- `selector` (str, optional): Required for 'bitdict' type. Ignored for other types. The name of the property used to select the active sub-bitdict. This property must be of type 'bool' or 'uint' and have a width <= 16.
- `description` (str, optional): Arbitary text that is only used in `the generate_markdown_tables` documentation generation function.
- `valid` (dict, optional): A dictionary defining valid values or ranges for the bit field. Cannot be used with 'bitdict' type.
- `value` (set, optional): A set of valid values for the field. Each value must be an integer or boolean.
- `range` (list of tuples, optional): A list of valid ranges for the field. Each tuple must contain one, two or 3 integers representing the start (inclusive) and end (exclusive) of the range and the step. Note that both `value` and `range` may be defined and may overlap.
## API
### generate_markdown_tables Function
The `generate_markdown_tables` function converts a bitdict configuration dictionary into a list of markdown tables.
- `generate_markdown_tables(config: dict, include_types: bool = True) -> list[str]`: Converts a bitdict configuration dictionary into a list of markdown tables.
- `config` (dict): The bitdict configuration dictionary that needs to be converted.
- `include_types` (bool, optional): A boolean to indicate if data types should be included in the output. Defaults to True.
- Returns: A list of formatted markdown strings representing the bitdict configuration in table format.
Using the example configuration above:
```python
print(generate_markdown_tables(MyBitDict)[0])
```
returns
```markdown
## BitDict
| Name | Type | Bitfield | Default | Description |
|---|:-:|:-:|:-:|---|
| enabled | bool | 0 | False | |
| mode | uint | 2:1 | 0 | |
| value | int | 7:3 | 0 | |
```
### BitDict Class
The BitDict class provides methods to interact with the bit-packed data structure. Here are some of the key methods:
- `__getitem__(self, key: str) -> bool | int | BitDict`: Retrieves the value associated with the given key.
- `__setitem__(self, key: str, value: bool | int) -> None`: Sets the value of a property within the BitDict.
- `__len__(self) -> int`: Returns the total width of the bit dictionary, representing the number of bits it can store.
- `__contains__(self, key: str) -> bool`: Checks if a property exists within this BitDict or its selected nested BitDicts.
- `__iter__(self) -> Generator[tuple[str, bool | BitDict | int], Any, None]`: Iterates over the BitDict, yielding (name, value) pairs for each non-reserved field.
- `clear(self) -> None`: Clears the bit dictionary, setting all bits to 0.
- `reset(self) -> None`: Resets the BitDict to its default values.
- `set(self, value: int | dict[str, Any]) -> None`: Sets the value of the BitDict.
- `update(self, data: dict[str, Any]) -> None`: Updates the BitDict with values from another dictionary.
- `to_json(self) -> dict[str, Any]`: Converts the BitDict to a JSON-serializable dictionary.
- `to_bytes(self) -> bytes`: Converts the bit dictionary to a byte string.
- `to_int(self) -> int`: Returns the integer representation of the BitDict.
- `get_config(cls) -> MappingProxyType[str, Any]`: Returns the configuration settings for the BitDict class.
## Detailed Example
Here's a more detailed example that demonstrates the use of nested BitDicts and selectors:
```python
from bitdict import bitdict_factory
# Define the configuration for the BitDict
config = {
"Constant": {"start": 7, "width": 1, "type": "bool"},
"Mode": {"start": 6, "width": 1, "type": "bool"},
"Reserved": {"start": 4, "width": 2, "type": "uint"},
"SubValue": {
"start": 0,
"width": 4,
"type": "bitdict",
"selector": "Mode",
"subtype": [
{
"PropA": {"start": 0, "width": 2, "type": "uint", "default": 0},
"PropB": {"start": 2, "width": 2, "type": "int", "default": -1},
},
{
"PropC": {"start": 0, "width": 3, "type": "uint", "default": 1},
"PropD": {"start": 3, "width": 1, "type": "bool", "default": True},
},
],
},
}
# Create a BitDict class using the factory function
MyBitDict = bitdict_factory(config, "MyBitDict")
# Create an instance of the BitDict
bd = MyBitDict()
# Set and access bit fields
bd["Constant"] = True
bd["Mode"] = False
bd["SubValue"]["PropA"] = 2
bd["SubValue"]["PropB"] = -1
# Get the integer representation
value = bd.to_int()
print(value) # Output: 142
# Create an instance from an integer
bd2 = MyBitDict(value)
print(
bd2.to_json()
) # Output: {'Constant': True, 'Mode': False, 'SubValue': {'PropB': -1, 'PropA': 2}}
# Change the mode and access the new sub-bitdict
bd["Mode"] = True
bd["SubValue"]["PropC"] = 5
bd["SubValue"]["PropD"] = False
# Get the updated integer representation
value = bd.to_int()
print(value) # Output: 197
# Create an instance from the updated integer
bd3 = MyBitDict(value)
print(
bd3.to_json()
) # Output: {'Constant': True, 'Mode': True, 'SubValue': {'PropD': False, 'PropC': 5}}
```
This example demonstrates how to define a BitDict with nested sub-bitdicts and selectors, set and access bit fields, and convert the BitDict to and from its integer representation.
Executing
```python
print('\n\n'.join(generate_markdown_tables(MyBitDict)))
```
Generates the following markdown.
```markdown
## BitDict
| Name | Type | Bitfield | Default | Description |
|---|:-:|:-:|:-:|---|
| SubValue | bitdict | 3:0 | N/A | See 'SubValue' definition table(s). |
| Reserved | uint | 5:4 | 0 | |
| Mode | bool | 6 | False | |
| Constant | bool | 7 | False | |
## SubValue: Mode = 0
| Name | Type | Bitfield | Default | Description |
|---|:-:|:-:|:-:|---|
| PropA | uint | 1:0 | 0 | |
| PropB | int | 3:2 | -1 | |
## SubValue: Mode = 1
| Name | Type | Bitfield | Default | Description |
|---|:-:|:-:|:-:|---|
| PropC | uint | 2:0 | 1 | |
| PropD | bool | 3 | True | |
```
## FAQ
**Question**: What value does a bitfield have when the selector value is changed?
**Answer**: _When the selector value is changed, the bitfield associated with the selector is reset to its default value._
**Question**: Can you have a bitfield property with the same name as another bitfields property?
**Answer**: _No, you cannot have a bitfield property with the same name as another bitfield's property within the same BitDict configuration. Each property name within a BitDict configuration must be unique to avoid conflicts and ensure that each bitfield can be correctly identified and accessed._
**Question**: What value does an undefined bitfield have i.e. the bits that are between the defined properties?
**Answer**: _Undefined bitfields, or the bits that are between the defined properties, are typically set to 0 by default. This ensures that any gaps between defined bitfields do not contain arbitrary or undefined values. This behavior is consistent with the initialization and reset methods in the `BitDict` class, which set all bits to 0 unless specified otherwise._
Raw data
{
"_id": null,
"home_page": null,
"name": "bitdict",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "bitstruct, bitfield, bitpacked",
"author": null,
"author_email": "Shaped Sundew <shapedsundew9@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d8/6b/4ee29032470cd4fcc262fe340fff8f7dc758ec4f8edf1c52c0c15138e75a/bitdict-1.0.0.tar.gz",
"platform": null,
"description": "# bitdict\n\n[](https://github.com/Shapedsundew9/bitdict/actions/workflows/python-package.yml)\n[](https://codecov.io/gh/Shapedsundew9/bitdict)\n[](https://snyk.io/test/github/shapedsundew9/bitdict)\n[](https://codeclimate.com/github/Shapedsundew9/bitdict/maintainability)\n\n[](https://github.com/psf/black)\n[](https://pypi.org/project/bitdict/)\n\nBitDict is a Python library for creating custom bit-packed data structures with dynamically defined substructures. It allows you to define and manipulate data structures where individual fields occupy specific bit ranges, similar to a struct in C. This is particularly useful for parsing and generating binary data formats, representing hardware registers, and implementing data structures with specific bit-level packing requirements.\n\n## Installation\n\n```bash\npip install bitdict\n```\n\n## Concept and Use Case\n\nBitDict provides a flexible way to define and interact with data structures where individual fields occupy specific bit ranges. It supports various data types, including integers (signed and unsigned), booleans, and nested BitDict instances, enabling complex data layouts to be easily managed.\n\n### Example Use Case\n\nConsider a scenario where you need to parse a binary data format with specific bit-level packing requirements. BitDict allows you to define the structure of this data format and provides methods to access and manipulate individual fields within the structure.\n\n## Simple Configuration and Usage Example\n\nHere's a simple example of how to define and use a BitDict:\n\n```python\nfrom bitdict import bitdict_factory\n\n# Define the configuration for the BitDict\nconfig = {\n \"enabled\": {\"start\": 0, \"width\": 1, \"type\": \"bool\"},\n \"mode\": {\"start\": 1, \"width\": 2, \"type\": \"uint\"},\n \"value\": {\"start\": 3, \"width\": 5, \"type\": \"int\"},\n}\n\n# Create a BitDict class using the factory function\nMyBitDict = bitdict_factory(config, \"MyBitDict\")\n\n# Create an instance of the BitDict\nbd = MyBitDict()\n\n# Set and access bit fields\nbd[\"enabled\"] = True\nbd[\"mode\"] = 2\nbd[\"value\"] = -5\n\n# Get the integer representation\nvalue = bd.to_int()\nprint(value) # Output: 221\n\n# Create an instance from an integer\nbd2 = MyBitDict(value)\nprint(bd2.to_json()) # Output: {'value': -5, 'mode': 2, 'enabled': True}\n```\n\n## Configuration\n\nThe configuration for a BitDict is a dictionary that defines the structure of the bit fields. Each key in the dictionary represents a field name, and the value is another dictionary with the following keys:\n\n- `start` (int): The starting bit position (LSB = 0).\n- `width` (int): The width of the bit field in bits.\n- `type` (str): The data type of the bit field. Can be one of: 'bool', 'uint', 'int', 'reserved', 'bitdict'.\n- `default` (optional): The default value for the bit field. If not provided, defaults to False for 'bool', 0 for 'uint' and 'int'.\n- `subtype` (list of dict, optional): Required for 'bitdict' type. Ignored for other types. A list of sub-bitdict configurations to select from based on the value of the selector property.\n- `selector` (str, optional): Required for 'bitdict' type. Ignored for other types. The name of the property used to select the active sub-bitdict. This property must be of type 'bool' or 'uint' and have a width <= 16.\n- `description` (str, optional): Arbitary text that is only used in `the generate_markdown_tables` documentation generation function.\n- `valid` (dict, optional): A dictionary defining valid values or ranges for the bit field. Cannot be used with 'bitdict' type.\n - `value` (set, optional): A set of valid values for the field. Each value must be an integer or boolean.\n - `range` (list of tuples, optional): A list of valid ranges for the field. Each tuple must contain one, two or 3 integers representing the start (inclusive) and end (exclusive) of the range and the step. Note that both `value` and `range` may be defined and may overlap.\n\n## API\n\n### generate_markdown_tables Function\n\nThe `generate_markdown_tables` function converts a bitdict configuration dictionary into a list of markdown tables.\n\n- `generate_markdown_tables(config: dict, include_types: bool = True) -> list[str]`: Converts a bitdict configuration dictionary into a list of markdown tables.\n - `config` (dict): The bitdict configuration dictionary that needs to be converted.\n - `include_types` (bool, optional): A boolean to indicate if data types should be included in the output. Defaults to True.\n - Returns: A list of formatted markdown strings representing the bitdict configuration in table format.\n\nUsing the example configuration above:\n\n```python\nprint(generate_markdown_tables(MyBitDict)[0])\n```\n\nreturns\n\n```markdown\n## BitDict\n\n| Name | Type | Bitfield | Default | Description |\n|---|:-:|:-:|:-:|---|\n| enabled | bool | 0 | False | |\n| mode | uint | 2:1 | 0 | |\n| value | int | 7:3 | 0 | |\n```\n\n### BitDict Class\n\nThe BitDict class provides methods to interact with the bit-packed data structure. Here are some of the key methods:\n\n- `__getitem__(self, key: str) -> bool | int | BitDict`: Retrieves the value associated with the given key.\n- `__setitem__(self, key: str, value: bool | int) -> None`: Sets the value of a property within the BitDict.\n- `__len__(self) -> int`: Returns the total width of the bit dictionary, representing the number of bits it can store.\n- `__contains__(self, key: str) -> bool`: Checks if a property exists within this BitDict or its selected nested BitDicts.\n- `__iter__(self) -> Generator[tuple[str, bool | BitDict | int], Any, None]`: Iterates over the BitDict, yielding (name, value) pairs for each non-reserved field.\n- `clear(self) -> None`: Clears the bit dictionary, setting all bits to 0.\n- `reset(self) -> None`: Resets the BitDict to its default values.\n- `set(self, value: int | dict[str, Any]) -> None`: Sets the value of the BitDict.\n- `update(self, data: dict[str, Any]) -> None`: Updates the BitDict with values from another dictionary.\n- `to_json(self) -> dict[str, Any]`: Converts the BitDict to a JSON-serializable dictionary.\n- `to_bytes(self) -> bytes`: Converts the bit dictionary to a byte string.\n- `to_int(self) -> int`: Returns the integer representation of the BitDict.\n- `get_config(cls) -> MappingProxyType[str, Any]`: Returns the configuration settings for the BitDict class.\n\n## Detailed Example\n\nHere's a more detailed example that demonstrates the use of nested BitDicts and selectors:\n\n```python\nfrom bitdict import bitdict_factory\n\n# Define the configuration for the BitDict\nconfig = {\n \"Constant\": {\"start\": 7, \"width\": 1, \"type\": \"bool\"},\n \"Mode\": {\"start\": 6, \"width\": 1, \"type\": \"bool\"},\n \"Reserved\": {\"start\": 4, \"width\": 2, \"type\": \"uint\"},\n \"SubValue\": {\n \"start\": 0,\n \"width\": 4,\n \"type\": \"bitdict\",\n \"selector\": \"Mode\",\n \"subtype\": [\n {\n \"PropA\": {\"start\": 0, \"width\": 2, \"type\": \"uint\", \"default\": 0},\n \"PropB\": {\"start\": 2, \"width\": 2, \"type\": \"int\", \"default\": -1},\n },\n {\n \"PropC\": {\"start\": 0, \"width\": 3, \"type\": \"uint\", \"default\": 1},\n \"PropD\": {\"start\": 3, \"width\": 1, \"type\": \"bool\", \"default\": True},\n },\n ],\n },\n}\n\n# Create a BitDict class using the factory function\nMyBitDict = bitdict_factory(config, \"MyBitDict\")\n\n# Create an instance of the BitDict\nbd = MyBitDict()\n\n# Set and access bit fields\nbd[\"Constant\"] = True\nbd[\"Mode\"] = False\nbd[\"SubValue\"][\"PropA\"] = 2\nbd[\"SubValue\"][\"PropB\"] = -1\n\n# Get the integer representation\nvalue = bd.to_int()\nprint(value) # Output: 142\n\n# Create an instance from an integer\nbd2 = MyBitDict(value)\nprint(\n bd2.to_json()\n) # Output: {'Constant': True, 'Mode': False, 'SubValue': {'PropB': -1, 'PropA': 2}}\n\n# Change the mode and access the new sub-bitdict\nbd[\"Mode\"] = True\nbd[\"SubValue\"][\"PropC\"] = 5\nbd[\"SubValue\"][\"PropD\"] = False\n\n# Get the updated integer representation\nvalue = bd.to_int()\nprint(value) # Output: 197\n\n# Create an instance from the updated integer\nbd3 = MyBitDict(value)\nprint(\n bd3.to_json()\n) # Output: {'Constant': True, 'Mode': True, 'SubValue': {'PropD': False, 'PropC': 5}}\n```\n\nThis example demonstrates how to define a BitDict with nested sub-bitdicts and selectors, set and access bit fields, and convert the BitDict to and from its integer representation.\n\nExecuting\n\n```python\nprint('\\n\\n'.join(generate_markdown_tables(MyBitDict)))\n```\n\nGenerates the following markdown.\n\n```markdown\n## BitDict\n\n| Name | Type | Bitfield | Default | Description |\n|---|:-:|:-:|:-:|---|\n| SubValue | bitdict | 3:0 | N/A | See 'SubValue' definition table(s). |\n| Reserved | uint | 5:4 | 0 | |\n| Mode | bool | 6 | False | |\n| Constant | bool | 7 | False | |\n\n## SubValue: Mode = 0\n\n| Name | Type | Bitfield | Default | Description |\n|---|:-:|:-:|:-:|---|\n| PropA | uint | 1:0 | 0 | |\n| PropB | int | 3:2 | -1 | |\n\n## SubValue: Mode = 1\n\n| Name | Type | Bitfield | Default | Description |\n|---|:-:|:-:|:-:|---|\n| PropC | uint | 2:0 | 1 | |\n| PropD | bool | 3 | True | |\n```\n\n## FAQ\n\n**Question**: What value does a bitfield have when the selector value is changed?\n**Answer**: _When the selector value is changed, the bitfield associated with the selector is reset to its default value._\n\n**Question**: Can you have a bitfield property with the same name as another bitfields property?\n**Answer**: _No, you cannot have a bitfield property with the same name as another bitfield's property within the same BitDict configuration. Each property name within a BitDict configuration must be unique to avoid conflicts and ensure that each bitfield can be correctly identified and accessed._\n\n**Question**: What value does an undefined bitfield have i.e. the bits that are between the defined properties?\n**Answer**: _Undefined bitfields, or the bits that are between the defined properties, are typically set to 0 by default. This ensures that any gaps between defined bitfields do not contain arbitrary or undefined values. This behavior is consistent with the initialization and reset methods in the `BitDict` class, which set all bits to 0 unless specified otherwise._\n",
"bugtrack_url": null,
"license": null,
"summary": "BitDict is a Python library for creating custom bit-packed data structures with dynamically defined substructures.",
"version": "1.0.0",
"project_urls": {
"Changelog": "https://github.com/Shapedsundew9/bitdict/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/Shapedsundew9/bitdict/blob/main/README.md",
"Homepage": "https://github.com/Shapedsundew9/bitdict",
"Issues": "https://github.com/Shapedsundew9/bitdict/issues",
"Repository": "https://github.com/Shapedsundew9/bitdict"
},
"split_keywords": [
"bitstruct",
" bitfield",
" bitpacked"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "53468a644c17d940b12aec19fea6879b060f7914f76829dae336ff81c45cb432",
"md5": "d9a0dd155ae5af94f8a7142f5ba56083",
"sha256": "e492fc6e04820cb6a3f975dc4b27ee74a4aadf27dfca507fe41d7661b9768c62"
},
"downloads": -1,
"filename": "bitdict-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d9a0dd155ae5af94f8a7142f5ba56083",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 18629,
"upload_time": "2025-02-23T19:53:06",
"upload_time_iso_8601": "2025-02-23T19:53:06.852906Z",
"url": "https://files.pythonhosted.org/packages/53/46/8a644c17d940b12aec19fea6879b060f7914f76829dae336ff81c45cb432/bitdict-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d86b4ee29032470cd4fcc262fe340fff8f7dc758ec4f8edf1c52c0c15138e75a",
"md5": "432dc2d13492a6cf2f837b5cd9cb8790",
"sha256": "a45fb077737d3b068238569cb70b567e1ae0e9aefe2539516bba84113d7f33e1"
},
"downloads": -1,
"filename": "bitdict-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "432dc2d13492a6cf2f837b5cd9cb8790",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 31661,
"upload_time": "2025-02-23T19:53:09",
"upload_time_iso_8601": "2025-02-23T19:53:09.631148Z",
"url": "https://files.pythonhosted.org/packages/d8/6b/4ee29032470cd4fcc262fe340fff8f7dc758ec4f8edf1c52c0c15138e75a/bitdict-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-23 19:53:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Shapedsundew9",
"github_project": "bitdict",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "bitdict"
}
