binobj.fields.numeric module

Fields representing numeric values, such as integers and floats.

class Float(*_args: Any, **kwargs: Any)

Bases: Field[float]

A floating-point number in IEEE-754:2008 interchange format.

This is a base class and should not be used directly.

Parameters:

• format_string (str) – The format character used by the struct library to load and dump this floating-point number. Can be “e” (16 bits), “f” (32 bits) or “d” (64 bits).

• endian (str) – The endianness to use to load/store the float. Either “big” or “little”. If not given, defaults to the system’s native byte ordering as given by sys.byteorder.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class Float16(*_args: Any, **kwargs: Any)

Bases: Float

A half-precision floating-point number in IEEE-754 binary16 format.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class Float32(*_args: Any, **kwargs: Any)

Bases: Float

A single-precision floating-point number in IEEE-754 binary32 format.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class Float64(*_args: Any, **kwargs: Any)

Bases: Float

A floating-point number stored in IEEE-754 binary64 format.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class Int16(*_args: Any, **kwargs: Any)

Bases: Integer

A 16-bit signed integer.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class Int32(*_args: Any, **kwargs: Any)

Bases: Integer

A 32-bit signed integer.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class Int64(*_args: Any, **kwargs: Any)

Bases: Integer

A 64-bit signed integer.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class Int8(*_args: Any, **kwargs: Any)

Bases: Integer

An 8-bit signed integer.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class Integer(*_args: Any, **kwargs: Any)

Bases: Field[int]

A two’s-complement integer of some fixed size.

This class is typically not used directly, except for integers with sizes that aren’t powers of two, e.g. for a 24-bit number.

Parameters:

• endian (str) – The endianness to use to load/store the integer. Either ‘big’ or ‘little’. If not given, defaults to the system’s native byte ordering as given by sys.byteorder.

• signed (bool) – Indicates if this number is a two’s-complement signed or unsigned integer. Defaults to True (signed). Signed formats other than two’s-complement such as sign-magnitude are not supported.

• size (int) – The size of the integer, in bytes.

Changed in version 0.8.0:

• The size argument is now required.

• The class now throws UndefinedSizeError when loading and dumping if the field doesn’t have a defined size. Before it used to crash with a TypeError due to this oversight.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class Timestamp(*_args: Any, **kwargs: Any)

Bases: Field[datetime]

A timestamp stored as an integer offset from the Unix epoch.

Timestamps are stored in UTC. When dumping, naive datetimes are assumed to be in the local timezone; when loading and tz_aware is False, loaded datetimes are in the local timezone.

This class is typically not used directly, except for timestamps with sizes that aren’t powers of two, e.g. the 96-bit timestamps used by Amazon Redshift.

Parameters:

• resolution (str) – The resolution timestamps will be stored with. Accepted values are “s”, “ms”, “us” (microseconds), and “ns”. Note that Python’s datetime objects don’t support nanosecond resolution.

• tz_aware (bool) –

  Controls whether loads return timezone-aware or naive datetimes. Loaded timestamps are naive by default, and in the platform’s local timezone.

  >>> field = Timestamp32(tz_aware=True)
  >>> field.from_bytes(b'\xa3\xc3\x55\x5c')
  datetime.datetime(2019, 2, 2, 16, 21, 55, tzinfo=datetime.timezone.utc)
  

• endian (str) – The byte order to store the timestamp in. Defaults to the host machine’s byte order as given by sys.byteorder.

• signed (bool) – Whether the timestamp should be stored as a signed integer or not. It’s highly recommended this be left at the default (True) for compatibility with other Unix systems.

New in version 0.6.0.

Changed in version 0.8.0:

• This class no longer inherits from Integer.

• size is now a required argument.

• The class now throws UndefinedSizeError when loading and dumping if the field doesn’t have a defined size. Before it used to crash with a TypeError due to this oversight.

Deprecated since version 0.11.0: Passing a zone-aware timestamp to this field when tz_aware is false, or a naive timestamp when tz_aware is true is now deprecated, and will trigger an error in the future.

See also

Timestamp32, Timestamp64

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class Timestamp32(*_args: Any, **kwargs: Any)

Bases: Timestamp

A timestamp saved as a 32-bit integer.

New in version 0.6.0.

See also

Timestamp

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class Timestamp64(*_args: Any, **kwargs: Any)

Bases: Timestamp

A timestamp saved as a 64-bit integer.

New in version 0.6.0.

See also

Timestamp

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class UInt16(*_args: Any, **kwargs: Any)

Bases: Int16

A 16-bit unsigned integer.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class UInt32(*_args: Any, **kwargs: Any)

Bases: Int32

A 32-bit unsigned integer.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class UInt64(*_args: Any, **kwargs: Any)

Bases: Int64

A 64-bit unsigned integer.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class UInt8(*_args: Any, **kwargs: Any)

Bases: Int8

An 8-bit unsigned integer.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class UnsignedInteger(*_args: Any, **kwargs: Any)

Bases: Integer

An unsigned two’s-complement integer of some fixed size.

This class is typically not used directly, except for integers with sizes that aren’t powers of two, e.g. for a 24-bit number.

See also

Integer

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None

class VariableLengthInteger(*_args: Any, **kwargs: Any)

Bases: Integer

An integer of varying size.

Parameters:

• vli_format (VarIntEncoding) – Required. The encoding to use for the variable-length integer.

• max_bytes (int) – The maximum number of bytes to use for encoding this integer. If not given, there’s no restriction on the size.

const: T | _Undefined

The fixed value of a field, if applicable.

This is mostly useful for fields that act as magic numbers or reserved fields in a struct that should be set to nulls.

discard: bool

If True, indicates that a field should be discarded when read.

This is best used for filler fields that are of no use to the application but are nonetheless important to ensure the proper layout of the struct.

name: str

The name of the field.

Technical Note: This attribute can only be None if the field was created without passing a value for name to the constructor and the field has never been bound to a struct. Since this is highly unlikely in normal usage, this attribute is declared as str rather than Optional[str].

offset: int | None