Add new DeviceReader constructors

.github/workflows/build.yml

@@ -0,0 +1,37 @@
+# Builds the python environment; linter and formatting via ruff; type annotations via pyright;
+# tests via pytest; reports test coverage via pytest-cov.
+
+name: build
+on:
+  push:
+    branches: ['*']
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build_run_tests:
+    name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    if: github.event.pull_request.draft == false
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: [3.9, 3.11]
+      fail-fast: false
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+      - name: Install dependencies
+        run: pip install -e .[dev]
+
+      - name: ruff
+        run: ruff check .
+      - name: pyright
+        run: pyright . 
+      - name: pytest
+        run: pytest --cov harp

harp/__init__.py

@@ -1,3 +1,6 @@
 from harp.io import REFERENCE_EPOCH, MessageType, read
 from harp.reader import create_reader
 from harp.schema import read_schema
+
+
+__all__ = ["REFERENCE_EPOCH", "MessageType", "read", "create_reader", "read_schema"]

harp/_helpers.py

@@ -0,0 +1,20 @@
+import warnings
+import functools
+
+
+def deprecated(message):
+    # This decorator is only available from the stdlib warnings module in Python 3.13
+    # Making it available here for compatibility with older versions
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            warnings.warn(
+                f"Call to deprecated function {func.__name__}: {message}",
+                category=DeprecationWarning,
+                stacklevel=1,
+            )
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

harp/io.py

@@ -2,9 +2,10 @@
 from enum import IntEnum
 from os import PathLike
 from typing import Any, BinaryIO, Optional, Union
-from pandas._typing import Axes
+
 import numpy as np
 import pandas as pd
+from pandas._typing import Axes
 
 REFERENCE_EPOCH = datetime(1904, 1, 1)
 """The reference epoch for UTC harp time."""
@@ -73,29 +74,23 @@ def read(
     """
     data = np.fromfile(file, dtype=np.uint8)
     if len(data) == 0:
-        return pd.DataFrame(
-            columns=columns, index=pd.Index([], dtype=np.float64, name="Time")
-        )
+        return pd.DataFrame(columns=columns, index=pd.Index([], dtype=np.float64, name="Time"))
 
     if address is not None and address != data[2]:
         raise ValueError(f"expected address {address} but got {data[2]}")
 
     index = None
-    stride = data[1] + 2
+    stride = int(data[1] + 2)
     nrows = len(data) // stride
     payloadtype = data[4]
     payloadoffset = 5
     if payloadtype & 0x10 != 0:
-        seconds = np.ndarray(
-            nrows, dtype=np.uint32, buffer=data, offset=payloadoffset, strides=stride
-        )
+        seconds = np.ndarray(nrows, dtype=np.uint32, buffer=data, offset=payloadoffset, strides=stride)
         payloadoffset += 4
-        micros = np.ndarray(
-            nrows, dtype=np.uint16, buffer=data, offset=payloadoffset, strides=stride
-        )
+        micros = np.ndarray(nrows, dtype=np.uint16, buffer=data, offset=payloadoffset, strides=stride)
         payloadoffset += 2
         time = micros * _SECONDS_PER_TICK + seconds
-        payloadtype = payloadtype & ~0x10
+        payloadtype = payloadtype & ~np.uint8(0x10)
         if epoch is not None:
             time = epoch + pd.to_timedelta(time, "s")  # type: ignore
         index = pd.Series(time)
@@ -121,9 +116,7 @@ def read(
 
     result = pd.DataFrame(payload, index=index, columns=columns)
     if keep_type:
-        msgtype = np.ndarray(
-            nrows, dtype=np.uint8, buffer=data, offset=0, strides=stride
-        )
+        msgtype = np.ndarray(nrows, dtype=np.uint8, buffer=data, offset=0, strides=stride)
         msgtype = pd.Categorical.from_codes(msgtype, categories=_messagetypes)  # type: ignore
         result[MessageType.__name__] = msgtype
     return result

harp/model.py

@@ -5,17 +5,9 @@
 from __future__ import annotations
 
 from enum import Enum
-from typing import Dict, List, Optional, Union
-from typing_extensions import Annotated
+from typing import Annotated, Dict, List, Optional, Union
 
-from pydantic import (
-    BaseModel,
-    BeforeValidator,
-    ConfigDict,
-    Field,
-    RootModel,
-    field_serializer,
-)
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field, RootModel, field_serializer
 
 
 class PayloadType(str, Enum):
@@ -136,16 +128,12 @@ class Visibility(Enum):
 class Register(BaseModel):
     address: Annotated[
         int,
-        Field(
-            le=255, description="Specifies the unique 8-bit address of the register."
-        ),
+        Field(le=255, description="Specifies the unique 8-bit address of the register."),
     ]
     type: Annotated[PayloadType, BeforeValidator(lambda v: PayloadType[v])]
     length: Annotated[
         Optional[int],
-        Field(
-            ge=1, default=1, description="Specifies the length of the register payload."
-        ),
+        Field(ge=1, default=1, description="Specifies the length of the register payload."),
     ]
     access: Union[Access, List[Access]] = Field(
         ..., description="Specifies the expected use of the register."
@@ -191,12 +179,6 @@ class Registers(BaseModel):
 
 class Model(Registers):
     device: str = Field(..., description="Specifies the name of the device.")
-    whoAmI: int = Field(
-        ..., description="Specifies the unique identifier for this device type."
-    )
-    firmwareVersion: str = Field(
-        ..., description="Specifies the semantic version of the device firmware."
-    )
-    hardwareTargets: str = Field(
-        ..., description="Specifies the semantic version of the device hardware."
-    )
+    whoAmI: int = Field(..., description="Specifies the unique identifier for this device type.")
+    firmwareVersion: str = Field(..., description="Specifies the semantic version of the device firmware.")
+    hardwareTargets: str = Field(..., description="Specifies the semantic version of the device hardware.")