src.bluetooth_sig.gatt.characteristics.utils.extractors¶

Raw byte extractors for the BLE encoding/decoding pipeline.

This module provides the extraction layer that ONLY converts bytes to raw integers (and back). Extractors have a single responsibility: byte layout interpretation.

The extraction layer is the first stage of the decode pipeline:: bytes → [Extractor] → raw_int → [Translator] → typed_value

Per Bluetooth SIG specifications, all multi-byte values use little-endian encoding unless explicitly stated otherwise.

Attributes¶

Name	Description
`FLOAT32`
`SINT16`
`SINT24`
`SINT32`
`SINT8`
`UINT16`
`UINT24`
`UINT32`
`UINT8`

Classes¶

Name	Description
`Float32Extractor`	Extract/pack IEEE-754 32-bit floats.
`RawExtractor`	Protocol for raw byte extraction.
`Sint16Extractor`	Extract/pack signed 16-bit integers (-32768 to 32767).
`Sint24Extractor`	Extract/pack signed 24-bit integers (-8388608 to 8388607).
`Sint32Extractor`	Extract/pack signed 32-bit integers (-2147483648 to 2147483647).
`Sint8Extractor`	Extract/pack signed 8-bit integers (-128 to 127).
`Uint16Extractor`	Extract/pack unsigned 16-bit integers (0 to 65535).
`Uint24Extractor`	Extract/pack unsigned 24-bit integers (0 to 16777215).
`Uint32Extractor`	Extract/pack unsigned 32-bit integers (0 to 4294967295).
`Uint8Extractor`	Extract/pack unsigned 8-bit integers (0 to 255).

Functions¶

Name	Description
`get_extractor`(→ RawExtractor \| None)	Get extractor for a GSS type string.

Module Contents¶

class src.bluetooth_sig.gatt.characteristics.utils.extractors.Float32Extractor¶

Bases: RawExtractor

Extract/pack IEEE-754 32-bit floats.

Unlike integer extractors, this returns the raw bits as an integer to enable special value detection (NaN patterns, etc.) before translation to float.

extract(data: bytes | bytearray, offset: int = 0) → int¶

Extract float32 as raw bits for special value checking.

Returns the raw 32-bit integer representation of the float, which allows special value detection (NaN patterns, etc.).

extract_float(data: bytes | bytearray, offset: int = 0) → float¶: Extract as actual float value (convenience method).

pack(raw: int) → bytearray¶: Pack raw bits to float32 bytes.

pack_float(value: float) → bytearray¶: Pack float value to bytes (convenience method).

property byte_size: int¶

4 bytes.

Type:: Size

property signed: bool¶: Floats are inherently signed.

class src.bluetooth_sig.gatt.characteristics.utils.extractors.RawExtractor¶

Bases: abc.ABC

Protocol for raw byte extraction.

Extractors handle ONLY byte layout: extracting raw integers from bytes and packing raw integers back to bytes. They do not apply scaling, handle special values, or perform validation beyond bounds checking.

The separation enables: - Interception of raw values for special value handling - Composition with translators for scaling - Reuse across templates and characteristics

abstractmethod extract(data: bytes | bytearray, offset: int = 0) → int¶

Extract raw integer from bytes.

Parameters:

data – Source bytes to extract from.
offset – Byte offset to start reading from.

Returns:

Raw integer value (not scaled or interpreted).

Raises:

InsufficientDataError – If data is too short for extraction.

abstractmethod pack(raw: int) → bytearray¶

Pack raw integer to bytes.

Parameters:: raw – Raw integer value to encode.
Returns:: Packed bytes in little-endian format.
Raises:: ValueRangeError – If raw value exceeds type bounds.

property byte_size: int¶

Abstractmethod:

Number of bytes this extractor reads/writes.

property signed: bool¶

Abstractmethod:

Whether the integer type is signed.

class src.bluetooth_sig.gatt.characteristics.utils.extractors.Sint16Extractor(endian: Literal['little', 'big'] = 'little')¶

Bases: RawExtractor

Extract/pack signed 16-bit integers (-32768 to 32767).

extract(data: bytes | bytearray, offset: int = 0) → int¶: Extract sint16 from bytes.

pack(raw: int) → bytearray¶: Pack sint16 to bytes.

property byte_size: int¶

2 bytes.

Type:: Size

property signed: bool¶: Signed type.

class src.bluetooth_sig.gatt.characteristics.utils.extractors.Sint24Extractor(endian: Literal['little', 'big'] = 'little')¶

Bases: RawExtractor

