fix: type correctness audit and lint cleanup

- Remove _python_type overrides from 40 characteristic classes (metadata-only,
  not used for decoding; contradicted BaseCharacteristic[T] generic param)
- Remove _manual_role from 10 enum characteristics (classifier rule 12 handles
  enum→STATUS automatically)
- Enforce list[CharacteristicTestData] return type in valid_test_data fixture
  (base class + 55 subclass test files); remove isinstance guards
- Move Appearance, PnP ID, System ID from MEASUREMENT to INFO test group
  (they have _manual_role=INFO — device metadata, not sensor data)
- Refactor classify_role() into 5 tier functions to fix PLR0911 (too many
  return statements) and remove ERA001 false-positive comment
- Fix test_alert_level: pass AlertLevel(int) instead of raw int to build_value()
- Fix examples: remove invalid properties kwarg from BaseCharacteristic and
  UnknownCharacteristic constructors in 3 connection manager examples
- Fix test_readme_badges: add socket_enabled fixture and graceful skip when
  pytest-socket blocks network access
- Fix test_magnetic_flux_density_2d/3d: correct python_type assertions

Author: RonanB96

examples/connection_managers/bleak_retry.py

@@ -192,16 +192,15 @@ async def get_services(self) -> list[DeviceService]:
                     char_class = CharacteristicRegistry.get_characteristic_class_by_uuid(char_uuid)
 
                     if char_class:
-                        # Create characteristic instance with runtime properties from device
-                        char_instance = char_class(properties=properties)
+                        char_instance = char_class()
                         characteristics[str(char_uuid)] = char_instance
                     else:
                         # Fallback: Create UnknownCharacteristic for unrecognized UUIDs
                         char_info = CharacteristicInfo(
                             uuid=char_uuid,
                             name=char.description or f"Unknown Characteristic ({char_uuid.short_form}...)",
                         )
-                        char_instance = UnknownCharacteristic(info=char_info, properties=properties)
+                        char_instance = UnknownCharacteristic(info=char_info)
                         characteristics[str(char_uuid)] = char_instance
 
                 # Type ignore needed due to dict invariance with union types

examples/connection_managers/bluepy.py

@@ -279,16 +279,15 @@ def _get_services() -> list[DeviceService]:
                         char_class = CharacteristicRegistry.get_characteristic_class_by_uuid(char_uuid)
 
                         if char_class:
-                            # Create characteristic instance with runtime properties from device
-                            char_instance = char_class(properties=properties)
+                            char_instance = char_class()
                             characteristics[str(char_uuid)] = char_instance
                         else:
                             # Fallback: Create UnknownCharacteristic for unrecognized UUIDs
                             char_info = CharacteristicInfo(
                                 uuid=char_uuid,
                                 name=f"Unknown Characteristic ({char_uuid.short_form}...)",
                             )
-                            char_instance = UnknownCharacteristic(info=char_info, properties=properties)
+                            char_instance = UnknownCharacteristic(info=char_info)
                             characteristics[str(char_uuid)] = char_instance
 
                     # Type ignore needed due to dict invariance with union types

examples/connection_managers/simpleble.py

@@ -285,16 +285,15 @@ def _get_services() -> list[DeviceService]:
                     char_class = CharacteristicRegistry.get_characteristic_class_by_uuid(char_uuid)
 
                     if char_class:
-                        # Create characteristic instance with runtime properties from device
-                        char_instance = char_class(properties=properties)
+                        char_instance = char_class()
                         characteristics[str(char_uuid)] = char_instance
                     else:
                         # Fallback: Create UnknownCharacteristic for unrecognized UUIDs
                         char_info = CharacteristicInfo(
                             uuid=char_uuid,
                             name=f"Unknown Characteristic ({char_uuid.short_form}...)",
                         )
-                        char_instance = UnknownCharacteristic(info=char_info, properties=properties)
+                        char_instance = UnknownCharacteristic(info=char_info)
                         characteristics[str(char_uuid)] = char_instance
 
                 # Type ignore needed due to dict invariance with union types

scripts/ble_device_debugger.py

@@ -123,9 +123,7 @@ async def debug_ble_device(target_address: str) -> None:
                                     try:
                                         if len(value) == 1:
                                             int_val = value[0]
-                                        elif len(value) == 2:
-                                            int_val = int.from_bytes(value, byteorder="little")
-                                        elif len(value) == 4:
+                                        elif len(value) == 2 or len(value) == 4:
                                             int_val = int.from_bytes(value, byteorder="little")
                                         else:
                                             int_val = None

scripts/extract_validation_info.py

@@ -47,19 +47,18 @@
 import importlib
 import inspect
 import json
-import tempfile
-from pathlib import Path
-from typing import Any
 
 # Add src to path
 import sys
+import tempfile
+from pathlib import Path
+from typing import Any
 
 src_path = Path(__file__).parent.parent / "src"
 if str(src_path) not in sys.path:
     sys.path.insert(0, str(src_path))
 
 from bluetooth_sig.gatt.characteristics.base import BaseCharacteristic
