4.3. Context#

4.3.1. Context classes#

class caterpillar.context.Context[source]#

Represents a context object with attribute-style access.

Represents the primary container for context-aware operations during packing and unpacking. It manages attribute access, supports hierarchical relationships, and tracks contextual state. Conforms to the _ContextLike protocol.

__context_getattr__(path: str)[source]#

Retrieves an attribute from the context.

Parameters:: key – The attribute key.
Returns:: The value associated with the key.

class caterpillar.context.ContextPath(path=None)[source]#: Represents a lambda function for retrieving a value from a Context based on a specified path.

class caterpillar.context.ContextLength(path: ContextPath)[source]#: Encapsulates length information derived from the context, often used in size-dependent field evaluation.

class caterpillar.context.ConditionContext(condition, depth=2)[source]#

Class implementation of an inline condition.

Use this class to automatically apply a condition to multiple field definitions. Note that this class will only work if it has access to the parent stack frame.

@struct
class Format:
    magic: b"MGK"
    length: uint32

    with this.length > 32:
        # other field definitions here
        foo: uint8

This class will replace any existing fields!

Parameters:: condition (Union[_ContextLambda, bool]) – a context lambda or constant boolean value

4.3.2. Extra options#

context.O_CONTEXT_FACTORY = Flag(name='option.context_factory', value=<class 'caterpillar.context.Context'>)#

Defines the default factory used to instantiate context objects during the packing and unpacking process. To use the C-extension Context implementation for a 10% speed caveat, use:

from caterpillar.context import O_CONTEXT_FACTORY
from caterpillar.c import c_Context

# that's all you have to do
O_CONTEXT_FACTORY.value = c_Context

Added in version 2.6.0.

4.3.3. Special paths#

context.this#: Represents a lambda function for retrieving a value from a Context based on a specified path.

context.ctx#: Represents a lambda function for retrieving a value from a Context based on a specified path.

context.parent#: Represents a lambda function for retrieving a value from a Context based on a specified path.

context.root#

Represents a lambda function for retrieving a value from a Context based on a specified path.

Provides access to the root-level context object.

Added in version 2.6.0.

4.3.4. Special Attributes#

context.CTX_PARENT = '_parent'#: Identifies the parent object within the context tree.

context.CTX_OBJECT = '_obj'#: Refers to the current object associated with the context.

context.CTX_OFFSETS = '_offsets'#: Stores offset information used during stream parsing or generation.

context.CTX_STREAM = '_io'#: References the data stream associated with the packing or unpacking operation.

context.CTX_FIELD = '_field'#: Indicates the current field being processed within the structure.

context.CTX_VALUE = '_value'#: Stores the value associated with the current context node.

context.CTX_POS = '_pos'#: Represents the current position within the stream or structure.

context.CTX_INDEX = '_index'#: Maintains the index for sequence or array-based context elements.

context.CTX_PATH = '_path'#: Provides the full path to the current context object.

context.CTX_SEQ = '_is_seq'#: Holds a reference to the sequence object, if applicable.

context.CTX_ROOT = '_root'#: Points to the root of the entire context hierarchy.

4.3.5. Expressions#

class caterpillar.context.ExprMixin[source]#: A mixin class providing methods for creating binary and unary expressions.

class caterpillar.context.BinaryExpression(operand: Callable[[Any, Any], Any], left: Any, right: Any)[source]#

Represents a binary expression.

Parameters:

operand – The binary operator function.
left – The left operand.
right – The right operand.

class caterpillar.context.UnaryExpression(name: str, operand: Callable[[Any], Any], value: Any)[source]#

Represents a unary expression.