sectra-image-analysis-api 1.6.0__tar.gz → 1.6.2__tar.gz

{sectra_image_analysis_api-1.6.0 → sectra_image_analysis_api-1.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sectra-image-analysis-api
-Version: 1.6.0
+Version: 1.6.2
 Summary: A wrapper for the Sectra Image Analysis API.
 Project-URL: Homepage, https://github.com/amspath/sectra-image-analysis-api
 Project-URL: Repository, https://github.com/amspath/sectra-image-analysis-api

{sectra_image_analysis_api-1.6.0 → sectra_image_analysis_api-1.6.2}/docs/api/schemas.md

@@ -76,21 +76,34 @@ Another discriminated union on `type`:
 
 ### Image notifications
 
-`NewImageFilesInvocation` (`action: "newImageFiles"`) is sent when new image files are imported for a slide, so your app can decide whether the slide is worth analysing. Unlike the other four actions it carries the slide's full `imageInfo` (PHI-free) up front, so the decision needs no API calls.
+`NewImageFilesInvocation` (`action: "newImageFiles"`) is sent when new image files are imported for a slide, so your app can decide whether the slide is worth analysing. Unlike the other four actions it carries the slide's full `imageInfo` (PHI-free) up front.
 
-Sectra delivers it to whatever URL you registered, so it normally arrives on the same webhook as everything else.
+It does not arrive on the URL you registered, as Sectra appends `/imagenotification` to it:
+
+| Action | Delivered to |
+|---|---|
+| `create` / `modify` / `cancel` / `delete` | the registered URL, e.g. `/sectra/hook` |
+| `newImageFiles` | `<registered URL>/imagenotification` |
+
+So an app needs a second route.
 
 ```python
 @app.post("/sectra/hook")
 def hook(invocation: Invocation):
-    if isinstance(invocation, NewImageFilesInvocation):
-        if invocation.imageInfo.micronsPerPixel > 0.5:
-            return {}          # too low-res for us — ignore
-        ...                    # otherwise queue the analysis
+    ...                        # create / modify / cancel / delete
+
+
+@app.post("/sectra/hook/imagenotification")
+def image_notification(invocation: NewImageFilesInvocation):
+    if invocation.imageInfo.micronsPerPixel > 0.5:
+        return {}              # too low-res for us — ignore
+    ...                        # otherwise queue the analysis
 ```
 
 To simulate one in local development, use [`MockSectraServer.notify()`](mock-server.md): it builds the payload from the mock's own slide metadata, so the notification always agrees with what the mock later serves.
 
+Pass the registered URL — `notify()` appends `/imagenotification` itself, just like Sectra.
+
 ```python
 mock.notify(webhook_url="http://localhost:8000/sectra/hook", slide_id="slide-001")
 ```

{sectra_image_analysis_api-1.6.0 → sectra_image_analysis_api-1.6.2}/docs/quickstart.md

@@ -71,6 +71,7 @@ from sectra_client import SectraClient
 from sectra_client.schemas import Result, ResultData, Invocation, PrimitiveResultContent, CreateInvocation
 
 app = FastAPI()
+
 @app.post("/sectra/hook")
 def hook(invocation: Invocation, background_tasks: BackgroundTasks):
     background_tasks.add_task(run_analysis, invocation)

{sectra_image_analysis_api-1.6.0 → sectra_image_analysis_api-1.6.2}/examples/image_notification.py

@@ -4,6 +4,10 @@ Sectra sends a ``newImageFiles`` notification when new image files are imported.
 carries the slide's full (PHI-free) ``imageInfo``, so the triage decision needs no API
 calls; and ignoring the notification is a valid response.
 
+Image notifications do NOT arrive on the URL you registered. Sectra appends
+``/imagenotification`` to it, so an app registered at ``/sectra/hook`` needs a second
+route at ``/sectra/hook/imagenotification``.
+
 Run it directly; it starts a mock Sectra server and an analysis app and fires two
 notifications, one that gets accepted and one that gets skipped.
 
@@ -33,15 +37,14 @@ def _is_interesting(info: ImageMetadata) -> bool:
 
 @analysis_app.post("/sectra/hook")
 def sectra_hook(invocation: Invocation):
-    """Receive an invocation from Sectra.
+    """The registered URL: create / modify / cancel / delete land here."""
+    # See local_dev.py for a full create -> download -> store round-trip.
+    return {}
 
-    Notifications share this endpoint with create/modify/cancel/delete, so handle them
-    explicitly; an unhandled branch here means notifications are silently dropped.
-    """
-    if not isinstance(invocation, NewImageFilesInvocation):
-        # See local_dev.py for a full create -> download -> store round-trip.
-        return {}
 
+@analysis_app.post("/sectra/hook/imagenotification")
+def sectra_image_notification(invocation: NewImageFilesInvocation):
+    """The registered URL + /imagenotification: newImageFiles lands here."""
     info = invocation.imageInfo
     print(
         f"[analysis app] {invocation.slideId}: "
@@ -90,6 +93,7 @@ if __name__ == "__main__":
     app_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
     app_sock.bind(("localhost", 0))
     APP_PORT = app_sock.getsockname()[1]
+    # The registered URL. notify() appends /imagenotification, as Sectra does.
     WEBHOOK = f"http://localhost:{APP_PORT}/sectra/hook"
 
     # Two slides: one we want, one we don't.

{sectra_image_analysis_api-1.6.0 → sectra_image_analysis_api-1.6.2}/src/sectra_client/client.py

@@ -1,6 +1,7 @@
 import logging
 import pathlib
 import re
+import time
 from typing import List, Optional, cast
 from urllib.parse import urlsplit, urlunsplit
 
@@ -22,6 +23,11 @@ from sectra_client.utils.helpers import JSONPayload, connection_retry
 
 logger = logging.getLogger(__name__)
 
+# Server versions change only when Sectra is upgraded, so one lookup per server per hour
+# is plenty. Without this every client construction costs a /info round trip.
+_INFO_TTL_SECONDS = 3600
+_info_cache: dict[str, tuple[float, ApplicationInfo]] = {}
+
 class SectraClient:
     __slots__ = ("_url", "_token", "version_info", "_headers", "_session")
 
@@ -96,9 +102,19 @@ class SectraClient:
         return None
 
     def _retrieve_version_info(self) -> ApplicationInfo:
-        """Retrieves the versions of DPAT from the server."""
+        """Retrieves the versions of DPAT from the server.
+
+        Cached per base url for `_INFO_TTL_SECONDS`, so constructing many clients against
+        the same server costs one /info call per hour rather than one per client.
+        """
+
+        cached = _info_cache.get(self._url)
+        if cached is not None and time.monotonic() - cached[0] < _INFO_TTL_SECONDS:
+            versions = cached[1]
+        else:
+            versions = ApplicationInfo(**cast(dict, self._get("/info")))
+            _info_cache[self._url] = (time.monotonic(), versions)
 
-        versions = ApplicationInfo(**cast(dict, self._get("/info")))
         self._headers.update(
             {"X-Sectra-ApiVersion": versions.apiVersion, "X-Sectra-SoftwareVersion": versions.softwareVersion}
         )

{sectra_image_analysis_api-1.6.0 → sectra_image_analysis_api-1.6.2}/src/sectra_client/mock_server.py

@@ -234,6 +234,9 @@ class MockSectraServer:
     ) -> dict:
         """Fire a ``newImageFiles`` image notification at *webhook_url*.
 
+        Sectra does not deliver image notifications to the registered URL itself; it
+        appends ``/imagenotification`` to it. So does this method.
+
         ``imageInfo`` is taken from this server's own slide metadata (registered via
         :meth:`add_slide`, or fabricated on demand), so the notification always agrees
         with what ``GET /slides/{slide_id}/info`` will subsequently return.
@@ -241,8 +244,8 @@ class MockSectraServer:
         Parameters
         ----------
         webhook_url:
-            Full URL of the analysis app's endpoint, e.g.
-            ``"http://localhost:8000/sectra/hook"``.
+            The app's *registered* URL, e.g. ``"http://localhost:8000/sectra/hook"``.
+            The notification is POSTed to ``<webhook_url>/imagenotification``.
         slide_id:
             Slide that new image files were imported for.
         application_id:
@@ -260,7 +263,8 @@ class MockSectraServer:
             cancellationToken=str(uuid.uuid4()),
             imageInfo=self._get_or_create_slide(slide_id),
         )
-        resp = _requests.post(webhook_url, json=invocation.model_dump(), timeout=30)
+        url = f"{webhook_url.rstrip('/')}/imagenotification"
+        resp = _requests.post(url, json=invocation.model_dump(), timeout=30)
         resp.raise_for_status()
         return resp.json()