-from bluetooth_sig.types.gatt_enums import ValueType
 
 
 def get_all_characteristic_classes() -> list[type[BaseCharacteristic]]:
@@ -349,7 +348,7 @@ def main() -> None:
     # Generate report
     try:
         generate_validation_report(output_file)
-        print(f"\n📊 Report summary:")
+        print("\n📊 Report summary:")
         print(f"   Output file: {output_file}")
 
         # Show stats
@@ -362,14 +361,14 @@ def main() -> None:
             if with_errors:
                 print(f"   With errors: {with_errors}")
 
-        print(f"\n📋 Output format:")
-        print(f"   Each value includes a 'source' field indicating origin:")
-        print(f"   - resolved_sig_info: From Bluetooth SIG registry")
-        print(f"   - yaml_spec: From Bluetooth SIG YAML specifications")
-        print(f"   - class_level_or_yaml: From characteristic class or YAML defaults")
-        print(f"   - manual_override: Explicit manual override")
-        print(f"   - runtime_descriptor_check: Discovered at runtime")
-        print(f"   - (see script header for full source legend)")
+        print("\n📋 Output format:")
+        print("   Each value includes a 'source' field indicating origin:")
+        print("   - resolved_sig_info: From Bluetooth SIG registry")
+        print("   - yaml_spec: From Bluetooth SIG YAML specifications")
+        print("   - class_level_or_yaml: From characteristic class or YAML defaults")
+        print("   - manual_override: Explicit manual override")
+        print("   - runtime_descriptor_check: Discovered at runtime")
+        print("   - (see script header for full source legend)")
 
     except Exception as e:
         print(f"❌ Error: {e}", file=sys.stderr)

scripts/test_real_device.py

@@ -9,7 +9,6 @@
 import logging
 import sys
 from pathlib import Path
-from typing import Optional
 
 # Configure path for imports
 script_dir = Path(__file__).parent
@@ -32,7 +31,7 @@
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 
 
-async def test_device_connection(mac_address: str) -> Optional[bool]:
+async def test_device_connection(mac_address: str) -> bool | None:
     """Test connection to a real device using Bleak."""
     print(f"\n🔍 Testing connection to device: {mac_address}")
     print("=" * 60)

src/bluetooth_sig/gatt/characteristics/acceleration_detection_status.py

@@ -3,9 +3,10 @@
 from __future__ import annotations
 
 from enum import IntEnum
+from typing import cast
 
 from .base import BaseCharacteristic
-from .templates import EnumTemplate
+from .templates import CodingTemplate, EnumTemplate
 
 
 class AccelerationDetectionStatus(IntEnum):
@@ -15,12 +16,12 @@ class AccelerationDetectionStatus(IntEnum):
     CHANGE_DETECTED = 1
 
 
-class AccelerationDetectionStatusCharacteristic(BaseCharacteristic[int]):
+class AccelerationDetectionStatusCharacteristic(BaseCharacteristic[AccelerationDetectionStatus]):
     """Acceleration Detection Status characteristic (0x2C0B).
 
     org.bluetooth.characteristic.acceleration_detection_status
 
     The Acceleration Detection Status characteristic represents the status of detected acceleration.
     """
 
-    _template = EnumTemplate.uint8(AccelerationDetectionStatus)
+    _template = cast(CodingTemplate[AccelerationDetectionStatus], EnumTemplate.uint8(AccelerationDetectionStatus))

src/bluetooth_sig/gatt/characteristics/alert_level.py

@@ -22,7 +22,7 @@ class AlertLevel(IntEnum):
     HIGH_ALERT = 0x02
 
 
-class AlertLevelCharacteristic(BaseCharacteristic[int]):
+class AlertLevelCharacteristic(BaseCharacteristic[AlertLevel]):
     """Alert Level characteristic (0x2A06).
 
     org.bluetooth.characteristic.alert_level

src/bluetooth_sig/gatt/characteristics/appearance.py

@@ -4,6 +4,7 @@
 
 from ...registry.core.appearance_values import appearance_values_registry
 from ...types.appearance import AppearanceData
+from ...types.gatt_enums import CharacteristicRole
 from ..context import CharacteristicContext
 from .base import BaseCharacteristic
 from .utils import DataParser
@@ -17,6 +18,7 @@ class AppearanceCharacteristic(BaseCharacteristic[AppearanceData]):
     Appearance characteristic with human-readable device type information.
     """
 
+    _manual_role = CharacteristicRole.INFO
     expected_length = 2
 
     def _decode_value(

src/bluetooth_sig/gatt/characteristics/blood_pressure_common.py

@@ -51,8 +51,6 @@ class BaseBloodPressureCharacteristic(BaseCharacteristic[Any]):
 
     _is_base_class = True  # Exclude from characteristic discovery
 
-    _python_type = str  # Override since decode_value returns dataclass
-
     # Declare optional dependency on Blood Pressure Feature for status interpretation
     _optional_dependencies: ClassVar[list[type[BaseCharacteristic[Any]]]] = [BloodPressureFeatureCharacteristic]