atlan-application-sdk-api 3.51.0__tar.gz → 3.51.2__tar.gz

{atlan_application_sdk_api-3.51.0 → atlan_application_sdk_api-3.51.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: atlan-application-sdk-api
-Version: 3.51.0
+Version: 3.51.2
 Summary: Experimental: the handler surface of the Atlan Application SDK, for the consolidated API host
 Project-URL: Homepage, https://github.com/atlanhq/application-sdk
 Project-URL: Source, https://github.com/atlanhq/application-sdk/tree/main/packages/api
@@ -15,6 +15,7 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Requires-Python: >=3.11
+Requires-Dist: certifi>=2026.10.19
 Requires-Dist: fastapi<0.144.0,>=0.143.0
 Requires-Dist: httpx<0.29.0,>=0.27.0
 Requires-Dist: orjson<4.0.0,>=3.11.6
@@ -27,7 +28,8 @@ Requires-Dist: python-dotenv<2.0.0,>=1.1.0; extra == 'aws'
 Provides-Extra: pandas
 Requires-Dist: pandas<3.0.0,>=2.2.3; extra == 'pandas'
 Provides-Extra: pyatlan
-Requires-Dist: pyatlan<12,>=11.3; extra == 'pyatlan'
+Requires-Dist: authlib<2,>=1.9.1; extra == 'pyatlan'
+Requires-Dist: pyatlan<12,>=11.5.0; extra == 'pyatlan'
 Provides-Extra: sql
 Requires-Dist: httpx<0.29.0,>=0.27.0; extra == 'sql'
 Requires-Dist: python-dotenv<2.0.0,>=1.1.0; extra == 'sql'

{atlan_application_sdk_api-3.51.0 → atlan_application_sdk_api-3.51.2}/api-files.txt

@@ -56,6 +56,7 @@ application_sdk/errors/http.py
 application_sdk/errors/leaves.py
 application_sdk/errors/wire.py
 application_sdk/handler/__init__.py
+application_sdk/handler/_dispatch.py
 application_sdk/handler/_warmup.py
 application_sdk/handler/asgi.py
 application_sdk/handler/base.py

{atlan_application_sdk_api-3.51.0 → atlan_application_sdk_api-3.51.2}/application_sdk/common/_listing.py

@@ -29,6 +29,11 @@ import sys
 from collections.abc import Iterator
 from pathlib import Path
 
+try:
+    import fcntl
+except ImportError:  # Windows has no fcntl; only the darwin barrier below uses it
+    fcntl = None  # type: ignore[assignment]  # — sentinel for "no fcntl on this platform": None is not a module
+
 # Darwin-only fcntl op: flush kernel buffer + drive cache. Value from
 # <sys/fcntl.h>; not exported by Python's fcntl module.
 _DARWIN_F_FULLFSYNC = 51
@@ -114,9 +119,7 @@ def _flush_directory_metadata(path: Path) -> None:
     except OSError:
         return
     try:
-        if sys.platform == "darwin":
-            import fcntl  # noqa: PLC0415
-
+        if sys.platform == "darwin" and fcntl is not None:
             try:
                 fcntl.fcntl(fd, _DARWIN_F_FULLFSYNC)
                 return

{atlan_application_sdk_api-3.51.0 → atlan_application_sdk_api-3.51.2}/application_sdk/constants.py

@@ -117,13 +117,22 @@ from application_sdk._build_info import (  # noqa: E402 — public here as befor
 
 _BUILD_INFO = load_build_info()
 
+
+def _load_application_version(build_info: dict[str, str]) -> str:
+    return build_info.get("app_version", "") or os.getenv(
+        "ATLAN_APPLICATION_VERSION", ""
+    )
+
+
+def _load_commit_sha(build_info: dict[str, str]) -> str:
+    return build_info.get("commit_sha", "") or os.getenv("ATLAN_COMMIT_SHA", "")
+
+
 #: Version of the app release exactly as Global Marketplace stores it
 #: (release tag for semver apps, sha7 for CD apps). Baked value first.
-APPLICATION_VERSION = _BUILD_INFO.get("app_version", "") or os.getenv(
-    "ATLAN_APPLICATION_VERSION", ""
-)
+APPLICATION_VERSION = _load_application_version(_BUILD_INFO)
 #: Git commit the image was built from. Baked only — no deployer stamps it.
-COMMIT_SHA = _BUILD_INFO.get("commit_sha", "") or os.getenv("ATLAN_COMMIT_SHA", "")
+COMMIT_SHA = _load_commit_sha(_BUILD_INFO)
 #: Release UUID from Global Marketplace
 RELEASE_ID = os.getenv("ATLAN_RELEASE_ID", "")
 #: Release channel (all, beta, staging, specific)
@@ -351,6 +360,7 @@ STORAGE_PROGRESS_LOG_INTERVAL_SECONDS = float(
     os.getenv("ATLAN_STORAGE_PROGRESS_LOG_INTERVAL_SECONDS", "30")
 )
 
+
 #: Interval (seconds) between progress marks while an activity waits on a
 #: per-destination storage lock (materialise dedupe, chunked-transfer
 #: exclusion). Must stay under the stall watchdog's no-progress budget, or a
@@ -360,13 +370,17 @@ STORAGE_PROGRESS_LOG_INTERVAL_SECONDS = float(
 #: ``max_no_progress_seconds`` below that cap is the operator's explicit
 #: exception and is not defended here). Floored at 1s so a zero cannot turn
 #: the wait into a busy spin. (CONNECT-1126)
-STORAGE_LOCK_WAIT_PROGRESS_SECONDS = max(
-    1.0,
-    min(
-        float(os.getenv("ATLAN_STORAGE_LOCK_WAIT_PROGRESS_SECONDS", "30")),
-        float(os.getenv("ATLAN_MAX_NO_PROGRESS_SECONDS", "900")) / 4.0,
-    ),
-)
+def _load_storage_lock_wait_progress_seconds() -> float:
+    return max(
+        1.0,
+        min(
+            float(os.getenv("ATLAN_STORAGE_LOCK_WAIT_PROGRESS_SECONDS", "30")),
+            float(os.getenv("ATLAN_MAX_NO_PROGRESS_SECONDS", "900")) / 4.0,
+        ),
+    )
+
+
+STORAGE_LOCK_WAIT_PROGRESS_SECONDS = _load_storage_lock_wait_progress_seconds()
 
 #: Multipart part size for uploads (default 8 MiB). Raise this per deployment
 #: when the destination makes *part count* expensive rather than part size.
@@ -454,13 +468,16 @@ STORAGE_WRITE_SIDECARS = (
     os.getenv("ATLAN_STORAGE_WRITE_SIDECARS", "true").strip().lower() != "false"
 )
 
+
 #: Opt-in for the e2e ``sdk:store-assert`` node (FND-3571). The workflow is
 #: registered on every worker so worker start-up is identical everywhere; with
 #: this unset the node reads nothing and reports itself disabled. Only e2e
 #: installs set it, per tenant, through ``deploy.env_overrides``.
-STORE_ASSERT_ENABLED = (
-    os.getenv("ATLAN_STORE_ASSERT_ENABLED", "false").strip().lower() == "true"
-)
+def _load_store_assert_enabled() -> bool:
+    return os.getenv("ATLAN_STORE_ASSERT_ENABLED", "false").strip().lower() == "true"
+
+
+STORE_ASSERT_ENABLED = _load_store_assert_enabled()
 
 #: Build ID for worker versioning (injected by TWD controller via Kubernetes Downward API).
 #: When set, workers identify themselves with this build ID so the Temporal server can
@@ -660,9 +677,13 @@ OOM_RESTART_CHECK = _load_oom_restart_check()
 #: Whether to use server-side cursors for SQL operations.
 #: Enabled by default; set ATLAN_SQL_USE_SERVER_SIDE_CURSOR to any value other
 #: than "true" (e.g. "false") to opt out.
-USE_SERVER_SIDE_CURSOR = (
-    os.getenv("ATLAN_SQL_USE_SERVER_SIDE_CURSOR", "true").strip().lower() == "true"
-)
+def _load_use_server_side_cursor() -> bool:
+    return (
+        os.getenv("ATLAN_SQL_USE_SERVER_SIDE_CURSOR", "true").strip().lower() == "true"
+    )
+
+
+USE_SERVER_SIDE_CURSOR = _load_use_server_side_cursor()
 
 # DAPR Constants
 #: Name of the state store component in DAPR
@@ -839,12 +860,17 @@ LOG_LEVEL = (os.getenv("ATLAN_LOG_LEVEL") or os.getenv("LOG_LEVEL", "INFO")).upp
 #: Used by traces_adaptor.py and metrics_adaptor.py at module level for
 #: tracer/meter initialization. AppConfig.service_name is the runtime equivalent.
 SERVICE_NAME: str = os.getenv("OTEL_SERVICE_NAME", "atlan-application-sdk")
-#: Service version for OpenTelemetry
-SERVICE_VERSION: str = os.getenv("OTEL_SERVICE_VERSION", "")
-if not SERVICE_VERSION:
-    from application_sdk.version import __version__
 
-    SERVICE_VERSION = __version__
+
+from application_sdk.version import __version__  # noqa: E402
+
+
+def _load_service_version() -> str:
+    return os.getenv("OTEL_SERVICE_VERSION", "") or __version__
+
+
+#: Service version for OpenTelemetry
+SERVICE_VERSION: str = _load_service_version()
 #: Additional resource attributes for OpenTelemetry
 OTEL_RESOURCE_ATTRIBUTES: str = os.getenv("OTEL_RESOURCE_ATTRIBUTES", "")
 #: Endpoint for the OpenTelemetry collector

atlan_application_sdk_api-3.51.2/application_sdk/handler/_dispatch.py

@@ -0,0 +1,227 @@
+"""Resolve which callable answers a handler op for an entry point.
+
+One resolution for every surface that runs a handler op: the HTTP routes
+(``application_sdk.handler.routes``, shared by the worker's handler service and
+the consolidated API host) and the SDR Temporal activities
+(``application_sdk.execution._temporal.sdr``). Before this module the SDR
+activities called ``Handler.test_auth`` / ``Handler.fetch_metadata`` directly, so
+a per-entrypoint ``app.<segment>.handler`` hook ran over HTTP and was silently
+skipped over SDR.
+
+This module is part of the api slice's core: it must not import Temporal or any
+worker-only module, so it ships in ``atlan-application-sdk-api``.
+"""
+
+from __future__ import annotations
+
+import inspect
+import re
+from collections.abc import Awaitable, Callable
+from types import ModuleType
+from typing import Any, Literal, cast, overload
+
+from application_sdk._logging import get_logger
+from application_sdk.errors.leaves import InvalidInputError
+from application_sdk.handler.base import Handler
+from application_sdk.handler.context import HandlerContext
+from application_sdk.handler.contracts import (
+    AuthInput,
+    AuthOutput,
+    MetadataInput,
+    MetadataOutput,
+    PreflightInput,
+    PreflightOutput,
+    WarmupInput,
+    WarmupObservation,
+)
+
+# Named for application_sdk.handler.service: discovery moved from there (via
+# routes.py) and keeps its logger name, so its debug line is unchanged.
+logger = get_logger("application_sdk.handler.service")
+
+# ``\Z``, not ``$``: ``$`` also matches before a trailing newline, so
+# ``"export\n"`` would pass and then miss discovery instead of being refused.
+_ENTRYPOINT_NAME_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9_-]*\Z")
+
+HandlerFn = Callable[[Any, HandlerContext], Awaitable[Any]]
+
+HandlerOp = Literal["test_auth", "preflight_check", "fetch_metadata", "warmup"]
+
+
+def entrypoint_module_segment(name: str) -> str:
+    """Kebab-case entry-point name → its Python module segment (``a-b`` → ``a_b``).
+
+    Same conversion as ``application_sdk.app.entrypoint.entrypoint_module_segment``.
+    """
+    return name.replace("-", "_")
+
+
+def _import_optional_app_module(dotted: str) -> ModuleType | None:
+    """Import an optional consumer-owned module by dotted path.
+
+    Returns ``None`` only when the module *itself* (or one of its parent
+    packages) is absent — the expected "this app ships no such hook" case.
+    Re-raises when the module exists but fails to import: a transitive
+    ``ModuleNotFoundError`` (a missing dependency named somewhere other than the
+    target's own dotted path) or any other ``ImportError`` is a real bug in the
+    connector's code and must surface, not be silently swallowed into a
+    fall-through.
+    """
+    import importlib  # noqa: PLC0415 — cold path: per-entrypoint discovery only
+
+    try:
+        return importlib.import_module(dotted)
+    except ModuleNotFoundError as exc:  # conformance: ignore[E008] re-raises if missing dep is not the target module itself
+        missing = exc.name or ""
+        # Swallow only if what's missing is the target or one of its parents
+        # (e.g. ``app``, ``app.<segment>``, ``app.<segment>.core``).
+        if missing == dotted or dotted.startswith(f"{missing}."):
+            return None
+        raise
+
+
+def _discover_handler_fn(
+    entrypoint: str, app_package: str, fn_name: str
+) -> HandlerFn | None:
+    """Look for a per-entrypoint handler function.
+
+    Convention: ``app.<segment>.handler.<fn_name>`` where ``segment`` is
+    :func:`~application_sdk.app.entrypoint.entrypoint_module_segment` of the
+    entry-point name and ``fn_name`` is one of ``"test_auth"``,
+    ``"preflight_check"``, ``"fetch_metadata"``, ``"warmup"``. Multi-entrypoint apps that
+    need *per-entrypoint* lifecycle hooks drop a ``handler.py`` next to their
+    package's hand-written code with::
+
+        async def test_auth(input: AuthInput, ctx: HandlerContext) -> AuthOutput: ...
+        async def preflight_check(input: PreflightInput, ctx: HandlerContext) -> PreflightOutput: ...
+        async def fetch_metadata(input: MetadataInput, ctx: HandlerContext) -> MetadataOutput: ...
+        async def warmup(input: WarmupInput, ctx: HandlerContext) -> WarmupObservation: ...
+
+    The dispatch is best-effort: if the per-entrypoint module / attribute
+    is absent, the caller falls through to the app-level ``Handler`` instance
+    (``DefaultHandler`` if no custom handler is configured), preserving
+    today's single-entrypoint behavior 1:1.
+
+    Precedence & silent fall-through — important when reasoning about which
+    code actually runs (mirrored in ``docs/concepts/handlers.md``):
+
+    - When a per-entrypoint ``<fn_name>`` exists, it **pre-empts** the
+      app-level ``Handler.<fn_name>`` for that entry point. Defining both
+      silently runs the module one; the class method never executes.
+    - Resolution is per-op: a module that defines only ``fetch_metadata``
+      leaves ``test_auth`` / ``preflight_check`` falling back to the
+      app-level ``Handler`` — one entry point can be split across two files.
+    - A wrong name or a non-``async`` ``def`` does not match (see the
+      ``iscoroutinefunction`` check below) and **silently** falls through
+      rather than erroring — so a typo'd hook quietly does nothing.
+
+    Returns the callable or ``None`` if absent.
+    """
+
+    segment = entrypoint_module_segment(entrypoint)
+    module = _import_optional_app_module(f"{app_package}.{segment}.handler")
+    if module is None:
+        return None
+    fn = getattr(module, fn_name, None)
+    # The dispatch ``await``s the result, so require a coroutine function — a
+    # sync ``def`` falls through to the app-level Handler rather than blowing up
+    # with a TypeError at request time.
+    if fn is not None and not inspect.iscoroutinefunction(fn):
+        logger.debug(
+            "%s.%s.%s found but not async; falling through to app-level Handler",
+            app_package,
+            segment,
+            fn_name,
+        )
+    return cast("HandlerFn | None", fn if inspect.iscoroutinefunction(fn) else None)
+
+
+@overload
+def resolve_handler_op(
+    handler: Handler,
+    op: Literal["test_auth"],
+    entrypoint: str,
+    *,
+    app_package: str = ...,
+) -> Callable[[AuthInput, HandlerContext], Awaitable[AuthOutput]]: ...
+@overload
+def resolve_handler_op(
+    handler: Handler,
+    op: Literal["preflight_check"],
+    entrypoint: str,
+    *,
+    app_package: str = ...,
+) -> Callable[[PreflightInput, HandlerContext], Awaitable[PreflightOutput]]: ...
+@overload
+def resolve_handler_op(
+    handler: Handler,
+    op: Literal["fetch_metadata"],
+    entrypoint: str,
+    *,
+    app_package: str = ...,
+) -> Callable[[MetadataInput, HandlerContext], Awaitable[MetadataOutput]]: ...
+@overload
+def resolve_handler_op(
+    handler: Handler,
+    op: Literal["warmup"],
+    entrypoint: str,
+    *,
+    app_package: str = ...,
+) -> Callable[[WarmupInput, HandlerContext], Awaitable[WarmupObservation]]: ...
+def resolve_handler_op(
+    handler: Handler,
+    op: HandlerOp,
+    entrypoint: str,
+    *,
+    app_package: str = "app",
+) -> HandlerFn:
+    """Return the callable that answers ``op`` for ``entrypoint``.
+
+    A per-entrypoint ``<app_package>.<segment>.handler.<op>`` hook wins (see
+    :func:`_discover_handler_fn` for the precedence rules); otherwise the
+    app-level ``handler.<op>`` answers. Both come back with the hook signature
+    ``(input, ctx)`` so callers invoke them the same way; the ``Handler`` method
+    ignores ``ctx`` (it reads ``self.context``, bound by the caller).
+
+    An empty ``entrypoint`` (single-entrypoint apps, older orchestrators) goes
+    straight to ``handler``.
+
+    Raises:
+        InvalidInputError: ``entrypoint`` is non-empty and not a valid entry-point
+            name. The name becomes part of a module path, so a malformed one is
+            refused rather than imported. The HTTP routes reject it with a 400
+            before calling this.
+    """
+    if entrypoint:
+        if not _ENTRYPOINT_NAME_RE.match(entrypoint):
+            raise InvalidInputError(
+                message="Invalid entrypoint name",
+                field="entrypoint",
+                constraint=_ENTRYPOINT_NAME_RE.pattern,
+            )
+        fn = _discover_handler_fn(entrypoint, app_package, op)
+        if fn is not None:
+            return fn
+    method: Callable[[Any], Awaitable[Any]] = getattr(handler, op)
+
+    async def call_handler(input: Any, ctx: HandlerContext) -> Any:
+        return await method(input)
+
+    return call_handler
+
+
+def mirror_template_key(metadata_input: MetadataInput) -> MetadataInput:
+    """Copy the widget routing key onto ``object_filter`` when that is empty.
+
+    The widget routing key (``metadataTemplateKey`` / ``type`` on the wire) lands
+    in its documented home, ``metadata_template_key``, via the field's
+    validation alias. Per-entrypoint hooks that read the legacy ``object_filter``
+    (e.g. asset-export-advanced's tags vs connectors vs typenames widgets) keep
+    working because it is mirrored there. New hooks can read
+    ``metadata_template_key`` directly. Returns a copy; the input is not mutated.
+    """
+    if not metadata_input.object_filter and metadata_input.metadata_template_key:
+        return metadata_input.model_copy(
+            update={"object_filter": metadata_input.metadata_template_key}
+        )
+    return metadata_input