SY-3768: Oracle Prep 10: Fix Mypy Type Checking in Python Client

.github/actions/test-python/action.yaml

@@ -25,6 +25,10 @@ inputs:
     description: Whether to run mypy type checking
     required: false
     default: "true"
+  type_check_dir:
+    description: The directory to run mypy type checking in
+    required: false
+    default: "."
   format_check:
     description: Whether to run formatting checks (isort, black)
     required: false
@@ -62,7 +66,7 @@ runs:
 
     - name: Check types
       if: inputs.type_check == 'true'
-      run: uv run mypy .
+      run: uv run mypy ${{ inputs.type_check_dir }}
       shell: bash
       working-directory: ${{ inputs.directory }}
 

.github/workflows/test.client.yaml

@@ -267,7 +267,7 @@ jobs:
           coverage: true
           coverage_module: synnax
           coverage_flag: client-py
-          type_check: false
+          type_check_dir: "./synnax"
 
   ts:
     name: Test - TypeScript

client/py/examples/simulators/press.py

@@ -130,7 +130,7 @@ def _run_loop(self) -> None:
             with self.client.open_writer(
                 start=sy.TimeStamp.now(),
                 channels=[
-                    self.daq_time_ch.key,
+                    self.daq_time_ch.name,
                     "press_vlv_state",
                     "vent_vlv_state",
                     "press_pt",

client/py/examples/simulators/thermal.py

@@ -96,7 +96,7 @@ def _create_channels(self) -> None:
         client.write(
             now,
             {
-                self.daq_time.key: [now],
+                self.daq_time.name: [now],
                 "temp_sensor": [self.AMBIENT_TEMP],
                 "heater_state": [0],
             },
@@ -119,7 +119,7 @@ def _run_loop(self) -> None:
         ) as streamer:
             with self.client.open_writer(
                 start=sy.TimeStamp.now(),
-                channels=[self.daq_time.key, "temp_sensor", "heater_state"],
+                channels=[self.daq_time.name, "temp_sensor", "heater_state"],
                 name="Thermal Sim DAQ",
             ) as writer:
                 force_overheat = False

client/py/pyproject.toml

@@ -32,6 +32,7 @@ dev = [
     "black>=26.1.0,<27",
     "isort>=7.0.0,<8",
     "mypy>=1.19.1,<2",
+    "pandas-stubs>=2.0.0",
     "pymodbus>=3.11.4,<4",
     "pytest>=9.0.2,<10",
     "pytest-asyncio>=1.3.0,<2",
@@ -46,9 +47,14 @@ packages = ["synnax", "examples"]
 profile = "black"
 
 [tool.mypy]
-plugins = ["numpy.typing.mypy_plugin", "pydantic.mypy"]
+plugins = ["pydantic.mypy"]
 strict = true
 
+[[tool.mypy.overrides]]
+module = "nptdms.*"
+ignore_missing_imports = true
+follow_imports = "skip"
+
 [tool.pydantic-mypy]
 init_forbid_extra = true
 init_types = true
@@ -62,6 +68,7 @@ markers = [
     "channel: mark test as a channel test",
     "cli: mark test as a cli test",
     "control: mark test as a control test",
+    "deprecation: mark test as a deprecation test",
     "device: mark test as a device test",
     "ethercat: mark test as an ethercat test",
     "framer: mark test as a framer test",

client/py/synnax/__init__.py

@@ -20,7 +20,7 @@
     Handle,
     Position,
 )
-from synnax.arc import Task as ArcTask
+from synnax.arc import Task as _ArcTask
 from synnax.arc import (
     Text,
 )
@@ -57,8 +57,8 @@
 from synnax.ranger import Range
 from synnax.status import Status
 from synnax.synnax import Synnax
-from synnax.task import Status as TaskStatus
-from synnax.task import StatusDetails as TaskStatusDetails
+from synnax.task import Status as _TaskStatus
+from synnax.task import StatusDetails as _TaskStatusDetails
 from synnax.task import Task
 from synnax.telem import (
     Alignment,
@@ -86,13 +86,20 @@
 )
 from synnax.timing import Loop, Timer, sleep
 from synnax.user.payload import User
+from synnax.util.deprecation import deprecated_getattr
 
-SynnaxOptions = Options
+_DEPRECATED: dict[str, str | tuple[str, str]] = {
+    "ArcTask": ("synnax.arc.Task", "_ArcTask"),
+    "TaskStatus": ("synnax.task.Status", "_TaskStatus"),
+    "TaskStatusDetails": ("synnax.task.StatusDetails", "_TaskStatusDetails"),
+    "SynnaxOptions": "Options",
+}
+
+__getattr__ = deprecated_getattr(__name__, _DEPRECATED, globals())
 
 __all__ = [
     "Alignment",
     "Arc",
-    "ArcTask",
     "AUTO_SPAN",
     "AuthError",
     "Authority",
@@ -143,10 +150,7 @@
     "Status",
     "Streamer",
     "Synnax",
-    "SynnaxOptions",
     "Task",
-    "TaskStatus",
-    "TaskStatusDetails",
     "Text",
     "Timer",
     "TimeRange",
@@ -165,4 +169,5 @@
     "ni",
     "opcua",
     "status",
+    "Status",
 ]

client/py/synnax/access/policy/__init__.py

@@ -16,13 +16,17 @@
     Policy,
     ontology_id,
 )
+from synnax.util.deprecation import deprecated_getattr
 
-# Backwards compatibility
-PolicyClient = Client
-CREATE_ACTION = ACTION_CREATE
-DELETE_ACTION = ACTION_DELETE
-RETRIEVE_ACTION = ACTION_RETRIEVE
-UPDATE_ACTION = ACTION_UPDATE
+_DEPRECATED = {
+    "PolicyClient": "Client",
+    "CREATE_ACTION": "ACTION_CREATE",
+    "DELETE_ACTION": "ACTION_DELETE",
+    "RETRIEVE_ACTION": "ACTION_RETRIEVE",
+    "UPDATE_ACTION": "ACTION_UPDATE",
+}
+
+__getattr__ = deprecated_getattr(__name__, _DEPRECATED, globals())
 
 __all__ = [
     "Client",
@@ -32,9 +36,4 @@
     "ACTION_RETRIEVE",
     "ACTION_UPDATE",
     "ontology_id",
-    "PolicyClient",
-    "CREATE_ACTION",
-    "DELETE_ACTION",
-    "RETRIEVE_ACTION",
-    "UPDATE_ACTION",
 ]

client/py/synnax/access/policy/payload.py

@@ -34,8 +34,13 @@ def ontology_id(key: UUID | None = None) -> ontology.ID:
     return ontology.ID(type="policy", key=key if key is None else str(key))
 
 
-# Backwards compatibility
-CREATE_ACTION = ACTION_CREATE
-DELETE_ACTION = ACTION_DELETE
-RETRIEVE_ACTION = ACTION_RETRIEVE
-UPDATE_ACTION = ACTION_UPDATE
+from synnax.util.deprecation import deprecated_getattr
+
+_DEPRECATED = {
+    "CREATE_ACTION": "ACTION_CREATE",
+    "DELETE_ACTION": "ACTION_DELETE",
+    "RETRIEVE_ACTION": "ACTION_RETRIEVE",
+    "UPDATE_ACTION": "ACTION_UPDATE",
+}
+
+__getattr__ = deprecated_getattr(__name__, _DEPRECATED, globals())

client/py/synnax/access/role/__init__.py

@@ -10,8 +10,12 @@
 
 from synnax.access.role.client import Client
 from synnax.access.role.payload import ONTOLOGY_TYPE, Role, ontology_id
+from synnax.util.deprecation import deprecated_getattr
 
-# Backwards compatibility
-RoleClient = Client
+_DEPRECATED = {
+    "RoleClient": "Client",
+}
 
-__all__ = ["Role", "Client", "ONTOLOGY_TYPE", "ontology_id", "RoleClient"]
+__getattr__ = deprecated_getattr(__name__, _DEPRECATED, globals())
+
+__all__ = ["Role", "Client", "ONTOLOGY_TYPE", "ontology_id"]

client/py/synnax/access/role/client.py

@@ -65,7 +65,7 @@ def __init__(
     @overload
     def create(
         self,
-        role: Role,
+        roles: Role,
     ) -> Role: ...
 
     @overload
@@ -89,6 +89,7 @@ def retrieve(self, key: UUID) -> Role: ...
     @overload
     def retrieve(
         self,
+        *,
         keys: list[UUID] | None = None,
         limit: int | None = None,
         offset: int | None = None,
@@ -104,7 +105,7 @@ def retrieve(
         internal: bool | None = None,
     ) -> Role | list[Role]:
         is_single = key is not None
-        if is_single:
+        if is_single and key is not None:
             keys = [key]
         req = _RetrieveRequest(keys=keys, limit=limit, offset=offset, internal=internal)
         res = send_required(

client/py/synnax/arc/__init__.py

@@ -20,14 +20,18 @@
     Text,
 )
 from synnax.arc.types import Task, TaskConfig
+from synnax.util.deprecation import deprecated_getattr
 
-# Backwards compatibility
-ArcTask = Task
-ArcTaskConfig = TaskConfig
-ArcClient = Client
-ArcKey = Key
-ArcMode = Mode
-ArcPayload = Payload
+_DEPRECATED = {
+    "ArcTask": "Task",
+    "ArcTaskConfig": "TaskConfig",
+    "ArcClient": "Client",
+    "ArcKey": "Key",
+    "ArcMode": "Mode",
+    "ArcPayload": "Payload",
+}
+
+__getattr__ = deprecated_getattr(__name__, _DEPRECATED, globals())
 
 __all__ = [
     "Arc",
@@ -43,10 +47,4 @@
     "Handle",
     "Position",
     "Text",
-    "ArcTask",
-    "ArcTaskConfig",
-    "ArcClient",
-    "ArcKey",
-    "ArcMode",
-    "ArcPayload",
 ]

client/py/synnax/arc/payload.py

@@ -98,8 +98,13 @@ class Payload(BaseModel):
     """Visual graph representation of the program."""
 
 
-# Backwards compatibility
-ARC_ONTOLOGY_TYPE = ONTOLOGY_TYPE
-ArcKey = Key
-ArcMode = Mode
-ArcPayload = Payload
+from synnax.util.deprecation import deprecated_getattr
+
+_DEPRECATED = {
+    "ARC_ONTOLOGY_TYPE": "ONTOLOGY_TYPE",
+    "ArcKey": "Key",
+    "ArcMode": "Mode",
+    "ArcPayload": "Payload",
+}
+
+__getattr__ = deprecated_getattr(__name__, _DEPRECATED, globals())

client/py/synnax/arc/types.py

@@ -57,6 +57,11 @@ def __init__(
         self.config = TaskConfig(arc_key=str(arc_key), auto_start=auto_start)
 
 
-# Backwards compatibility
-ArcTask = Task
-ArcTaskConfig = TaskConfig
+from synnax.util.deprecation import deprecated_getattr
+
+_DEPRECATED = {
+    "ArcTask": "Task",
+    "ArcTaskConfig": "TaskConfig",
+}
+
+__getattr__ = deprecated_getattr(__name__, _DEPRECATED, globals())

client/py/synnax/auth.py

@@ -69,8 +69,8 @@ def authenticate(self) -> None:
         self.user = res.user
         self.authenticated = True
 
-    def middleware(self) -> list[Middleware]:
-        def mw(ctx: Context, _next: Next):
+    def middleware(self) -> Middleware:
+        def mw(ctx: Context, _next: Next) -> tuple[Context, Exception | None]:
             if not self.authenticated:
                 self.authenticate()
 
@@ -86,8 +86,10 @@ def mw(ctx: Context, _next: Next):
 
         return mw
 
-    def async_middleware(self) -> list[AsyncMiddleware]:
-        async def mw(ctx: Context, _next: AsyncNext):
+    def async_middleware(self) -> AsyncMiddleware:
+        async def mw(
+            ctx: Context, _next: AsyncNext
+        ) -> tuple[Context, Exception | None]:
             if not self.authenticated:
                 self.authenticate()
 
@@ -112,5 +114,10 @@ def maybe_refresh_token(
             self.token = refresh
 
 
-# Backwards compatibility
-AuthenticationClient = Client
+from synnax.util.deprecation import deprecated_getattr
+
+_DEPRECATED = {
+    "AuthenticationClient": "Client",
+}
+
+__getattr__ = deprecated_getattr(__name__, _DEPRECATED, globals())