atlan-application-sdk-api 3.51.0__py3-none-any.whl

application_sdk/__init__.py

@@ -0,0 +1,7 @@
+"""
+Application SDK for developing applications on the Atlan Platform.
+"""
+
+from application_sdk.version import __version__
+
+__all__ = ["__version__"]

application_sdk/_build_info.py

@@ -0,0 +1,62 @@
+"""The build-identity file reader, with no dependencies beyond the stdlib.
+
+:mod:`application_sdk.constants` exposes it as ``load_build_info``, as before.
+It lives here so :mod:`application_sdk.common.build_identity` can read the file
+without importing ``constants``, whose module-level imports the consolidated
+API host's core install does not carry.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+__all__ = ["load_build_info"]
+
+
+def load_build_info(path: str | None = None) -> dict[str, str]:
+    """Read the build-identity file the reusable CI bakes into the image.
+
+    ``build-and-publish-app.yaml`` writes ``app/atlan_build.json`` into the
+    build context and the template Dockerfile's ``COPY app/ app/`` carries it
+    into the image. Keys: ``app_version`` (the exact string Global Marketplace
+    stores as ``versions.version``), ``commit_sha``, ``build_id`` (the immutable
+    image tag, the same value ``ATLAN_BUILD_ID`` carries on the e2e path),
+    ``image``, ``built_at``.
+
+    Missing or malformed file → ``{}``; callers fall back to the env vars.
+    ``ATLAN_BUILD_INFO_PATH`` overrides the lookup for non-template layouts.
+
+    Public because :mod:`application_sdk.app.build_identity` reads the same file
+    through it. A second parser there would be a second place for the key names
+    to drift from what CI writes.
+    """
+    if path:
+        candidates = [path]
+    else:
+        override = os.getenv("ATLAN_BUILD_INFO_PATH", "")
+        generated_dir = os.environ.get("ATLAN_CONTRACT_GENERATED_DIR", "app/generated")
+        candidates = (
+            [override]
+            if override
+            else [
+                "app/atlan_build.json",
+                os.path.join(
+                    os.path.dirname(generated_dir.rstrip("/")) or ".",
+                    "atlan_build.json",
+                ),
+            ]
+        )
+    for candidate in candidates:
+        try:
+            with open(candidate, encoding="utf-8") as fh:
+                data = json.load(fh)
+        except (OSError, ValueError):
+            continue
+        if isinstance(data, dict):
+            return {
+                str(k): str(v)
+                for k, v in data.items()
+                if isinstance(v, (str, int, float)) and not isinstance(v, bool)
+            }
+    return {}

application_sdk/_context_errors.py

@@ -0,0 +1,65 @@
+"""Context errors raised by code that ships in the api distribution.
+
+Defined here, not in ``application_sdk.app``, so the handler surface can raise
+them on an api-only install. ``application_sdk.app.base`` and
+``application_sdk.app.base_errors`` re-export them under their usual names.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from application_sdk.errors import APP_CONTEXT_ERROR, ErrorCode
+from application_sdk.errors.leaves import InternalError as _InternalError
+from application_sdk.errors.leaves import PreconditionError
+
+
+@dataclass(kw_only=True)
+class ObjectStoreNotConfiguredError(PreconditionError):
+    """Object store required by a @task but not configured in the deployment."""
+
+    code: ClassVar[str] = "PRECONDITION_OBJECT_STORE_NOT_CONFIGURED"
+    message: str = (
+        "No object store configured. "
+        "Ensure the deployment has a storage binding or APP_STORAGE_ROOT set."
+    )
+    resource: str | None = "object_store"
+    expected_state: str | None = "configured"
+
+
+@dataclass(kw_only=True)
+class SecretStoreNotConfiguredError(PreconditionError):
+    """Secret store required by get_secret / resolve_credential but not configured."""
+
+    code: ClassVar[str] = "PRECONDITION_SECRET_STORE_NOT_CONFIGURED"
+    message: str = "No secret store configured"
+    resource: str | None = "secret_store"
+    expected_state: str | None = "configured"
+
+
+class AppContextError(_InternalError):
+    """Raised when App or task context is accessed outside of valid execution scope.
+
+    This is a programming error — it indicates that context-dependent methods
+    (e.g. ``self.context``, ``self.heartbeat()``) were called outside of a
+    workflow run or @task execution.
+    """
+
+    DEFAULT_ERROR_CODE: ClassVar[ErrorCode] = APP_CONTEXT_ERROR
+    code: ClassVar[str] = "INTERNAL_APP_CONTEXT"
+
+    def __init__(self, message: str, *, error_code: ErrorCode | None = None) -> None:
+        _InternalError.__init__(self, message=message)
+        self._legacy_error_code = error_code
+
+    @property
+    def error_code(self) -> ErrorCode:
+        return (
+            self._legacy_error_code
+            if self._legacy_error_code is not None
+            else self.DEFAULT_ERROR_CODE
+        )
+
+    def __str__(self) -> str:
+        return f"[{self.error_code.code}] {self.message}"

