Skip to content

Commit 35bc5b9

Browse files
MatrixEditorMatrixEditor
authored
[2.6.0] CAPI Compatibility and new arbitrary length reference struct
Merge pull request #42 from MatrixEditor/dev/2.6.0-rc
2 parents 5868d73 + 709902c commit 35bc5b9

176 files changed

Lines changed: 5932 additions & 14919 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@ venv-matrix/
88
# C extensions
99
*.so
1010
include/caterpillar/caterpillar.h
11+
src/ccaterpillar/caterpillarapi.c
12+
src/ccaterpillar/module.c
13+
src/ccaterpillar/private.h
1114

1215
# Distribution / packaging
1316
.Python
@@ -29,6 +32,8 @@ share/python-wheels/
2932
*.egg
3033
MANIFEST
3134
bench/
35+
pypi/
36+
caterpillarapi.h
3237

3338
# PyInstaller
3439
# Usually these files are written by a python script from a template
@@ -164,4 +169,6 @@ cython_debug/
164169
#.idea/
165170

166171
# VSCode
167-
.vscode/
172+
.vscode/
173+
Makefile
174+
.clangd

‎CHANGELOG.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,59 @@
11
# Changelog
22

3+
## [2.6.0] - Minor Release
4+
5+
### Added
6+
- **caterpillar.fields._base**
7+
- Add support for non-context lambda switch fields.
8+
9+
- **caterpillar.fields.common**
10+
- Add compatibility support for CAPI atoms in `Int`, `UInt` and `PyStructFormattedField`.
11+
12+
- **caterpillar.options**
13+
- Add custom `Flag.__eq__` implementation to support equality check with `c_Option` objects.
14+
15+
- **caterpillar.abc**
16+
- Add new typing-only `_OptionLike` protocol.
17+
- Add missing `_SupportsType` protocol to the stubs file.
18+
- Add new method `get` to the `_ContextLike` protocol.
19+
20+
- **caterpillar.context**
21+
- Add new option `O_CONTEXT_FACTORY` that controls the global context type.
22+
Value must be a method or another type implementing the `_ContextLike` protocol.
23+
- Add new global context path: `root` (exported as `G` in shortcuts).
24+
25+
- **caterpillar.shortcuts**
26+
- Add new shortcuts `C` for `ctx`, `P` for `parent` and `G` for the `root` context as `ContextPath` objects.
27+
28+
- **CAPI**
29+
- New index assignment system when generating CAPI code — a running number is now applied instead of a hard-coded index.
30+
- Add complete Context implementation in C (`c_Context`) that conforms to the `_ContextLike` protocol.
31+
- Add `Atom` for C-based struct-like classes (previously known as `catom`).
32+
- Add native support for `__bits__` in `Atom`.
33+
- Add special class `LengthInfo` for packing or unpacking multiple objects.
34+
- New builtin atoms (CAPI): `Repeated`, `Conditional` and `Switch`.
35+
- Add new shared objects and exception types to the native implementation (`Cp_ContextFactory`, `Cp_ArrayFactory`, `CpExc_Stop` and `Cp_DefaultOption`).
36+
37+
---
38+
39+
### Changed
40+
- **caterpillar.fields._base**
41+
- Rework `Field` implementation to reduce overhead when packing and unpacking elements.
42+
- Use pre-computed states instead of calculating everything on the fly; states will be adjusted automatically when setting new values (via `@property` attributes).
43+
44+
---
45+
46+
### Fixed
47+
- **caterpillar.fields.common**
48+
- Fix issue in `Prefixed` that occurred when the internal struct packs a sequence of elements.
49+
50+
---
51+
52+
### Removed
53+
- **CAPI**
54+
- Remove old CAPI and completely revamp the CAPI concept to make it compatible with the Python equivalent.
55+
56+
357
## [2.5.1] - Hot-Fix Release
458

559
### Fixed

‎CMakeLists.txt‎

