src.bluetooth_sig.gatt.services.base¶

Base class for GATT service implementations.

Attributes¶

Name	Description
`GattCharacteristic`
`ServiceCharacteristicCollection`
`ServiceCharacteristics`

Classes¶

Name	Description
`BaseGattService`	Base class for all GATT services.
`CharacteristicStatus`	Status of characteristics within a service.
`SIGServiceResolver`	Resolves SIG service information from registry.
`ServiceCharacteristicInfo`	Service-specific information about a characteristic with context about its presence.
`ServiceCompletenessReport`	Comprehensive report about service completeness and health.
`ServiceHealthStatus`	Health status of a GATT service.
`ServiceValidationConfig`	Configuration for service validation constraints.
`ServiceValidationResult`	Result of service validation.

Module Contents¶

class src.bluetooth_sig.gatt.services.base.BaseGattService(info: src.bluetooth_sig.types.ServiceInfo | None = None, validation: ServiceValidationConfig | None = None)¶

Base class for all GATT services.

Automatically resolves UUID, name, and summary from Bluetooth SIG specifications. Follows the same pattern as BaseCharacteristic for consistency.

get_characteristic(uuid: src.bluetooth_sig.types.uuid.BluetoothUUID) → GattCharacteristic[Any] | None¶: Get a characteristic by UUID.

get_characteristic_status(characteristic_name: src.bluetooth_sig.gatt.characteristics.registry.CharacteristicName) → ServiceCharacteristicInfo | None¶

Get detailed status of a specific characteristic.

Parameters:: characteristic_name – CharacteristicName enum
Returns:: CharacteristicInfo if characteristic is expected by this service, None otherwise

classmethod get_characteristics_schema() → type | None¶

Get the TypedDict schema for this service’s characteristics.

Override this method to provide strong typing for characteristics. If not implemented, falls back to get_expected_characteristics().

Returns:: TypedDict class defining the service’s characteristics, or None

classmethod get_class_uuid() → src.bluetooth_sig.types.uuid.BluetoothUUID¶

Get the UUID for this service class without instantiation.

Returns:: BluetoothUUID for this service class
Raises:: UUIDResolutionError – If UUID cannot be resolved

classmethod get_conditional_characteristics() → ServiceCharacteristicCollection¶

Get characteristics that are required only under certain conditions.

Returns:: ServiceCharacteristicCollection mapping characteristic name to CharacteristicSpec

Override in subclasses to specify conditional characteristics.

get_expected_characteristic_uuids() → set[src.bluetooth_sig.types.uuid.BluetoothUUID]¶: Get the set of expected characteristic UUIDs for this service.

classmethod get_expected_characteristics() → ServiceCharacteristicCollection¶

Get the expected characteristics for this service from the service_characteristics dict.

Looks for a ‘service_characteristics’ class attribute containing a dictionary of: CharacteristicName -> required flag, and automatically builds CharacteristicSpec objects.

Returns:: ServiceCharacteristicCollection mapping characteristic name to CharacteristicSpec

get_missing_characteristics() → dict[src.bluetooth_sig.gatt.characteristics.registry.CharacteristicName, ServiceCharacteristicInfo]¶

Get detailed information about missing characteristics.

Returns:: Dict mapping characteristic name to ServiceCharacteristicInfo

classmethod get_name() → str¶

Get the service name for this class without creating an instance.

Returns:: The service name as registered in the UUID registry.

classmethod get_optional_characteristics() → ServiceCharacteristicCollection¶

Get the optional characteristics for this service by name and class.

Returns:: ServiceCharacteristicCollection mapping characteristic name to CharacteristicSpec

classmethod get_required_characteristic_keys() → set[src.bluetooth_sig.gatt.characteristics.registry.CharacteristicName]¶

Get the set of required characteristic keys from the schema.

Override this method when using strongly-typed characteristics. If not implemented, falls back to get_required_characteristics().keys().

Returns:: Set of required characteristic field names

get_required_characteristic_uuids() → set[src.bluetooth_sig.types.uuid.BluetoothUUID]¶: Get the set of required characteristic UUIDs for this service.

classmethod get_required_characteristics() → ServiceCharacteristicCollection¶

Get the required characteristics for this service from the characteristics dict.

Automatically filters the characteristics dictionary for required=True entries.

Returns:: ServiceCharacteristicCollection mapping characteristic name to CharacteristicSpec

get_service_completeness_report() → ServiceCompletenessReport¶

Get a comprehensive report about service completeness.

Returns:: ServiceCompletenessReport with detailed service status information

has_minimum_functionality() → bool¶

Check if service has minimum required functionality.

Returns:: True if service has all required characteristics and is usable

classmethod matches_uuid(uuid: str | src.bluetooth_sig.types.uuid.BluetoothUUID) → bool¶: Check if this service matches the given UUID.

process_characteristics(characteristics: src.bluetooth_sig.types.gatt_services.ServiceDiscoveryData) → None¶

Process the characteristics for this service (default implementation).

Parameters:: characteristics – Dict mapping UUID to characteristic info

classmethod validate_bluetooth_sig_compliance() → list[str]¶

