Skip to content

[DEV] v2.8.0: Extended syntax & typing fixes#55

Merged
MatrixEditor merged 37 commits into
masterfrom
dev/2.8.0-extended-syntax
Feb 1, 2026
Merged

[DEV] v2.8.0: Extended syntax & typing fixes#55
MatrixEditor merged 37 commits into
masterfrom
dev/2.8.0-extended-syntax

Conversation

@MatrixEditor
Copy link
Copy Markdown
Owner

@MatrixEditor MatrixEditor commented Jan 14, 2026

This pull request tracks the status while transitioning to the v2.8.0 release

As mentioned in #53, having a type-checker compliant class definition would increase the usability of this library, changes made here introduce a new syntax, named "extended syntax". It allows specifying fields alongside their Python type without breaking the core concept of caterpillar.

The newly introduced type aliases apply a specific naming scheme and always end with _t, so they can be distinguished from normal struct types.

from caterpillar.types import uint32_t # new module
from caterpillar.shortcuts import f # extended syntax field specifier
from caterpillar.py import struct, uint32 # struct types

@struct
class Format:
    # Annotating fields is the same as before. This time, is is important to note that we can 
    # either use the type directly or specify it manually
    value: uint32_t
    # manual definition
    value: f[int, uint32] # NOTE: no '_t' here as we have to use the struct here

# packing and unpacking is still the same...

TBD

Additions

  • Invisible field specifier that can be used to "hide" struct fields in the constructor (when using a type checker)
  • 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.
  • Add new parentctx context path
  • Dynamic endian is now used by default (i. e. can be changed via order= in pack() or unpack())
  • Add new generic Timestatmp class

Other changes

  • Merge all stub files with their corresponding Python files. All typing is now inline.
  • A number of new test cases
  • padding struct now has its own dedicated class
  • sizeof() now always returns an integer
  • IntFlag support for Enum structs (IntFlag support & global default endianess #56)

Fixes #54

---

+ Merge byteorder stubs into byteorder.py
+ Merge abc.py
---

+ Fix abc.py type definitions
---

+ Add _ContextFactoryLike protocol
---

+ TypeVar is not imported from typing_extensions to support the default argument
+ Add _SwitchOptionsT
+ Make _ArchLike, _EndianLike and _OptionLike '@runtime_checkable'
---

+ getstruct(): update annotations to support @struct defined types
+ typeof(): now supports NotImplementedError and NotImplemented as return type
---

+ ContextPath: dropped support for the call action
---

+ fix __getitem__ return type annotation
+ fix switch annotation in __rshift__
+ Field.get_name() now always returns a string
---

+ Merge conditional.py stubs
---

+ Merge digest.py stubs
---

+ Rename ssize and size in caterpillar.fields exports
+ Sequence: add support for Annotated values
+ Merge model._base annotations
---

+ Merge template.py as well
---

+ shortcuts: New export "f" which aliases the Annotated function for extended syntax
+ new module: types
   - defines default types that can be used as annotations within struct definitions
---

+ Update examples and remove type errors
+ options.get_flags() always returns list
+ add missing global exports
+ Add protocol compliance tests
+ Add more tests for Flag class
@MatrixEditor MatrixEditor linked an issue Jan 23, 2026 that may be closed by this pull request
---

NEW:
+ O_DEFAULT_ENDIAN as a global option to set a global default byteorder
+ O_DEFAULT_ARCH same concept for arch-like objects
+ Add new 'strict' option to Enum struct
+ Add 'order' and 'arch' options to pack() and unpack(), which temporarily change the global endianess or arch (compatible with Dynamic byteorder)
+ Add extra options to extended syntax allowing OptionLike, EndianLike and ArchLike
+ Add ATTR_PACK and ATTR_UNPACK to caterpillar.shared

CHANGES:
+ Update common structs and bitfield implementation to support new global byteorder option
+ Fix IntFlag issure with Enum structs (#56)
+ Bitfield, Struct and Sequence now respect fields with already configured byteorder
---

+ Add new byteorder tests
+ Add enum tests for Python's IntFlag
----

+ Export 'f' shortcut in caterpillar.py
---

CHANGES:
+ Add Padding class including custom fill pattern and parsing checks
+ Add padding tests
+ move __set_byteorder__ into ByteOrderMixin
+ Prefixed struct now does not require as_field=True when calling pack() or unpack()
+ Add custom type: balign_t for special boundary alignment in bitfields
---

+ Update README
+ Fix ConditionalContext to support Annotated types
---

+ Update README to include default syntax as well
+ Update benchmark script to use new extended syntax
+ caterpillar.shared: renamed identity -> constval
+ Add missing AsLengthRef to exports
+ sizeof() now always returns an integer

NEW:
+ Add new parentctx context path
+ Add new struct-mixin example
+ Add new generic timestatmp class
+ Add new concept: invisiable class attributes for type checkers
+ Add new struct-mixin class to help type checkers
---

+ Add timestamp_t for unix timestamps
---

+ Context and ContextPath now include type checker hints for special context variables
+ Renamed size and ssize to psize and pssize
---

+ Cleanup _C.pyi stubs file
---

+ Add _C protocol conformance tests
@MatrixEditor MatrixEditor merged commit 0477c67 into master Feb 1, 2026
12 checks passed
@MatrixEditor MatrixEditor deleted the dev/2.8.0-extended-syntax branch February 1, 2026 10:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

IntFlag support & global default endianess [BUG] Context stub file is missing a field

1 participant