Python/mkdocs init

python/docs/index.md

@@ -0,0 +1,17 @@
+# Welcome to MkDocs
+
+For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+
+## Commands
+
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
+
+## Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.

python/griffe_extensions/__init__.py

@@ -0,0 +1,3 @@
+from griffe_extensions.sync_stubs_inspector import InspectSpecificObjects
+
+__all__ = ["InspectSpecificObjects"]

python/griffe_extensions/sync_stubs_inspector.py

@@ -0,0 +1,21 @@
+import griffe
+
+logger = griffe.get_logger("griffe_inspect_specific_objects")
+
+
+class InspectSpecificObjects(griffe.Extension):
+    """Only inspect specific objects (such as ones with stubs)"""
+
+    def __init__(self, paths: list[str]) -> None:
+        self.objects = paths
+
+    def on_instance(self, *, obj: griffe.Object, **kwargs) -> None:
+        if obj.path not in self.objects:
+            return
+
+        # Skip over the stub files themselves
+        if str(obj.filepath).endswith(".pyi"):
+            return
+        # Load the stub file instead of importing the .py
+        inspected_module = griffe.inspect(obj.module.path, filepath=obj.filepath)
+        obj.parent.set_member(obj.name, inspected_module[obj.name])

python/lib/sift_client/__init__.py

@@ -1,7 +1,2 @@
 from sift_client.client import SiftClient
 from sift_client.transport import SiftConnectionConfig
-
-__all__ = [
-    "SiftClient",
-    "SiftConnectionConfig",
-]

python/lib/sift_client/_internal/sync_wrapper.py

@@ -6,6 +6,7 @@
 
 import asyncio
 import inspect
+import sys
 from functools import wraps
 from typing import Any, Type, TypeVar
 
@@ -61,6 +62,7 @@ def _run(self, coro):
         "__doc__": f"Sync counterpart to `{name}`.\n\n{cls.__doc__ or ''}",
         "__init__": __init__,
         "_run": _run,
+        "__qualname__": sync_name,  # Add __qualname__ to help static analyzers
     }
 
     # helper to wrap an async method and make into a sync method
@@ -134,7 +136,15 @@ def sync_prop(self, _prop_name=prop_name):
 
         namespace[name] = _wrap_sync(name)
 
+    # Create the sync class
     sync_class = type(sync_name, (object,), namespace)  # noqa
+
+    # Register the class in the module's globals
+    # This helps static analysis tools recognize it as a proper class
+    if module in sys.modules:
+        module_globals = sys.modules[module].__dict__
+        module_globals[sync_name] = sync_class
+
     _registered.append(SyncAPIRegistration(async_cls=cls, sync_cls=sync_class))
 
     return sync_class

python/lib/sift_client/resources/py.typed

@@ -0,0 +1 @@
+

python/lib/sift_client/resources/sync_stubs/__init__.py

@@ -3,7 +3,7 @@
 This package contains synchronous versions of all async API classes.
 """
 
-from sift_client._internal.sync_wrapper import generate_sync_api
+from sift_client._internal.sync_wrapper import generate_sync_api as generate_sync_api
 from sift_client.resources import AssetsAPIAsync, PingAPIAsync
 
 PingAPI = generate_sync_api(PingAPIAsync, "PingAPI")

python/lib/sift_client/resources/sync_stubs/__init__.pyi

@@ -9,6 +9,7 @@ from typing import Any
 from sift_client.client import SiftClient
 from sift_client.types.asset import Asset, AssetUpdate
 
+
 class AssetsAPI:
     """
     Sync counterpart to `AssetsAPIAsync`.
@@ -131,6 +132,7 @@ class AssetsAPI:
         """
         ...
 
+
 class PingAPI:
     """
     Sync counterpart to `PingAPIAsync`.

python/lib/sift_client/util/cel_utils.py

@@ -215,6 +215,7 @@ def greater_than(field: str, value: int | float | datetime) -> str:
     return f"{field} > {as_string}"
 
 
+
 def less_than(field: str, value: int | float | datetime) -> str:
     """
     Generates a CEL expression that checks whether a numeric or datetime field is less than a given value.

python/mkdocs.yml

@@ -0,0 +1,69 @@
+site_name: Sift Python Client Library
+repo_url: https://github.com/sift-stack/sift/tree/main/python
+copyright: "Copyright 2025 Sift Stack, Inc."
+theme:
+  name: material
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      primary: grey
+      accent: deep orange
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: black
+      accent: deep orange
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  logo: https://avatars.githubusercontent.com/u/105525178?s=200&v=4
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - toc.follow
+    - navigation.top
+    - search.suggest
+
+nav:
+  - Home: index.md
+
+plugins:
+  - search
+  - autorefs
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          options:
+            load_external_modules: true
+            show_source: false
+            find_stubs_package: true
+            show_if_no_docstring: true
+            filters: "public"
+            show_submodules: false
+            # Styling
+            group_by_category: true
+            docstring_section_style: spacy
+            docstring_style: "google"
+            heading_level: 1
+            merge_init_into_class: true
+            separate_signature: true
+            show_root_heading: true
+            show_signature_annotations: true
+            signature_crossrefs: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            summary: true
+            # Custom Griffe extension to only inspect sync_stubs
+            extensions:
+              - griffe_extensions/sync_stubs_inspector.py:InspectSpecificObjects:
+                  paths:
+                    - sift_client.resources.sync_stubs
+
+
+  - api-autonav:
+      modules: [ lib/sift_client ] #, lib/sift ]
+      exclude_private: true
+      nav_item_prefix: ""

python/pyproject.toml

@@ -58,6 +58,7 @@ build = ["pdoc==14.5.0", "build==1.2.1"]
 openssl = ["pyOpenSSL<24.0.0", "types-pyOpenSSL<24.0.0", "cffi~=1.14"]
 tdms = ["npTDMS~=1.9"]
 rosbags = ["rosbags~=0.0"]
+docs = ["mkdocs", "mkdocs-material", "mkdocstrings[python]", "mkdocs-include-markdown-plugin"]
 
 [build-system]
 requires = ["setuptools"]