Validate compliance with Bluetooth SIG service specification.

Returns:: List of compliance issues found

Override in subclasses to provide service-specific validation.

validate_service(strict: bool = False) → ServiceValidationResult¶

Validate the completeness and health of this service.

Parameters:: strict – If True, missing optional characteristics are treated as warnings
Returns:: ServiceValidationResult with detailed status information

characteristics: dict[src.bluetooth_sig.types.uuid.BluetoothUUID, src.bluetooth_sig.gatt.characteristics.BaseCharacteristic[Any]]¶

property info: src.bluetooth_sig.types.ServiceInfo¶

Return the resolved service information for this instance.

The info property provides all metadata about the service, including UUID, name, and description.

property name: str¶: Get the service name from _info.

property supported_characteristics: set[src.bluetooth_sig.gatt.characteristics.BaseCharacteristic[Any]]¶: Get the set of characteristic UUIDs supported by this service.

property uuid: src.bluetooth_sig.types.uuid.BluetoothUUID¶: Get the service UUID from _info.

class src.bluetooth_sig.gatt.services.base.CharacteristicStatus(*args, **kwds)¶

Bases: enum.Enum

Status of characteristics within a service.

INVALID = 'invalid'¶

MISSING = 'missing'¶

PRESENT = 'present'¶

class src.bluetooth_sig.gatt.services.base.SIGServiceResolver¶

Resolves SIG service information from registry.

This class handles all SIG service resolution logic, separating concerns from the BaseGattService constructor. Uses shared utilities from the resolver module to avoid code duplication with characteristic resolution.

static resolve_for_class(service_class: type[BaseGattService]) → src.bluetooth_sig.types.ServiceInfo¶

Resolve ServiceInfo for a SIG service class.

Parameters:: service_class – The service class to resolve info for
Returns:: ServiceInfo with resolved UUID, name, summary
Raises:: UUIDResolutionError – If no UUID can be resolved for the class

static resolve_from_registry(service_class: type[BaseGattService]) → src.bluetooth_sig.types.ServiceInfo | None¶: Resolve service info from registry using shared search strategy.

class src.bluetooth_sig.gatt.services.base.ServiceCharacteristicInfo¶

Bases: src.bluetooth_sig.types.CharacteristicInfo

Service-specific information about a characteristic with context about its presence.

Provides status, requirement, and class context for a characteristic within a service.

char_class: type[src.bluetooth_sig.gatt.characteristics.BaseCharacteristic[Any]] | None = None¶

condition_description: str = ''¶

is_conditional: bool = False¶

is_required: bool = False¶

status: CharacteristicStatus¶

class src.bluetooth_sig.gatt.services.base.ServiceCompletenessReport¶

Bases: msgspec.Struct

Comprehensive report about service completeness and health.

characteristics_expected: int¶

characteristics_present: int¶

characteristics_required: int¶

errors: list[str]¶

health_status: ServiceHealthStatus¶

invalid_characteristics: list[src.bluetooth_sig.gatt.characteristics.BaseCharacteristic[Any]]¶

is_healthy: bool¶

missing_details: dict[str, ServiceCharacteristicInfo]¶

missing_optional: list[src.bluetooth_sig.gatt.characteristics.BaseCharacteristic[Any]]¶

missing_required: list[src.bluetooth_sig.gatt.characteristics.BaseCharacteristic[Any]]¶

present_characteristics: list[src.bluetooth_sig.gatt.characteristics.BaseCharacteristic[Any]]¶

service_name: str¶

service_uuid: src.bluetooth_sig.types.uuid.BluetoothUUID¶

warnings: list[str]¶

class src.bluetooth_sig.gatt.services.base.ServiceHealthStatus(*args, **kwds)¶

Bases: enum.Enum

Health status of a GATT service.

COMPLETE = 'complete'¶

FUNCTIONAL = 'functional'¶

INCOMPLETE = 'incomplete'¶

PARTIAL = 'partial'¶

class src.bluetooth_sig.gatt.services.base.ServiceValidationConfig¶

Bases: msgspec.Struct

Configuration for service validation constraints.

Groups validation parameters into a single, optional configuration object to simplify BaseGattService constructor signatures.

require_all_optional: bool = False¶

strict_validation: bool = False¶

class src.bluetooth_sig.gatt.services.base.ServiceValidationResult¶

Bases: msgspec.Struct

Result of service validation.

errors: list[str]¶

property has_errors: bool¶: Check if service has any errors.

invalid_characteristics: list[src.bluetooth_sig.gatt.characteristics.BaseCharacteristic[Any]]¶

property is_healthy: bool¶: Check if service is in a healthy state.

missing_optional: list[src.bluetooth_sig.gatt.characteristics.BaseCharacteristic[Any]]¶

missing_required: list[src.bluetooth_sig.gatt.characteristics.BaseCharacteristic[Any]]¶

status: ServiceHealthStatus¶

warnings: list[str]¶

src.bluetooth_sig.gatt.services.base.GattCharacteristic¶

src.bluetooth_sig.gatt.services.base.ServiceCharacteristicCollection¶

src.bluetooth_sig.gatt.services.base.ServiceCharacteristics¶