application_sdk/_install.py

@@ -0,0 +1,130 @@
+"""Which distribution is installed: the full SDK, or only the api subset.
+
+``atlan-application-sdk-api`` ships a listed subset of ``application_sdk/`` (see
+``packages/api/api-files.txt``) for the consolidated API host. A few listed
+files reach worker-only code lazily (the object store, Temporal, the worker's
+infrastructure). Each such import is wrapped so that, on an api-only install,
+it takes a stated fallback instead of raising at call time — and so that, with
+the full SDK installed, a missing module is still a real error and still raises.
+:func:`api_only_install` is the one test that tells the two apart.
+"""
+
+from __future__ import annotations
+
+import functools
+import importlib
+import importlib.util
+from collections.abc import Collection, Mapping, MutableMapping
+from types import ModuleType
+from typing import Any
+
+#: A module the full SDK always ships and the api distribution never does.
+_WORKER_SENTINEL = "application_sdk.main"
+
+#: The modules the :func:`worker_only_missing` guards import, none of them shipped
+#: by the api distribution: the object store (``contracts.types``,
+#: ``credentials.utils``, ``common.utils``, ``observability.observability``), the
+#: worker's infrastructure (``handler.context``, ``observability.observability``),
+#: the SDK's structured logger (``_logging``) and Temporal
+#: (``observability.utils``). A guard falls back only when one of these (or a
+#: submodule of one) is what is missing; anything else is a real error. A new
+#: guard over another worker-only module adds that module here.
+_WORKER_ONLY_PREFIXES: tuple[str, ...] = (
+    "application_sdk.infrastructure",
+    "application_sdk.observability",
+    "application_sdk.storage",
+    "temporalio",
+)
+
+
+@functools.cache
+def api_only_install() -> bool:
+    """True when only ``atlan-application-sdk-api`` is installed (the API host)."""
+    return importlib.util.find_spec(_WORKER_SENTINEL) is None
+
+
+def worker_only_missing(exc: ModuleNotFoundError) -> bool:
+    """True when ``exc`` is an api-only install lacking a worker-only module.
+
+    Use it in ``except ModuleNotFoundError as exc: if not worker_only_missing(exc):
+    raise``. With the full SDK installed it is always False, so the error
+    propagates exactly as it did before the split. On an api-only install it is
+    True only when the missing module is one of :data:`_WORKER_ONLY_PREFIXES`;
+    a missing api file or third-party dependency still raises.
+    """
+    if not api_only_install():
+        return False
+    missing = exc.name or ""
+    return any(
+        missing == prefix or missing.startswith(prefix + ".")
+        for prefix in _WORKER_ONLY_PREFIXES
+    )
+
+
+def import_submodule(package: str, name: str) -> ModuleType | None:
+    """``package.name`` when it names an existing submodule, else ``None``.
+
+    A package whose ``__init__`` imports lazily (a ``__getattr__`` over a
+    ``_LAZY`` map) no longer has its submodules as attributes until something
+    imports them. :func:`lazy_getattr` calls this for the submodules the package
+    used to import eagerly, so ``import pkg; pkg.sub`` keeps working for them.
+    """
+    if not name.isidentifier() or name.startswith("__"):
+        return None
+    full = f"{package}.{name}"
+    try:
+        spec = importlib.util.find_spec(full)
+    except (ImportError, ValueError):
+        return None
+    return importlib.import_module(full) if spec is not None else None
+
+
+def _names_missing_module(exc: ModuleNotFoundError, module: str) -> bool:
+    """Whether ``exc`` is *module* itself (or a parent package) being absent."""
+    missing = exc.name or ""
+    return bool(missing) and (module == missing or module.startswith(f"{missing}."))
+
+
+def lazy_getattr(
+    module_name: str,
+    name: str,
+    lazy_map: Mapping[str, tuple[str, str]],
+    globals_: MutableMapping[str, Any],
+    submodules: Collection[str] = (),
+) -> Any:
+    """The PEP 562 ``__getattr__`` body of a package that imports lazily.
+
+    *lazy_map* maps a public name to ``(module, attribute)``; the first access
+    imports it and caches it in the package's *globals_*. *submodules* are the
+    submodules the package imported eagerly before it went lazy, so
+    ``import pkg; pkg.sub`` keeps working for those and only those: any other
+    submodule is an attribute only once something imports it, as with any
+    package (so ``hasattr(pkg, "sub")`` does not import it).
+    ``from pkg import sub`` needs no entry; the import system loads it.
+
+    A name whose module is not installed (on an api-only install the worker's
+    modules are absent) raises :class:`AttributeError` chained to the import
+    error, so ``hasattr`` and ``getattr(pkg, name, default)`` answer normally.
+    A module that is installed but fails to import raises its own error
+    unchanged: that is a real bug, and ``from pkg import name`` would otherwise
+    report only "cannot import name".
+    """
+    target = lazy_map.get(name)
+    if target is not None:
+        try:
+            module = importlib.import_module(target[0])
+        except ModuleNotFoundError as exc:
+            if not _names_missing_module(exc, target[0]):
+                raise
+            raise AttributeError(
+                f"module {module_name!r} has no attribute {name!r}: "
+                f"{target[0]} is not installed"
+            ) from exc
+        value = getattr(module, target[1])
+        globals_[name] = value
+        return value
+    if name in submodules:
+        submodule = import_submodule(module_name, name)
+        if submodule is not None:
+            return submodule
+    raise AttributeError(f"module {module_name!r} has no attribute {name!r}")