Lines changed: 15 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -17,42 +17,17 @@ python_add_library(
1717
MODULE
1818

1919
src/ccaterpillar/arch.c
20-
src/ccaterpillar/atomobj.c
21-
src/ccaterpillar/context.c
2220
src/ccaterpillar/option.c
2321
src/ccaterpillar/module.c
2422
src/ccaterpillar/context.c
25-
src/ccaterpillar/state.c
26-
src/ccaterpillar/struct.c
27-
src/ccaterpillar/layer.c
28-
src/ccaterpillar/default.c
29-
30-
src/ccaterpillar/parsing_typeof.c
31-
src/ccaterpillar/parsing_sizeof.c
32-
src/ccaterpillar/parsing_pack.c
33-
src/ccaterpillar/parsing_unpack.c
34-
35-
src/ccaterpillar/atomimpl/int.c
36-
src/ccaterpillar/atomimpl/float.c
37-
src/ccaterpillar/atomimpl/bool.c
38-
src/ccaterpillar/atomimpl/char.c
39-
src/ccaterpillar/atomimpl/pad.c
40-
src/ccaterpillar/atomimpl/string.c
41-
src/ccaterpillar/atomimpl/const.c
42-
src/ccaterpillar/atomimpl/bytes.c
43-
src/ccaterpillar/atomimpl/pstring.c
44-
src/ccaterpillar/atomimpl/enum.c
45-
src/ccaterpillar/atomimpl/varint.c
46-
src/ccaterpillar/atomimpl/computed.c
47-
src/ccaterpillar/atomimpl/lazy.c
48-
src/ccaterpillar/atomimpl/cstring.c
49-
50-
src/ccaterpillar/atomimpl/builtins/builtin.c
51-
src/ccaterpillar/atomimpl/builtins/repeated.c
52-
src/ccaterpillar/atomimpl/builtins/condition.c
53-
src/ccaterpillar/atomimpl/builtins/switch.c
54-
src/ccaterpillar/atomimpl/builtins/atoffset.c
55-
src/ccaterpillar/atomimpl/builtins/primitive.c
23+
src/ccaterpillar/atom.c
24+
src/ccaterpillar/lengthinfo.c
25+
src/ccaterpillar/shared.c
26+
src/ccaterpillar/atoms/builtin/builtin.c
27+
src/ccaterpillar/atoms/builtin/repeated.c
28+
src/ccaterpillar/atoms/builtin/switch.c
29+
src/ccaterpillar/atoms/builtin/conditional.c
30+
src/ccaterpillar/atoms/builtin/offset.c
5631

5732
WITH_SOABI
5833
)
@@ -65,15 +40,20 @@ message(STATUS "Python ${Python_VERSION_MAJOR}.${Python_VERSION_MINOR}")
6540
set (CP_GENAPI_SCRIPT ${CMAKE_CURRENT_SOURCE_DIR}/src/code_gen/genapi.py)
6641
set (CP_CAPI_HEADER ${CMAKE_CURRENT_SOURCE_DIR}/src/caterpillar/include/caterpillar/caterpillarapi.h.in)
6742
set (CP_CAPI_CSRC ${CMAKE_CURRENT_SOURCE_DIR}/src/ccaterpillar/caterpillarapi.c.in)
43+
set (CP_CAPI_MOD_CSRC ${CMAKE_CURRENT_SOURCE_DIR}/src/ccaterpillar/module.c.in)
44+
set (CP_CAPI_PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/ccaterpillar/private.h.in)
45+
6846
set (CP_CAPI_HEADER_OUT ${CMAKE_CURRENT_SOURCE_DIR}/src/caterpillar/include/caterpillar/caterpillarapi.h)
6947
set (CP_CAPI_CSRC_OUT ${CMAKE_CURRENT_SOURCE_DIR}/src/ccaterpillar/caterpillarapi.c)
48+
set (CP_CAPI_MOD_CSRC_OUT ${CMAKE_CURRENT_SOURCE_DIR}/src/ccaterpillar/module.c)
49+
set (CP_CAPI_PRIVATE_OUT ${CMAKE_CURRENT_SOURCE_DIR}/src/ccaterpillar/private.h)
7050

7151
add_custom_target(
7252
genapi ALL
7353
# execute python ./src/code_gen/genapi.py ./src/caterpillar/include/caterpillar/caterpillarapi.h.in ./src/ccaterpillar/caterpillarapi.c.in
7454
# in the root directory
75-
COMMAND ${PYTHON_EXECUTABLE} ${CP_GENAPI_SCRIPT} ${CP_CAPI_HEADER} ${CP_CAPI_CSRC}
76-
BYPRODUCTS ${CP_CAPI_HEADER_OUT} ${CP_CAPI_CSRC_OUT}
55+
COMMAND ${PYTHON_EXECUTABLE} ${CP_GENAPI_SCRIPT} ${CP_CAPI_HEADER} ${CP_CAPI_CSRC} ${CP_CAPI_MOD_CSRC} ${CP_CAPI_PRIVATE}
56+
BYPRODUCTS ${CP_CAPI_HEADER_OUT} ${CP_CAPI_CSRC_OUT} ${CP_CAPI_MOD_CSRC_OUT} ${CP_CAPI_PRIVATE_OUT}
7757
COMMENT "Generating Public Caterpillar API"
7858
)
7959

