refactor(api)!: replace Timing class with signed int timings (#19)

Co-authored-by: Claude <noreply@anthropic.com>

Author: balloob

AGENTS.md

@@ -77,7 +77,7 @@ pytest tests/test_commands.py::test_nec_command_get_raw_timings_standard
 ```
 infrared_protocols/      # Library source (only this directory is linted/type-checked)
     __init__.py          # Public API: defines __all__ and re-exports
-    commands.py          # All domain logic: Command ABC, NECCommand, Timing
+    commands.py          # All domain logic: Command ABC, NECCommand
 tests/
     test_commands.py     # pytest suite (all tests in one file)
 script/
@@ -111,7 +111,7 @@ pyproject.toml           # Build config, ruff rules, pyright settings
 |---|---|---|
 | Files / modules | `snake_case` | `commands.py` |
 | Packages | `snake_case` | `infrared_protocols` |
-| Classes | `PascalCase` | `NECCommand`, `Timing` |
+| Classes | `PascalCase` | `NECCommand`, `Command` |
 | Functions / methods | `snake_case` | `get_raw_timings` |
 | Variables / attributes | `snake_case` | `high_us`, `repeat_count` |
 | Local numeric constants | `snake_case` (not `UPPER_CASE`) | `leader_high = 9000` |
@@ -125,11 +125,11 @@ pyproject.toml           # Build config, ruff rules, pyright settings
 - Type checker: `basedpyright` with `typeCheckingMode = "standard"`.
 - **All** function parameters and return types must be annotated.
 - `-> None` must be explicit on `__init__` and void methods.
-- Use PEP 585 lowercase generics: `list[Timing]`, not `List[Timing]`.
+- Use PEP 585 lowercase generics: `list[int]`, not `List[int]`.
 - Use PEP 604 union syntax: `T | None`, not `Optional[T]`.
 - Use `@override` (from `typing`, Python 3.12+) on every overridden method.
 - No `Any`; avoid `cast`; prefer real type narrowing.
-- Inline variable annotations where needed: `timings: list[Timing] = []`.
+- Inline variable annotations where needed: `timings: list[int] = []`.
 
 ### Classes
 - Abstract base classes use `abc.ABC` and `@abc.abstractmethod`.
@@ -144,7 +144,7 @@ pyproject.toml           # Build config, ruff rules, pyright settings
   parameter sections unless complexity demands it.
 
 ```python
-def get_raw_timings(self) -> list[Timing]:
+def get_raw_timings(self) -> list[int]:
     """Get raw timings for the NEC command.
 
     NEC protocol timing (in microseconds):
@@ -159,33 +159,36 @@ def get_raw_timings(self) -> list[Timing]:
 
 ### Adding a New Protocol
 1. Subclass `Command` (ABC) in `infrared_protocols/commands.py`.
-2. Implement `get_raw_timings(self) -> list[Timing]`.
+2. Implement `get_raw_timings(self) -> list[int]`.
 3. Decorate the override with `@override`.
 4. Define timing constants as local `snake_case` variables inside the method.
 5. Re-export the new class from `infrared_protocols/__init__.py` and add it to
    `__all__`.
 
 ### Key Abstractions
-- **`Timing(high_us, low_us)`** — frozen dataclass representing one pulse+space pair
-  (microseconds). Immutable, comparable by value.
+- **Raw timings** — a flat `list[int]` of microsecond durations. Positive values are
+  pulse (high) durations; negative values are space (low) durations. A transmission
+  that ends on a pulse is represented by a trailing positive int with no paired
+  space.
 - **`Command` (ABC)** — base class for all IR protocol encoders. Holds `modulation`
   and `repeat_count`.
 - **`NECCommand(Command)`** — encodes the NEC protocol; reference implementation.
 
 ### Patterns to Follow
-- Build timing lists by starting with a base list, appending in a loop, then using
-  `extend()` for repeat frames.
-- Repeat-code frame gaps replace the last timing's `low_us` (see `NECCommand`).
+- Build timing lists by starting with a base list, appending pulse/space ints in a
+  loop, then using `extend()` for repeat frames.
+- Repeat-code frame gaps are appended as a negative int directly after the preceding
+  end-pulse (see `NECCommand`).
 - Bit manipulation uses masks like `data & 1`, `data >>= 1`, `(~x) & 0xFF`.
 
 ---
 
 ## Testing
 
 - No mocking. Tests use pure value comparison against manually constructed
-  `list[Timing]` fixtures.
+  `list[int]` fixtures of signed pulse/space durations.
 - One assertion per logical case; reuse expected values with list unpacking
-  (`[*expected[:-1], ...]`) rather than duplicating fixtures.
+  (`[*expected, ...]`) rather than duplicating fixtures.
 - Tests live in `tests/test_commands.py`; keep them in one file unless the suite
   grows substantially.
 - Pre-commit hooks (`prek`) do **not** run on `tests/`; the type checker and linter

infrared_protocols/__init__.py

@@ -1,9 +1,8 @@
 """Library to decode and encode infrared signals."""
 
-from .commands import Command, NECCommand, Timing
+from .commands import Command, NECCommand
 
 __all__ = [
     "Command",
     "NECCommand",
-    "Timing",
 ]

infrared_protocols/commands.py

@@ -1,18 +1,9 @@
 """Common IR command definitions."""
 
 import abc
-from dataclasses import dataclass
 from typing import override
 
 
-@dataclass(frozen=True, slots=True)
-class Timing:
-    """High/low signal timing."""
-
-    high_us: int
-    low_us: int
-
-
 class Command(abc.ABC):
     """Base class for IR commands."""
 
@@ -25,8 +16,12 @@ def __init__(self, *, modulation: int, repeat_count: int = 0) -> None:
         self.repeat_count = repeat_count
 
     @abc.abstractmethod
-    def get_raw_timings(self) -> list[Timing]:
-        """Get raw timings for the command."""
+    def get_raw_timings(self) -> list[int]:
+        """Get raw timings for the command.
+
+        Positive values are pulse (high) durations in microseconds; negative
+        values are space (low) durations in microseconds.
+        """
 
 
 class NECCommand(Command):
@@ -49,7 +44,7 @@ def __init__(
         self.command = command
 
     @override
-    def get_raw_timings(self) -> list[Timing]:
+    def get_raw_timings(self) -> list[int]:
         """Get raw timings for the NEC command.
 
         NEC protocol timing (in microseconds):
@@ -76,7 +71,7 @@ def get_raw_timings(self) -> list[Timing]:
         initial_frame_gap = 41000  # Gap to make total frame ~108ms
         frame_gap = 96000  # Gap to make total frame ~108ms
 
-        timings: list[Timing] = [Timing(high_us=leader_high, low_us=leader_low)]
+        timings: list[int] = [leader_high, -leader_low]
 
         # Determine if standard (8-bit) or extended (16-bit) address
         if self.address <= 0xFF:
@@ -101,29 +96,17 @@ def get_raw_timings(self) -> list[Timing]:
 
         for _ in range(32):
             bit = data & 1
-            if bit:
-                timings.append(Timing(high_us=bit_high, low_us=one_low))
-            else:
-                timings.append(Timing(high_us=bit_high, low_us=zero_low))
+            timings.append(bit_high)
+            timings.append(-one_low if bit else -zero_low)
             data >>= 1
 
         # End pulse
-        timings.append(Timing(high_us=bit_high, low_us=0))
+        timings.append(bit_high)
 
         # Add repeat codes if requested
         gap = initial_frame_gap
         for _ in range(self.repeat_count):
-            # Replace the last timing's low_us with the frame gap
-            last_timing = timings[-1]
-            timings[-1] = Timing(high_us=last_timing.high_us, low_us=gap)
+            timings.extend([-gap, leader_high, -repeat_low, bit_high])
             gap = frame_gap  # Use standard frame gap for subsequent repeats
 
-            # Repeat code: leader burst + shorter space + end pulse
-            timings.extend(
-                [
-                    Timing(high_us=leader_high, low_us=repeat_low),
-                    Timing(high_us=bit_high, low_us=0),
-                ]
-            )
-
         return timings