Add changelog for 2.8.0 release

Author: MatrixEditor

CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [2.8.0] - Extended Syntax
+
+### Added
+
+- New concept: *extended* syntax featuring typing compliance; introduces shortcut `f` to annotate fields and `Invisible()` to hide fields from the constructor
+- `struct_factory.mixin` and `bitfield_factory.mixin` both provide default function wrappers for packing and unpacking data as well as typing fixes for operating on types directly.
+- New `parentctx` context path
+- Dynamic endian is now used by default (i. e. can be changed via order parameter in pack() or unpack())
+- New generic `Timestamp` class
+- A number of new test cases
+- New module: `caterpillar.types`: defines default types that can be used as annotations within struct definitions
+- `O_DEFAULT_ENDIAN` as a global option to set a global default byteorder
+- `O_DEFAULT_ARCH` same concept for arch-like objects
+- new 'strict' option to `Enum` struct
+- `ATTR_PACK` and `ATTR_UNPACK` to *caterpillar.shared*
+- `'order'` and `'arch'` options to pack() and unpack(), which temporarily change the global endianess or arch (compatible with Dynamic byteorder)
+
+### Changes
+
+- Merge all stub files with their corresponding Python files. All typing is now inline.
+- `padding` struct now has its own dedicated class
+- sizeof() now always returns an integer
+- ContextPath: dropped support for the call action
+- Field.get_name() now always returns a string
+- Rename `ssize` and `size` to `pssize` and `psize` in caterpillar.fields exports
+- options.get_flags() always returns a list
+
+### Fixes
+
+- IntFlag support for `Enum` structs
+- Fix incorrect Sha1 Digest length
+- Add missing global exports in `caterpillar.py`
+- Bitfield, Struct and Sequence now respect fields with already configured byteorder
+- Prefixed struct now does not require `as_field=True` when calling pack() or unpack()
+
 ## [2.7.0] - Dynamic Byteorder
 
 ###  Added

docs/sphinx/source/development/changelog.rst

@@ -6,6 +6,48 @@ Changelog
 
 *More entries will be added in the future.*
 
+.. _changelog_2.8.0:
+
+[2.8.0] - Extended Syntax
+=========================
+
+Added
+-----
+
+- New concept: *extended* syntax featuring typing compliance; introduces shortcut :data:`f` to annotate fields and :func:`~caterpillar.model.Invisible` to hide fields from the constructor
+- ``struct_factory.mixin`` and ``bitfield_factory.mixin`` both provide default function wrappers for packing and unpacking data as well as typing fixes for operating on types directly.
+- New :data:`~caterpillar.context.parentctx` context path
+- Dynamic endian is now used by default (i. e. can be changed via order parameter in pack() or unpack())
+- New generic :class:`~caterpillar.fields.Timestamp` class
+- A number of new test cases
+- New module: ``caterpillar.types``: defines default types that can be used as annotations within struct definitions
+- :data:`~caterpillar.byteorder.O_DEFAULT_ENDIAN` as a global option to set a global default byteorder
+- :data:`~caterpillar.byteorder.O_DEFAULT_ARCH` same concept for arch-like objects
+- new 'strict' option to :class:`~caterpillar.fields.Enum` struct
+- :data:`~caterpillar.shared.ATTR_PACK` and :data:`~caterpillar.shared.ATTR_UNPACK` to *caterpillar.shared*
+- `'order'` and `'arch'` options to pack() and unpack(), which temporarily change the global endianess or arch (compatible with Dynamic byteorder)
+
+Changes
+-------
+
+- Merge all stub files with their corresponding Python files. All typing is now inline.
+- :class:`~caterpillar.fields.Padding` struct now has its own dedicated class
+- sizeof() now always returns an integer
+- ContextPath: dropped support for the call action
+- Field.get_name() now always returns a string
+- Rename `ssize` and `size` to :data:`~caterpillar.fields.pssize` and :data:`~caterpillar.fields.psize` in caterpillar.fields exports
+- options.get_flags() always returns a list
+
+Fixes
+-----
+
+- IntFlag support for :class:`~caterpillar.fields.Enum` structs
+- Fix incorrect Sha1 Digest length
+- Add missing global exports in *caterpillar.py*
+- Bitfield, Struct and Sequence now respect fields with already configured byteorder
+- Prefixed struct now does not require ``as_field=True`` when calling pack() or unpack()
+
+
 .. _changelog_2.7.0:
 
 [2.7.0] - Dynamic Byteorder