application_sdk/_logging.py

@@ -0,0 +1,171 @@
+"""Logger lookup for code that ships in the api distribution.
+
+The handler surface (errors, handler, contracts, credential specs) ships in
+``atlan-application-sdk-api``, which ``atlan-application-sdk`` depends on and
+which the consolidated API host installs without the worker SDK. Those files log
+through this helper. With the full SDK installed it returns the SDK's structured
+logger (``observability.logger_adaptor.get_logger``), exactly as before; with
+only the api distribution installed ``application_sdk.observability`` does not
+exist, and it falls back to the standard library.
+
+On that api-only path the stdlib ``application_sdk`` logger would otherwise have
+no handler, so its INFO lines (route lifecycle, preflight verdicts) would be
+dropped by the root logger's default WARNING level. The first fallback lookup
+therefore gives it one minimal handler — INFO and above, to stderr — and sets
+its level to INFO, but only when neither it nor the root logger has a handler
+yet (a host that configured logging first is left alone). If the root logger
+gains a handler later, the SDK's handler stands down and records propagate there
+instead, so no line is written twice; the ``application_sdk`` logger stays at
+INFO, so the SDK's INFO lines still reach those handlers unless the host sets
+that logger's level itself. The full SDK install never takes this path: worker
+logging is unchanged.
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+from collections.abc import Mapping
+from typing import Protocol
+
+from application_sdk._install import worker_only_missing
+
+_ExcInfo = bool | BaseException | None
+
+
+class SdkLogger(Protocol):
+    """The logging calls both loggers :func:`get_logger` returns accept.
+
+    Satisfied by the SDK's ``AtlanLoggerAdapter`` (full install) and by
+    :class:`logging.Logger` (api-only install), so code here may use only what
+    both take: ``%``-style arguments and the stdlib keywords.
+    """
+
+    def debug(
+        self,
+        msg: str,
+        /,
+        *args: object,
+        exc_info: _ExcInfo = ...,
+        stack_info: bool = ...,
+        stacklevel: int = ...,
+        extra: Mapping[str, object] | None = ...,
+    ) -> None: ...
+
+    def info(
+        self,
+        msg: str,
+        /,
+        *args: object,
+        exc_info: _ExcInfo = ...,
+        stack_info: bool = ...,
+        stacklevel: int = ...,
+        extra: Mapping[str, object] | None = ...,
+    ) -> None: ...
+
+    def warning(
+        self,
+        msg: str,
+        /,
+        *args: object,
+        exc_info: _ExcInfo = ...,
+        stack_info: bool = ...,
+        stacklevel: int = ...,
+        extra: Mapping[str, object] | None = ...,
+    ) -> None: ...
+
+    def error(
+        self,
+        msg: str,
+        /,
+        *args: object,
+        exc_info: _ExcInfo = ...,
+        stack_info: bool = ...,
+        stacklevel: int = ...,
+        extra: Mapping[str, object] | None = ...,
+    ) -> None: ...
+
+    def exception(
+        self,
+        msg: str,
+        /,
+        *args: object,
+        exc_info: _ExcInfo = ...,
+        stack_info: bool = ...,
+        stacklevel: int = ...,
+        extra: Mapping[str, object] | None = ...,
+    ) -> None: ...
+
+    def critical(
+        self,
+        msg: str,
+        /,
+        *args: object,
+        exc_info: _ExcInfo = ...,
+        stack_info: bool = ...,
+        stacklevel: int = ...,
+        extra: Mapping[str, object] | None = ...,
+    ) -> None: ...
+
+    def log(
+        self,
+        level: int,
+        msg: str,
+        /,
+        *args: object,
+        exc_info: _ExcInfo = ...,
+        stack_info: bool = ...,
+        stacklevel: int = ...,
+        extra: Mapping[str, object] | None = ...,
+    ) -> None: ...
+
+
+def get_logger(name: str | None = None) -> SdkLogger:
+    """The SDK logger for ``name``, or a stdlib logger on an api-only install.
+
+    Same signature as :func:`application_sdk.observability.logger_adaptor.get_logger`,
+    which the modules using this helper re-exported before.
+    """
+    try:
+        from application_sdk.observability.logger_adaptor import (  # noqa: PLC0415 — absent on an api-only install
+            get_logger as _sdk_get_logger,
+        )
+    except ModuleNotFoundError as exc:
+        if not worker_only_missing(exc):
+            raise
+        _configure_api_only_logging()
+        return logging.getLogger(name or __name__)
+    return _sdk_get_logger(name)
+
+
+#: The stdlib logger every api-only ``get_logger(__name__)`` in the SDK sits under.
+_SDK_LOGGER_NAME = "application_sdk"
+
+
+class _ApiOnlyHandler(logging.StreamHandler):
+    """stderr, unless the root logger has since been given a handler of its own."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if logging.getLogger().handlers:
+            return  # the record propagates to the host's own root handlers
+        super().emit(record)
+
+
+@functools.cache
+def _configure_api_only_logging() -> None:
+    """Give the ``application_sdk`` stdlib logger a minimal INFO handler, once.
+
+    Only on the api-only path, and only when neither that logger nor the root
+    logger has a handler: an existing logging setup is never touched.
+    """
+    sdk_logger = logging.getLogger(_SDK_LOGGER_NAME)
+    if sdk_logger.handlers or logging.getLogger().handlers:
+        return
+    handler = _ApiOnlyHandler()  # stderr
+    handler.setLevel(logging.INFO)
+    handler.setFormatter(
+        logging.Formatter("%(asctime)s %(levelname)s %(name)s - %(message)s")
+    )
+    sdk_logger.addHandler(handler)
+    if sdk_logger.level == logging.NOTSET:
+        sdk_logger.setLevel(logging.INFO)

