You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[](https://github.com/MatrixEditor/caterpillar/actions/workflows/python-sphinx.yml)
> This project is still in beta/testing phase. Expect bugs, naming changes and errors while using this
13
-
> library. C API Reference is WIP, C extensions are supported since v2.1.0.
14
-
15
-
> [!NOTE]
16
-
> Python 3.14 breaks `with` statements in class definitions since `__annotations__` are added at the end
17
-
> of a class definition. Therefore, `Digest` and conditional statements **ARE NOT SUPPORTED** in using the `with` syntax Python 3.14+.
18
-
> As of version `2.4.5` the `Digest` class has a counterpart (`DigestField`), which can be used to manually specify a digest without
19
-
> the need of a `ẁith` statement.
20
-
21
-
14
+
> library. C API Reference is WIP, C extensions are supported since v2.1.0. The latest stable release
15
+
> is available at PyPI.
22
16
23
17
Caterpillar is a Python 3.12+ library to pack and unpack structurized binary data. It
24
18
enhances the capabilities of [Python Struct](https://docs.python.org/3/library/struct.html)
@@ -27,7 +21,7 @@ options will be added in the future. Documentation is [here >](https://matrixedi
27
21
28
22
*Caterpillar* is able to:
29
23
30
-
* Pack and unpack data just from processing Python class definitions (including support for bitfields, c++-like templates and c-like unions!),
24
+
* Pack and unpack data just from processing Python class definitions (including support for powerful bitfields, c++-like templates and c-like unions!),
31
25
* apply a wide range of data types (with endianess and architecture configuration),
32
26
* dynamically adapt structs based on their inheritance layout,
33
27
* reduce the used memory space using `__slots__`,
@@ -36,36 +30,52 @@ options will be added in the future. Documentation is [here >](https://matrixedi
36
30
* it helps you to create cleaner and more compact code.
37
31
* You can even extend Caterpillar and write your parsing logic in C or C++!!
38
32
33
+
> [!NOTE]
34
+
> Python 3.14 breaks `with` statements in class definitions since `__annotations__` are added at the end
35
+
> of a class definition. Therefore, `Digest` and conditional statements **ARE NOT SUPPORTED** using the `with` syntax in Python 3.14+.
36
+
> As of version `2.4.5` the `Digest` class has a counterpart (`DigestField`), which can be used to manually specify a digest without
37
+
> the need of a `ẁith` statement.
38
+
39
+
39
40
## Give me some code!
40
41
41
42
```python
42
-
from caterpillar.py import*
43
+
@bitfield(order=LittleEndian)
44
+
classHeader:
45
+
version : 4# 4bit integer
46
+
valid : 1# 1bit flag (boolean)
47
+
ident : (8, CharFactory) # 8bit char
48
+
# automatic alignment to 16bits
43
49
44
50
@struct(order=LittleEndian)
45
51
classFormat:
46
-
magic: b"ITS MAGIC"# Supports string and byte constants directly
47
-
a: uint8 # Primitive data types
48
-
b: int32
49
-
length: uint8 # String fields with computed lengths
50
-
name: String(this.length) # -> you can also use Prefixed(uint8)
51
-
52
-
# wraps all following fields and creates a new attr
53
-
# only for Python <= 3.13
54
-
with Md5(name="hash", verify=True):
55
-
# Sequences with prefixed, computed lengths
56
-
names: CString[uint8::]
52
+
magic : b"ITS MAGIC"# Supports string and byte constants directly
53
+
header : Header
54
+
a : uint8 # Primitive data types
55
+
b : int32
56
+
length : uint8 # String fields with computed lengths
57
+
name : String(this.length) # -> you can also use Prefixed(uint8)
57
58
59
+
_hash_begin : DigestField.begin("hash", Md5_Algo) # custom actions, e.g. for hashes
60
+
names : CString[uint8::] # Sequences with prefixed, computed lengths
61
+
hash : Md5_Field("hash", verify=True) =None# automatic hash creation and verification + default value
58
62
59
63
# Instantiation (keyword-only arguments, magic is auto-inferred):
Copy file name to clipboardExpand all lines: docs/sphinx/source/development/changelog.rst
+106-1Lines changed: 106 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,4 +4,109 @@
4
4
Changelog
5
5
*********
6
6
7
-
*Entries will be added in the future.*
7
+
*More entries will be added in the future.*
8
+
9
+
.. _changelog_2.5.0:
10
+
11
+
[2.5.0] - Minor Release
12
+
=======================
13
+
14
+
This version introduces massive changes due to the addition of stub files. Most of the type hints in the Python
15
+
file are ported into several stub files. Additionally, the bitfield concept was completely renewed to be more
16
+
flexible and dynamic.
17
+
18
+
Added
19
+
-----
20
+
21
+
*caterpillar.abc*
22
+
^^^^^^^^^^^^^^^^^
23
+
24
+
- :class:`_SupportsBits` protocol
25
+
- :class:`_ContainsBits` protocol
26
+
- :class:`_SupportsType` protocol
27
+
28
+
*caterpillar.shortcuts*
29
+
^^^^^^^^^^^^^^^^^^^^^^^
30
+
31
+
- New shortcuts: :func:`typeof`, :func:`to_struct`, :func:`hasstruct`, :func:`getstruct` and :func:`sizeof`
32
+
33
+
*caterpillar.shared*
34
+
^^^^^^^^^^^^^^^^^^^^
35
+
36
+
- New constants from other modules: :attr:`ATTR_BYTEORDER`, :attr:`ATTR_TYPE`, :attr:`ATTR_BITS`, :attr:`ATTR_SIGNED`, :attr:`ATTR_TEMPLATE`
37
+
38
+
*caterpillar.context*
39
+
^^^^^^^^^^^^^^^^^^^^^
40
+
41
+
- New context attribute: `_root` can be set to point to the root context instance. Internally, instead of a for-loop that iterates through parent context instances, a simple :code:`self.get(...)` call is made.
42
+
43
+
.. raw:: html
44
+
45
+
<hr>
46
+
47
+
Removed
48
+
-------
49
+
50
+
*caterpillar.abc*
51
+
^^^^^^^^^^^^^^^^^
52
+
53
+
- ``_Action`` protocol and create two separate Protocols that form::
- Unused ``__fmt__`` function in :class:`Transformer`
69
+
70
+
.. raw:: html
71
+
72
+
<hr>
73
+
74
+
Changed
75
+
-------
76
+
77
+
*caterpillar.abc*
78
+
^^^^^^^^^^^^^^^^^
79
+
80
+
- Rename ``_Switch`` protocol to :attr:`_SwitchLike`
81
+
- Move the following attributes and methods into *caterpillar.shared*: rename ``STRUCT_FIELD`` to :attr:`ATTR_STRUCT`, :func:`hasstruct`, :func:`getstruct` and :func:`typeof`
82
+
83
+
*caterpillar.byteorder*
84
+
^^^^^^^^^^^^^^^^^^^^^^^
85
+
86
+
- Move ``BYTEORDER_FIELD`` to *caterpillar.shared* as :attr:`ATTR_BYTEORDER`
87
+
88
+
89
+
*caterpillar.model*
90
+
^^^^^^^^^^^^^^^^^^^
91
+
92
+
- :func:`sizeof` now checks if the provided object implements the :class:`_SupportsSize` protocol
93
+
- New :class:`Bitfield` concept with enhanced syntax
94
+
95
+
96
+
*Documentation*
97
+
^^^^^^^^^^^^^^^
98
+
99
+
- Update reference and library docs as well as section numbering
100
+
101
+
.. raw:: html
102
+
103
+
<hr>
104
+
105
+
Fixed
106
+
-----
107
+
108
+
*caterpillar.model*
109
+
^^^^^^^^^^^^^^^^^^^
110
+
111
+
- when parsing union objects with an unbound stream object
112
+
- field options defined in Sequences and Structs were not populated when creating fields.
0 commit comments