Skip to content

CHANGELOG.md

Latest commit

 

History

History
256 lines (185 loc) · 9.65 KB

CHANGELOG.md

File metadata and controls

256 lines (185 loc) · 9.65 KB
Raw

Changelog

[2.9.1] - Typing fixes

  • Prefixed now supports struct types directly
  • StructDefMixin now includes direct to-bytes conversion with bytes(...)
  • Fixed a bug in @bitfield where parsed bit-width fields are not populated to the current context
  • Corrected some type hints in FieldMixin and _ContextLike

[2.9.0] - Python 3.14 Compatibility and Generic Templates

Added

  • Python 3.14-compatible conditional field metadata: with If(condition) as when:, f[..., when], Start(when) / End(when), explicit ElseIf(previous, condition) chains, and Else(previous) fallback branches.
  • Branch, When, and Otherwise for conditional variants of one attribute, including branch-local f[...] options such as byte order.
  • Python generic templates based on normal typing.TypeVar and Generic classes. Templates now support direct Template[uint8] specialization, partial specialization, specialization caching, and runtime __origin__ / __args__ metadata.
  • field_of() for carrying generic template field metadata through f[...], including sequence length, offset, switch options, byte order, bit width, and conditions.
  • Padded, PrePad, and PostPad wrappers for explicit before/after padding, dynamic padding lengths, repeated fill patterns, strict validation, and slash syntax such as uint8 / PrePad(1) / PostPad(2).
  • A pytest-benchmark benchmark suite covering the examples/comparison workload.

Changes

  • derive() now handles generic templates, returns already materialized struct classes unchanged when no type arguments are supplied, supports keyword defaults in legacy templates, and evaluates deferred annotations while legacy template variables are still available.
  • Native C atoms (Repeated, Conditional, AtOffset, and Switch) now accept Python struct classes and other __struct__ containers, improving Python/C interoperability and c_Context coverage.
  • PyStructFormattedField now handles prefixed sequence unpacking and validates empty sequence packing after processing fixed or prefixed lengths.
  • Lazy now resolves objects that expose __struct__, allowing lazy factories to return decorated model classes or struct containers.

Fixes

  • Field rejects negative sequence lengths at definition time and uses a faster no-option unpack path while preserving default fallback and exception wrapping behavior.
  • Compressed copies compression and decompression keyword arguments before resolving context lambdas, preventing cross-call mutation.
  • Fixed-length CString unpacking now performs exact reads and rejects truncated input.
  • Padding validation now covers strict greedy fill patterns and rejects unsupported prefixed padding lengths.
  • C extension fixes include safer reference handling and error propagation, length-info forwarding to __pack_many__ / __unpack_many__, __bits__ lookup on Python atoms, repeated atom unpack detection, AtOffset.keep_pos behavior, switch type aggregation, arch/endian rich comparison errors, and writable offset/whence setters.

[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

  • New concept: dynamic byte order (explained in documentation "Dynamic Byte Order")

Fixed

caterpillar.field.net

  • Fixed parsing of :class:~caterpillar.fields.net.MACAddress
  • Fixed mixed endian in a struct, sequence or bit-field

[2.6.3] - Patch Release

Fixed

caterpillar

  • Various stub files and decorator annotations

[2.6.2] - Patch Release

Fixed

caterpillar.field._base

  • Fix 1-length sized array fields

caterpillar

  • Add compatibility with at least Python 3.10 by using typing_extensions

[2.6.1] - Hot-Fix Release

Fixed

  • caterpillar.fields._base

    • Fix switch functionality within the Field class for ContextPath objects

  • caterpillar.fields.common

    • fix % operator for the AsLengthRef class.

[2.6.0] - Minor Release

Added

  • caterpillar.fields._base

    • Add support for non-context lambda switch fields.

  • caterpillar.fields.common

    • Add compatibility support for CAPI atoms in Int, UInt and PyStructFormattedField.

  • caterpillar.options

    • Add custom Flag.__eq__ implementation to support equality check with c_Option objects.

  • caterpillar.abc

    • Add new typing-only _OptionLike protocol.
    • Add missing _SupportsType protocol to the stubs file.
    • Add new method get to the _ContextLike protocol.

  • caterpillar.context

    • Add new option O_CONTEXT_FACTORY that controls the global context type. Value must be a method or another type implementing the _ContextLike protocol.
    • Add new global context path: root (exported as G in shortcuts).

  • caterpillar.shortcuts

    • Add new shortcuts C for ctx, P for parent and G for the root context as ContextPath objects.

  • CAPI

    • New index assignment system when generating CAPI code — a running number is now applied instead of a hard-coded index.
    • Add complete Context implementation in C (c_Context) that conforms to the _ContextLike protocol.
    • Add Atom for C-based struct-like classes (previously known as catom).
    • Add native support for __bits__ in Atom.
    • Add special class LengthInfo for packing or unpacking multiple objects.
    • New builtin atoms (CAPI): Repeated, Conditional and Switch.
    • Add new shared objects and exception types to the native implementation (Cp_ContextFactory, Cp_ArrayFactory, CpExc_Stop and Cp_DefaultOption).

Changed

  • caterpillar.fields._base
    • Rework Field implementation to reduce overhead when packing and unpacking elements.
    • Use pre-computed states instead of calculating everything on the fly; states will be adjusted automatically when setting new values (via @property attributes).

Fixed

  • caterpillar.fields.common
    • Fix issue in Prefixed that occurred when the internal struct packs a sequence of elements.

Removed

  • CAPI
    • Remove old CAPI and completely revamp the CAPI concept to make it compatible with the Python equivalent.

[2.5.1] - Hot-Fix Release

Fixed

  • caterpillar.model
    • An issue when packing or unpacking a bitfield with unnamed fields AND S_DISCARD_UNNAMED enabled

[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.