application_sdk/_runtime/__init__.py

@@ -0,0 +1,29 @@
+"""Dependency-neutral runtime substrate — the SDK's bottom layer (ADR-0019).
+
+Everything in this package may be imported **at module scope from anywhere in
+the SDK**, including from ``storage/``. That is the package's entire purpose:
+the offload pool and the progress seam are needed by every layer, so they cannot
+live in a layer.
+
+**The rule for modules in here.** A ``_runtime`` module may import from the
+standard library, from third-party packages, from
+``application_sdk.observability.logger_adaptor``, and from its siblings in this
+package (``offload.py`` reads ``progress.py``, which is what makes the offload
+auto-holds work). Nothing else in ``application_sdk``: never
+``application_sdk.contracts``, ``application_sdk.credentials``,
+``application_sdk.storage``, ``application_sdk.execution`` or
+``application_sdk.app`` — each of those pulls in ``storage.ops`` transitively,
+which is exactly the cycle this package exists to remove.
+``tests/unit/runtime/test_layering.py`` enforces this in a subprocess, so
+breaking the rule fails CI rather than surfacing as an ``ImportError`` at some
+unrelated call site months later.
+
+The boundary is *upward*, not lateral — a sibling import stays inside the bottom
+layer and cannot reach a layer above it, so it cannot re-create the cycle.
+
+**Private on purpose.** The app-facing paths are unchanged and stay where the
+docs point them: ``application_sdk.execution.heartbeat`` for the offload
+primitives and ``application_sdk.execution.progress`` for the progress seam,
+both thin re-exports over this package. SDK-internal code imports from here
+directly; apps should not need to know this package exists.
+"""