MatrixEditor · MatrixEditor · Jun 29, 2025 · Jun 24, 2025 · Jun 24, 2025 · Jun 24, 2025
diff --git a/.github/workflows/python-test.yml b/.github/workflows/python-test.yml
@@ -9,7 +9,7 @@ jobs:
       fail-fast: true
       matrix:
         os: ["ubuntu-latest", "windows-latest", "macos-latest"]
-        python-version: ["3.12"]
+        python-version: ["3.12", "3.13"]
 
     steps:
       - name: Checkout source

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,56 @@
+# Changelog
+
+## [2.5.0] - Minor Release
+
+### Added
+- **caterpillar.abc**
+  - Add `_SupportsBits` protocol.
+  - Add `_ContainsBits` protocol.
+  - Add `_SupportsType` protocol.
+
+- **caterpillar.shortcuts**
+  - Add new shortcuts: `typeof`, `to_struct`, `hasstruct`, `getstruct`, and `sizeof`.
+
+- **caterpillar.shared**
+  - Add new constants from other modules: `ATTR_BYTEORDER`, `ATTR_TYPE`, `ATTR_BITS`, `ATTR_SIGNED`, `ATTR_TEMPLATE`.
+
+- **caterpillar.context**
+  - Add context attribute `_root` to point to the root context instance. Internal parent iteration now uses `self.get(...)`.
+
+---
+
+### Removed
+- **caterpillar.abc**
+  - Remove `_Action` protocol; split into `_ActionLike = _SupportsActionUnpack | _SupportsActionPack`.
+  - Remove `__type__` requirement from `_StructLike`.
+  - **Breaking:** Remove `_EnumLike` and `_ContextPathStr`.
+
+- **caterpillar.model**
+  - Remove unused `getformat` function.
+
+- **caterpillar.fields.common**
+  - Remove unused `__fmt__` function in `Transformer`.
+
+---
+
+### Changed
+- **caterpillar.abc**
+  - Rename `_Switch` protocol to `_SwitchLike`.
+  - Move `STRUCT_FIELD` to `caterpillar.shared` as `ATTR_STRUCT`; move `hasstruct`, `getstruct`, and `typeof` to `caterpillar.shared`.
+
+- **caterpillar.byteorder**
+  - Move `BYTEORDER_FIELD` to `caterpillar.shared` as `ATTR_BYTEORDER`.
+
+- **caterpillar.model**
+  - Update `sizeof` to check if the object implements `_SupportsSize` protocol.
+  - Renew `Bitfield` concept with enhanced syntax.
+
+- **Documentation**
+  - Update reference and library docs; improve section numbering.
+
+---
+
+### Fixed
+- **caterpillar.model**
+  - Fix parsing of union objects with an unbound stream.
+  - Fix field options in Sequences and Structs not being populated when creating fields.
diff --git a/MANIFEST.in b/MANIFEST.in
diff --git a/README.md b/README.md
@@ -1,6 +1,7 @@
 # Caterpillar - 🐛
 