docs/sphinx/source/reference/capi/extension.rst

@@ -17,7 +17,7 @@ Before proceeding, ensure you have the following tools installed:
 Assuming you are using `scikit-build <https://scikit-build-core.readthedocs.io/en/stable/getting_started.html)>`_ to write
 your extension, the following project structure applies:
 
-.. code-block:: txt
+.. code-block:: text
 
     example-extension
     ├── CMakeLists.txt

pyproject.toml

@@ -8,7 +8,7 @@ cmake.source-dir = "."
 
 [project]
 name = "caterpillar"
-version = "2.8.0rc"
+version = "2.8.0"
 requires-python = ">=3.10"
 description = "Library to pack and unpack structurized binary data."
 authors = [{ name = "MatrixEditor" }]

src/caterpillar/__init__.py

@@ -14,7 +14,7 @@
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 import warnings
 
-__version__ = "2.8.0rc"
+__version__ = "2.8.0"
 __release__ = "2.8"
 __author__ = "MatrixEditor"
 

src/caterpillar/abc.py

@@ -344,7 +344,9 @@ def __call__(self, value: Any, context: _ContextLike) -> _StructLike: ...
 
 
 _SwitchOptionsT = _SwitchLambda | dict[Any, Any]
-
+"""
+.. versionadded 2.8.0
+"""
 
 @runtime_checkable
 class _SupportsBits(Protocol):
@@ -391,6 +393,11 @@ def __call__(self, __value: Iterable[_IT]) -> Collection[_IT]: ...
 
 
 class _ContextFactoryLike(Protocol):
+    """
+
+    .. versionadded 2.8.0
+    """
+
     def __call__(self, **kwargs: Any) -> _ContextLike: ...
 
 

src/caterpillar/fields/_base.py

@@ -485,6 +485,11 @@ def get_type(self) -> type:
         return return_type  # pyright: ignore[reportReturnType]
 
     def get_name(self) -> str:
+        """Returns the name of this field.
+
+        .. versionchanged:: 2.8.0
+            now always returns a string
+        """
         return getattr(self, "__name__", "_")
 
     # IO related stuff

src/caterpillar/fields/common.py

@@ -798,6 +798,10 @@ class Enum(Generic[_EnumT, _IT], Transformer[_EnumT, _IT, _EnumT | _IT, _IT]):
     :param struct: The _StructLike object to be wrapped.
     :param default: The default value to return if decoding encounters an unrecognized value.
                     Default is `INVALID_DEFAULT`.
+    :param strict: controls whether the parsed value has to conform to the input enum model.
+
+    .. versionchanged:: 2.8.0
+        Add new 'strict' option.
     """
 
     __slots__: tuple[str, ...] = ("model", "default", "strict")

src/caterpillar/options.py

@@ -109,6 +109,9 @@ def get_flags(obj: object, attr: str | None = None) -> list[_OptionLike]:
     """
     Get the flags associated with an object.
 
+    .. versionchanged:: 2.8.0
+        now always returns a list
+
     :param obj: The object.
     :param attr: The attribute name containing the flags (default is "flags").
     :return: The set of flags, or None if no flags are present.

src/ccaterpillar/pyproject.toml

@@ -17,7 +17,7 @@ CP_ENABLE_NATIVE = "1"
 
 [project]
 name = "caterpillar"
-version = "2.8.0rc"
+version = "2.8.0"
 requires-python = ">=3.12"
 description = "Library to pack and unpack structurized binary data."
 readme = "../../README.md"