Retriever

Retriever

Used inside a BaseStruct subclass to define its serialization schema from built-in types or other base structs, allowing setting constraints and hooks

__get__

__get__(instance: Any, owner: Any) -> Any

__new__

__new__(data_type: Any, *, min_ver: Version = Version(-1), max_ver: Version = Version(10000), default: Any = None, default_factory: Callable[[Version], Any] = None, repeat: int = 1, remaining_compressed: bool = False, on_read: Callable[[], list[Combinator]] = None, on_write: Callable[[], list[Combinator]] = None) -> Retriever

Create a new retriever property to be used for serialization inside a BaseStruct subclass

Parameters:

• data_type (Any) –

  The type of the property used for serialization

• min_ver (Version, default: Version(-1) ) –

  The minimum struct version which supports this retriever property. If the version of the struct being serialized is less than min_ver, serialization for this retriever property is skipped. A VersionError will be raised if an attempt to access this property is made in an un-supporting struct. Using SemVer is recommended: https://semver.org/

• max_ver (Version, default: Version(10000) ) –

  The maximum struct version which supports this retriever property. If the version of the struct being serialized is greater than max_ver, serialization for this retriever property is skipped. A VersionError will be raised if an attempt to access this property is made in an un-supporting struct. Using SemVer is recommended: https://semver.org/

• default_factory (Callable[[Version], Any], default: None ) –

  A function that will receive a version when called and must return an instance of data_type

• repeat (int, default: 1 ) –

  The number of times this value is repeated. Prefer using fixed length array types over repeats wherever possible. Allowed values for this parameter are:

  • -2: skip a list, sets the property to None
  • -1: skip a value, sets the property to None
  • 0: skip a list, set property to []
  • 1: serialize a value
  • >1: serialize a list

  Note: -2 and -1 both skip serialization but -2 indicates that the true type of the value of this retriever property is actually a list[data_type] (compared to just data_type when it's -1) - this information is needed for type checking if the None value is later set to an actual value

• remaining_compressed (bool, default: False ) –

  If set to True, the _decompress/_compress methods from the BaseStruct subclass are used on the remaining bytes before deserialization/serialization of the remaining properties occurs (inclusive)

• on_read (Callable[[], list[Combinator]], default: None ) –

  A function that must return a list of Combinators to use for fine-grained operations during deserialization

• on_write (Callable[[], list[Combinator]], default: None ) –

  A function that must return a list of Combinators to use for fine-grained operations during serialization

__set__

__set__(instance: BaseStruct, value: Any) -> None

__set_name__

__set_name__(owner: Any, name: str) -> None

supported

supported(ver: Version) -> bool

Checks if this property is supported in the given version. A property is supported if min_ver <= ver <= max_ver

Parameters:

• ver (Version) –

  the version to check support for