‎README.md‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,6 @@
88
![GitHub License](https://img.shields.io/github/license/MatrixEditor/caterpillar?logo=github)
99

1010

11-
12-
> [!WARNING]
13-
> This project is still in beta/testing phase. Expect bugs, naming changes and errors while using this
14-
> library. C API Reference is WIP, C extensions are supported since v2.1.0. The latest stable release
15-
> is available at PyPI.
16-
1711
Caterpillar is a Python 3.12+ library to pack and unpack structurized binary data. It
1812
enhances the capabilities of [Python Struct](https://docs.python.org/3/library/struct.html)
1913
by enabling direct class declaration. More information about the different configuration
@@ -100,7 +94,7 @@ pip install caterpillar-py
10094
pip install "caterpillar[all]@git+https://github.com/MatrixEditor/caterpillar"
10195
```
10296

103-
### C-extension installation
97+
### Installation + C-extension
10498

10599
```bash
106100
pip install "caterpillar[all]@git+https://github.com/MatrixEditor/caterpillar/#subdirectory=src/ccaterpillar"

‎docs/doxygen/Doxyfile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -949,7 +949,7 @@ WARN_LOGFILE =
949949
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
950950
# Note: If this tag is empty the current directory is searched.
951951

952-
INPUT = ../../include
952+
INPUT = ../../src/caterpillar/include
953953

954954
# This tag can be used to specify the character encoding of the source files
955955
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

‎docs/sphinx/source/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515

1616
project = "Caterpillar"
1717
author = caterpillar.__author__
18-
copyright = f"2024, {author}"
18+
copyright = f"2025, {author}"
1919
release = version = caterpillar.__version__
2020

2121
# -- General configuration ---------------------------------------------------

‎docs/sphinx/source/development/changelog.rst‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,105 @@ Changelog
66

77
*More entries will be added in the future.*
88

9+
.. _changelog_2.6.0:
10+
11+
[2.6.0] - Minor Release
12+
=======================
13+
14+
Added
15+
-----
16+
17+
*caterpillar.fields._base*
18+
^^^^^^^^^^^^^^^^^^^^^^^^^^
19+
20+
- Add support for non-context lambda switch fields
21+
22+
23+
*caterpillar.fields.common*
24+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
25+
26+
- Add compatibility support for CAPI atoms in ``Int``, ``UInt`` and ``PyStructFormattedField``
27+
28+
*caterpillar.options*
29+
^^^^^^^^^^^^^^^^^^^^^
30+
31+
- Add custom ``Flag.__eq__`` implementation to support equality check with ``c_Option`` objects
32+
33+
34+
*caterpillar.abc*
35+
^^^^^^^^^^^^^^^^^
36+
37+
- Add new typing-only `_OptionLike` protocol
38+
- Add missing `_SupportsType` protocol to the stubs file
39+
- Add new method `get` to the `_ContextLike` protocol
40+
41+
42+
*caterpillar.context*
43+
^^^^^^^^^^^^^^^^^^^^^
44+
45+
- Add new option :py:attr:`~caterpillar.context.O_CONTEXT_FACTORY` that controls
46+
the global context type. Value must be a method or another type implementing
47+
the :class:`_ContextLike` protocol
48+
- Add new global context path: :py:attr:`~caterpillar.context.root` (exported as ``G`` in shortcuts)
49+
50+
*caterpillar.shortcuts*
51+
^^^^^^^^^^^^^^^^^^^^^^^
52+
53+
- Add new shortcuts ``C`` for :py:attr:`~caterpillar.context.ctx`, ``P`` for
54+
:py:attr:`~caterpillar.context.parent` and ``G`` for the
55+
:py:attr:`~caterpillar.context.root` context as
56+
:class:`~caterpillar.context.ContextPath` objects
57+
58+
59+
*CAPI*
60+
^^^^^^
61+
62+
- New index assignment system when generating CAPI code. A running number is now
63+
applied instead of a hard coded index.
64+
- Add *complete* Context implementation in C (:class:`c_Context`) that conforms
65+
to the :class:`_ContextLike` protocol.
66+
- Add :class:`Atom` for C-based struct-like classes. This class was previously
67+
known as :class:`catom`
68+
- Add native support for `__bits__` in :class:`Atom`
69+
- Add special class :class:`LengthInfo` for packing or unpacking multiple objects
70+
- New builtin atoms (CAPI): :class:`Repeated`, :class:`Conditional` and :class:`Switch`
71+
- Add new shared objects and exception types to the native implementation
72+
(:c:var:`Cp_ContextFactory`, :c:var:`Cp_ArrayFactory`, :c:var:`CpExc_Stop` and
73+
:c:var:`Cp_DefaultOption`)
74+
75+
76+
Changed
77+
-------
78+
79+
*caterpillar.fields._base*
80+
^^^^^^^^^^^^^^^^^^^^^^^^^^
81+
82+
- Rework :class:`~caterpillar.fields._base.Field` implementation to reduce
83+
overhead when packing and unpacking elements
84+
- Use pre-computed states instead of calculating everything on-the-fly. States
85+
will be adjusted when setting new values (automatically updated through
86+
:code:`@property` attributes)
87+
88+
89+
Fixed
90+
-----
91+
92+
*caterpillar.fields.common*
93+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
94+
95+
+ Fix issue in Prefixed that occurred when the internal struct packs a sequence
96+
of elements
97+
98+
Removed
99+
-------
100+
101+
*CAPI*
102+
^^^^^^
103+
104+
- Remove old CAPI and completely revamp the CAPI concept to make it compatible
105+
to the Python equivalent.
106+
107+
9108
.. _changelog_2.5.1:
10109

11110
[2.5.1] - Hot-Fix Release

0 commit comments

Comments
 (0)