Extract/pack signed 24-bit integers (-8388608 to 8388607).

extract(data: bytes | bytearray, offset: int = 0) → int¶: Extract sint24 from bytes.

pack(raw: int) → bytearray¶: Pack sint24 to bytes.

property byte_size: int¶

3 bytes.

Type:: Size

property signed: bool¶: Signed type.

class src.bluetooth_sig.gatt.characteristics.utils.extractors.Sint32Extractor(endian: Literal['little', 'big'] = 'little')¶

Bases: RawExtractor

Extract/pack signed 32-bit integers (-2147483648 to 2147483647).

extract(data: bytes | bytearray, offset: int = 0) → int¶: Extract sint32 from bytes.

pack(raw: int) → bytearray¶: Pack sint32 to bytes.

property byte_size: int¶

4 bytes.

Type:: Size

property signed: bool¶: Signed type.

class src.bluetooth_sig.gatt.characteristics.utils.extractors.Sint8Extractor¶

Bases: RawExtractor

Extract/pack signed 8-bit integers (-128 to 127).

extract(data: bytes | bytearray, offset: int = 0) → int¶: Extract sint8 from bytes.

pack(raw: int) → bytearray¶: Pack sint8 to bytes.

property byte_size: int¶

1 byte.

Type:: Size

property signed: bool¶: Signed type.

class src.bluetooth_sig.gatt.characteristics.utils.extractors.Uint16Extractor(endian: Literal['little', 'big'] = 'little')¶

Bases: RawExtractor

Extract/pack unsigned 16-bit integers (0 to 65535).

extract(data: bytes | bytearray, offset: int = 0) → int¶: Extract uint16 from bytes.

pack(raw: int) → bytearray¶: Pack uint16 to bytes.

property byte_size: int¶

2 bytes.

Type:: Size

property signed: bool¶: Unsigned type.

class src.bluetooth_sig.gatt.characteristics.utils.extractors.Uint24Extractor(endian: Literal['little', 'big'] = 'little')¶

Bases: RawExtractor

Extract/pack unsigned 24-bit integers (0 to 16777215).

extract(data: bytes | bytearray, offset: int = 0) → int¶: Extract uint24 from bytes.

pack(raw: int) → bytearray¶: Pack uint24 to bytes.

property byte_size: int¶

3 bytes.

Type:: Size

property signed: bool¶: Unsigned type.

class src.bluetooth_sig.gatt.characteristics.utils.extractors.Uint32Extractor(endian: Literal['little', 'big'] = 'little')¶

Bases: RawExtractor

Extract/pack unsigned 32-bit integers (0 to 4294967295).

extract(data: bytes | bytearray, offset: int = 0) → int¶: Extract uint32 from bytes.

pack(raw: int) → bytearray¶: Pack uint32 to bytes.

property byte_size: int¶

4 bytes.

Type:: Size

property signed: bool¶: Unsigned type.

class src.bluetooth_sig.gatt.characteristics.utils.extractors.Uint8Extractor¶

Bases: RawExtractor

Extract/pack unsigned 8-bit integers (0 to 255).

extract(data: bytes | bytearray, offset: int = 0) → int¶: Extract uint8 from bytes.

pack(raw: int) → bytearray¶: Pack uint8 to bytes.

property byte_size: int¶

1 byte.

Type:: Size

property signed: bool¶: Unsigned type.

src.bluetooth_sig.gatt.characteristics.utils.extractors.get_extractor(type_name: str) → RawExtractor | None¶

Get extractor for a GSS type string.

Parameters:: type_name – Type string from GSS FieldSpec.type (e.g., “sint16”, “uint8”).
Returns:: Matching RawExtractor singleton, or None if type is not recognized.

Examples

>>> extractor = get_extractor("sint16")
>>> raw = extractor.extract(data, offset=0)

src.bluetooth_sig.gatt.characteristics.utils.extractors.FLOAT32¶

src.bluetooth_sig.gatt.characteristics.utils.extractors.SINT16¶

src.bluetooth_sig.gatt.characteristics.utils.extractors.SINT24¶

src.bluetooth_sig.gatt.characteristics.utils.extractors.SINT32¶

src.bluetooth_sig.gatt.characteristics.utils.extractors.SINT8¶

src.bluetooth_sig.gatt.characteristics.utils.extractors.UINT16¶

src.bluetooth_sig.gatt.characteristics.utils.extractors.UINT24¶

src.bluetooth_sig.gatt.characteristics.utils.extractors.UINT32¶

src.bluetooth_sig.gatt.characteristics.utils.extractors.UINT8¶