-[![python](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FMatrixEditor%2Fcaterpillar%2Fmaster%2Fpyproject.toml&logo=python)](https://www.python.org/downloads/)
+[![python](https://img.shields.io/badge/Python-3.12+-blue?logo=python&logoColor=yellow)](https://www.python.org/downloads/)
+![![Latest Version](https://pypi.org/project/caterpillar-py/)](https://img.shields.io/github/v/release/MatrixEditor/caterpillar.svg?logo=github&label=Latest+Version)
 [![Build and Deploy Docs](https://github.com/MatrixEditor/caterpillar/actions/workflows/python-sphinx.yml/badge.svg)](https://github.com/MatrixEditor/caterpillar/actions/workflows/python-sphinx.yml)
 [![Run Tests](https://github.com/MatrixEditor/caterpillar/actions/workflows/python-test.yml/badge.svg)](https://github.com/MatrixEditor/caterpillar/actions/workflows/python-test.yml)
 ![GitHub issues](https://img.shields.io/github/issues/MatrixEditor/caterpillar?logo=github)
@@ -10,15 +11,8 @@
 
 > [!WARNING]
 > This project is still in beta/testing phase. Expect bugs, naming changes and errors while using this
-> library. C API Reference is WIP, C extensions are supported since v2.1.0.
-
-> [!NOTE]
-> Python 3.14 breaks `with` statements in class definitions since `__annotations__` are added at the end
-> of a class definition. Therefore, `Digest` and conditional statements **ARE NOT SUPPORTED** in using the `with` syntax Python 3.14+.
-> As of version `2.4.5` the `Digest` class has a counterpart (`DigestField`), which can be used to manually specify a digest without
-> the need of a `ẁith` statement.
-
-
+> library. C API Reference is WIP, C extensions are supported since v2.1.0. The latest stable release
+> is available at PyPI.
 
 Caterpillar is a Python 3.12+ library to pack and unpack structurized binary data. It
 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
 
 *Caterpillar* is able to:
 
-* Pack and unpack data just from processing Python class definitions (including support for bitfields, c++-like templates and c-like unions!),
+* Pack and unpack data just from processing Python class definitions (including support for powerful bitfields, c++-like templates and c-like unions!),
 * apply a wide range of data types (with endianess and architecture configuration),
 * dynamically adapt structs based on their inheritance layout,
 * reduce the used memory space using `__slots__`,
@@ -36,36 +30,52 @@ options will be added in the future. Documentation is [here >](https://matrixedi
 * it helps you to create cleaner and more compact code.
 * You can even extend Caterpillar and write your parsing logic in C or C++!!
 
+> [!NOTE]
+> Python 3.14 breaks `with` statements in class definitions since `__annotations__` are added at the end
+> of a class definition. Therefore, `Digest` and conditional statements **ARE NOT SUPPORTED** using the `with` syntax in Python 3.14+.
+> As of version `2.4.5` the `Digest` class has a counterpart (`DigestField`), which can be used to manually specify a digest without
+> the need of a `ẁith` statement.
+
+
 ## Give me some code!
 
 ```python
-from caterpillar.py import *
+@bitfield(order=LittleEndian)
+class Header:
+    version : 4                # 4bit integer
+    valid   : 1                # 1bit flag (boolean)
+    ident   : (8, CharFactory) # 8bit char
+    # automatic alignment to 16bits
 
 @struct(order=LittleEndian)
 class Format:
-    magic: b"ITS MAGIC"       # Supports string and byte constants directly
-    a: uint8                  # Primitive data types
-    b: int32
-    length: uint8             # String fields with computed lengths
-    name: String(this.length) #  -> you can also use Prefixed(uint8)
-
-    # wraps all following fields and creates a new attr
-    # only for Python <= 3.13
-    with Md5(name="hash", verify=True):
-        # Sequences with prefixed, computed lengths
-        names: CString[uint8::]
+    magic  : b"ITS MAGIC"        # Supports string and byte constants directly
+    header : Header
+    a      : uint8               # Primitive data types
+    b      : int32
+    length : uint8               # String fields with computed lengths
+    name   : String(this.length) #  -> you can also use Prefixed(uint8)
 
+    _hash_begin : DigestField.begin("hash", Md5_Algo)   # custom actions, e.g. for hashes
+    names       : CString[uint8::]                      # Sequences with prefixed, computed lengths
+    hash        : Md5_Field("hash", verify=True) = None # automatic hash creation and verification + default value
 
 # Instantiation (keyword-only arguments, magic is auto-inferred):
-obj = Format(a=1, b=2, length=3, name="foo", names=["a", "b"])
+obj = Format(
+    header=Header(version=2, valid=True, ident="F"),
+    a=1,
+    b=2,
+    length=3,
+    name="foo",
+    names=["a", "b"]
+)
 # Packing the object, reads as 'PACK obj FROM Format'
 # objects of struct classes can be packed right away
 blob = pack(obj, Format)
-# results in: b'ITS MAGIC\x01\x02\x00\x00\x00\x03foo\x02a\x00b\x00\xf55...
+# results in: b'ITS MAGIC0*\x01\x02\x00\x00\x00\x03foo\x02a\x00b\x00)\x9a...'
 
 # Unpacking the binary data, reads as 'UNPACK Format FROM blob'
 obj2 = unpack(Format, blob)
-assert obj2.hash == obj.hash
 ```
 
 This library offers extensive functionality beyond basic struct handling. For further details

diff --git a/docs/sphinx/source/_static/css/custom.css b/docs/sphinx/source/_static/css/custom.css
@@ -0,0 +1,51 @@
+table.t-stbl {
+    padding: 0em 1em 0.5em 1em;
+    flex-direction: column;
+    display: flex;
+}
+
+.t-stbl td.t-hr {
+    border-top: 1px solid var(--pst-color-surface);
+    padding: 0
+}
+
+.t-stbl span.t-decl-id {
+    color: var(--pst-color-on-surface);
+    font-style: italic;
+}
+
+.t-stbl span.t-decl-opt {
+    color: var(--pst-color-primary);
+    font-style: italic;
+    padding-left: 0;
+    font-size: small;
+}
+
+.t-stbl td.t-no {
+    padding-left: 2em;
+}
+
+table.t-par-begin {
+    flex-direction: column;
+    display: flex;
+}
+
+tr.t-bar {
+    vertical-align: top;
+}
+
+tr.t-par>td {
+    vertical-align: top;
+    padding: 0 1em 0 0;
+}
+
+tr.t-par>td:nth-child(1) {
+    white-space: nowrap;
+    text-align: right;
+    font-weight: bold;
+    font-family: var(--pst-font-family-monospace-system);
+}
+
+tr.t-par>td:nth-child(3) {
+    width: 100%
+}
diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py
@@ -29,7 +29,7 @@
     "sphinx_design",
     "breathe",
     "c_annotations",
-    "sphinx_copybutton"
+    "sphinx_copybutton",
 ]
 
 templates_path = ["_templates"]
@@ -63,13 +63,14 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
-refcount_file = '../../../src/capi.dat'
-autodoc_member_order = 'bysource'
+refcount_file = "../../../src/capi.dat"
+autodoc_member_order = "bysource"
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 html_theme = "pydata_sphinx_theme"
 html_static_path = ["_static"]
+html_css_files = ["css/custom.css"]
 html_theme_options = {
     "show_nav_level": 4,
     "navbar_end": ["navbar-icon-links", "theme-switcher"],
@@ -78,10 +79,9 @@
     "logo": {
         "text": f"Caterpillar {version}",
     },
-    "announcement": "https://raw.githubusercontent.com/MatrixEditor/caterpillar/master/docs/sphinx/source/_templates/announcement.html",
 }
 html_sidebars = {
-  "installing/index": [],
+    "installing/index": [],
 }
 
 # -- Options for C++ Docs -----------------------------------------------------

diff --git a/docs/sphinx/source/development/changelog.rst b/docs/sphinx/source/development/changelog.rst
@@ -4,4 +4,109 @@
 Changelog
 *********
 
-*Entries will be added in the future.*
+*More entries will be added in the future.*
+
+.. _changelog_2.5.0:
+
+[2.5.0] - Minor Release
+=======================
+
+This version introduces massive changes due to the addition of stub files. Most of the type hints in the Python
+file are ported into several stub files. Additionally, the bitfield concept was completely renewed to be more
+flexible and dynamic.
+
+Added
+-----
+
+*caterpillar.abc*
+^^^^^^^^^^^^^^^^^
+
+- :class:`_SupportsBits` protocol
+- :class:`_ContainsBits` protocol
+- :class:`_SupportsType` protocol
+
+*caterpillar.shortcuts*
+^^^^^^^^^^^^^^^^^^^^^^^
+
+- New shortcuts: :func:`typeof`, :func:`to_struct`, :func:`hasstruct`, :func:`getstruct` and :func:`sizeof`
+
+*caterpillar.shared*
+^^^^^^^^^^^^^^^^^^^^
+
+- New constants from other modules: :attr:`ATTR_BYTEORDER`, :attr:`ATTR_TYPE`, :attr:`ATTR_BITS`, :attr:`ATTR_SIGNED`, :attr:`ATTR_TEMPLATE`
+
+*caterpillar.context*
+^^^^^^^^^^^^^^^^^^^^^
+
+- 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.
+
+.. raw:: html
+
+    <hr>
+
+Removed
+-------
+
+*caterpillar.abc*
+^^^^^^^^^^^^^^^^^
+
+- ``_Action`` protocol and create two separate Protocols that form::
+
+    _ActionLike = _SupportsActionUnpack | _SupportsActionPack
+
+- ``__type__`` requirement from :class:`_StructLike`
+- **Breaking:** ``_EnumLike``, ``_ContextPathStr``
+
+*caterpillar.model*
+^^^^^^^^^^^^^^^^^^^
+
+- Unused ``getformat`` function
+
+*caterpillar.fields.common*
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Unused ``__fmt__`` function in :class:`Transformer`
+
+.. raw:: html
+
+    <hr>
+
+Changed
+-------
+
+*caterpillar.abc*
+^^^^^^^^^^^^^^^^^
+
+- Rename ``_Switch`` protocol to :attr:`_SwitchLike`
+- Move the following attributes and methods into *caterpillar.shared*: rename ``STRUCT_FIELD`` to :attr:`ATTR_STRUCT`, :func:`hasstruct`, :func:`getstruct` and :func:`typeof`
+
+*caterpillar.byteorder*
+^^^^^^^^^^^^^^^^^^^^^^^
+
+- Move ``BYTEORDER_FIELD`` to *caterpillar.shared* as :attr:`ATTR_BYTEORDER`
+
+
+*caterpillar.model*
+^^^^^^^^^^^^^^^^^^^
+
+- :func:`sizeof` now checks if the provided object implements the :class:`_SupportsSize` protocol
+- New :class:`Bitfield` concept with enhanced syntax
+
+
+*Documentation*
+^^^^^^^^^^^^^^^
+
+- Update reference and library docs as well as section numbering
+
+.. raw:: html
+
+    <hr>
+
+Fixed
+-----
+
+*caterpillar.model*
+^^^^^^^^^^^^^^^^^^^
+
+- when parsing union objects with an unbound stream object
+- field options defined in Sequences and Structs were not populated when creating fields.
diff --git a/docs/sphinx/source/development/index.rst b/docs/sphinx/source/development/index.rst
@@ -7,7 +7,6 @@ Development
 *TODO*
 
 .. toctree::
-    :numbered:
     :maxdepth: 2
 
     roadmap.rst