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

application_sdk/handler/service_errors.py

@@ -0,0 +1,37 @@
+"""Typed error leaves for the handler service module."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from application_sdk.errors.leaves import InternalError, InvalidInputError
+
+
+@dataclass(kw_only=True)
+class TempPathEscapeError(InternalError):
+    """A path escaped the system temp directory — invariant violation."""
+
+    code: ClassVar[str] = "INTERNAL_HANDLER_TEMP_PATH_ESCAPE"
+    message: str = "Temp file path escapes system temp directory"
+    component: str | None = "handler"
+
+
+@dataclass(kw_only=True)
+class InvalidConfigIdError(InvalidInputError):
+    """config_id did not match the allowed character pattern."""
+
+    code: ClassVar[str] = "INVALID_INPUT_CONFIG_ID"
+    message: str = "Invalid config_id: must match allowed character pattern"
+    field: str | None = "config_id"
+    config_id: str | None = None
+
+
+@dataclass(kw_only=True)
+class InvalidConfigTypeError(InvalidInputError):
+    """config_type did not match the allowed character pattern."""
+
+    code: ClassVar[str] = "INVALID_INPUT_CONFIG_TYPE"
+    message: str = "Invalid config_type: must match allowed character pattern"
+    field: str | None = "config_type"
+    config_type: str | None = None

application_sdk/server/__init__.py

@@ -0,0 +1,15 @@
+"""HTTP server layer — FastAPI app, MCP integration, middleware.
+
+Import from the submodules (``application_sdk.server.middleware``,
+``application_sdk.server.mcp``); nothing is re-exported here, and nothing is
+imported at package scope so that reaching one submodule never pulls in the
+others' dependencies.
+
+This file is intentionally almost empty. It exists because a package without an
+``__init__.py`` is an implicit namespace package, which static tools — griffe,
+and therefore the capability manifest — do not descend into: the public surface
+of ``server.mcp`` and ``server.middleware`` was invisible to every static reader
+of this package while it was missing (FND-439). The previous ``__init__.py`` was
+deleted wholesale with the v2 shim layer (b5ed0e49) because it held the
+deprecated ``ServerInterface``; only the deprecated content was meant to go.
+"""

application_sdk/server/fastapi/models.py

@@ -0,0 +1,338 @@
+# Request/Response DTOs for workflows
+
+from enum import Enum
+from typing import Any, Callable, Coroutine, Dict, Optional, Union
+
+from pydantic import BaseModel, Field, RootModel
+
+from application_sdk.contracts.events import Event
+
+
+class TestAuthRequest(RootModel[Dict[str, Any]]):
+    root: Dict[str, Any] = Field(
+        ..., description="Root JSON object containing database credentials"
+    )
+
+
+class TestAuthResponse(BaseModel):
+    success: bool
+    message: str
+
+
+class MetadataType(str, Enum):
+    DATABASE = "database"
+    SCHEMA = "schema"
+    ALL = "all"
+
+
+class FetchMetadataRequest(RootModel[Dict[str, Any]]):
+    root: Dict[str, Any] = Field(
+        ..., description="Root JSON object containing the metadata and credentials"
+    )
+
+
+class FetchMetadataResponse(BaseModel):
+    success: bool
+    data: Any
+
+
+class PreflightCheckRequest(BaseModel):
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "credentials": {
+                    "authType": "basic",
+                    "host": "host",
+                    "port": 5432,
+                    "username": "username",
+                    "password": "password",
+                    "database": "databasename",
+                },
+                "metadata": {
+                    "include-filter": '{"^dbengine$":["^public$","^airflow$"]}',
+                    "exclude-filter": "{}",
+                    "temp-table-regex": "",
+                },
+            }
+        }
+    }
+
+    credentials: Dict[str, Any] = Field(
+        ..., description="Required JSON field containing database credentials"
+    )
+    metadata: Dict[str, Any] = Field(
+        ...,
+        description="Required JSON field containing form data for filtering and configuration",
+    )
+
+
+class PreflightCheckResponse(BaseModel):
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "success": True,
+                "data": {
+                    "successMessage": "Successfully checked",
+                    "failureMessage": "",
+                },
+            }
+        }
+    }
+
+    success: bool = Field(
+        ..., description="Indicates if the overall operation was successful"
+    )
+    data: Dict[str, Any] = Field(..., description="Response data")
+
+
+class WorkflowRequest(RootModel[Dict[str, Any]]):
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "miner_args": {},
+                "credentials": {
+                    "authType": "basic",
+                    "host": "",
+                    "port": 5432,
+                    "username": "username",
+                    "password": "password",
+                    "database": "databasename",
+                },
+                "connection": {"connection": "dev"},
+                "metadata": {
+                    "include-filter": '{"^dbengine$":["^public$","^airflow$"]}',
+                    "exclude-filter": "{}",
+                    "temp-table-regex": "",
+                },
+            }
+        }
+    }
+
+    root: Dict[str, Any] = Field(
+        ..., description="Root JSON object containing workflow configuration"
+    )
+
+
+class EventWorkflowRequest(BaseModel):
+    event: Event = Field(alias="data", description="Event object")
+    datacontenttype: str = Field(
+        alias="datacontenttype", description="Data content type"
+    )
+    id: str = Field(alias="id", description="Event ID")
+    source: str = Field(alias="source", description="Event source")
+    specversion: str = Field(alias="specversion", description="Event spec version")
+    time: str = Field(alias="time", description="Event time")
+    type: str = Field(alias="type", description="Event type")
+    topic: str = Field(alias="topic", description="Event topic")
+
+
+class WorkflowData(BaseModel):
+    workflow_id: str = Field(..., description="Unique identifier for the workflow")
+    run_id: str = Field(..., description="Unique identifier for the workflow run")
+
+
+class WorkflowResponse(BaseModel):
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "success": True,
+                "message": "Workflow started successfully",
+                "data": {
+                    "workflow_id": "4b805f36-48c5-4dd3-942f-650e06f75bbc",
+                    "run_id": "efe16ffe-24b2-4391-a7ec-7000c32c5893",
+                },
+            }
+        }
+    }
+
+    success: bool = Field(
+        ..., description="Indicates whether the operation was successful"
+    )
+    message: str = Field(
+        ..., description="Message describing the result of the operation"
+    )
+    data: WorkflowData = Field(..., description="Details about the workflow and run")
+
+
+class EventWorkflowResponse(WorkflowResponse):
+    class Status(str, Enum):
+        SUCCESS = "SUCCESS"
+        RETRY = "RETRY"
+        DROP = "DROP"
+
+    # This should be a string enum of the status of the workflow, based on the Dapr docs
+    # https://docs.dapr.io/reference/api/pubsub_api/#expected-http-response
+    status: Status = Field(..., description="Status of the workflow")
+
+
+class WorkflowConfigRequest(RootModel[Dict[str, Any]]):
+    root: Dict[str, Any] = Field(
+        ..., description="Root JSON object containing workflow configuration"
+    )
+
+
+class WorkflowConfigResponse(BaseModel):
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "success": True,
+                "message": "Workflow configuration fetched successfully",
+                "data": {
+                    "credential_guid": "credential_test-uuid",
+                    "connection": {"connection": "dev"},
+                    "metadata": {
+                        "include-filter": '{"^dbengine$":["^public$","^airflow$"]}',
+                        "exclude-filter": "{}",
+                        "temp-table-regex": "",
+                    },
+                },
+            }
+        }
+    }
+
+    success: bool = Field(
+        ..., description="Indicates whether the operation was successful"
+    )
+    message: str = Field(
+        ..., description="Message describing the result of the operation"
+    )
+    data: Dict[str, Any] = Field(..., description="Workflow configuration")
+
+
+class ConfigMapResponse(BaseModel):
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "success": True,
+                "message": "Configuration map fetched successfully",
+                "data": {
+                    "config_map_id": "pikachu-config-001",
+                    "name": "Pikachu Configuration",
+                    "settings": {
+                        "electric_type": True,
+                        "level": 25,
+                        "moves": ["Thunderbolt", "Quick Attack"],
+                    },
+                },
+            }
+        }
+    }
+
+    success: bool = Field(
+        ..., description="Indicates whether the operation was successful"
+    )
+    message: str = Field(
+        ..., description="Message describing the result of the operation"
+    )
+    data: Dict[str, Any] = Field(..., description="Configuration map object")
+
+
+class Subscription(BaseModel):
+    """Subscription configuration for Dapr messaging.
+
+    Attributes:
+        component_name: Name of the Dapr pubsub component
+        topic: Topic to subscribe to
+        route: Route path for the message handler endpoint
+        handler: Required callback function to handle incoming messages
+        bulk_config: Optional bulk subscribe configuration
+        dead_letter_topic: Optional dead letter topic for failed messages
+
+    Nested Classes:
+        BulkConfig: Configuration for bulk message processing
+        MessageStatus: Status codes for handler responses (SUCCESS, RETRY, DROP)
+    """
+
+    class BulkConfig(BaseModel):
+        """Bulk configuration for Dapr messaging.
+
+        Attributes:
+            enabled: Whether bulk subscribe is enabled
+            max_messages_count: Maximum number of messages to receive in a batch
+            max_await_duration_ms: Maximum time to wait for messages in milliseconds
+        """
+
+        enabled: bool = False
+        max_messages_count: int = Field(
+            default=100, serialization_alias="maxMessagesCount"
+        )
+        max_await_duration_ms: int = Field(
+            default=40, serialization_alias="maxAwaitDurationMs"
+        )
+
+    class MessageStatus(str, Enum):
+        """Status codes for Dapr pub/sub subscription message handler responses.
+
+        Used in subscription handler responses to indicate how Dapr should handle the message.
+        Based on Dapr docs: https://docs.dapr.io/reference/api/pubsub_api/#expected-http-response
+
+        Attributes:
+            SUCCESS: Message was processed successfully.
+            RETRY: Message processing failed, should be retried.
+            DROP: Message should be dropped (sent to dead letter topic if configured).
+        """
+
+        SUCCESS = "SUCCESS"
+        RETRY = "RETRY"
+        DROP = "DROP"
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    component_name: str
+    topic: str
+    route: str
+    handler: Union[
+        Callable[[Any], Any], Callable[[Any], Coroutine[Any, Any, Any]]
+    ]  # Required callback function (sync or async)
+    bulk_config: Optional[BulkConfig] = None
+    dead_letter_topic: Optional[str] = None
+
+
+class FileUploadResponse(BaseModel):
+    """Response model for file upload endpoint matching heracles format.
+
+    Field names use camelCase to stay consistent with the upstream
+    Atlan ``/files`` endpoint contract.
+    """
+
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "id": "977f156b-9c78-4bfc-bd74-f603f18c078a",
+                "version": "weathered-firefly-9025",
+                "isActive": True,
+                "createdAt": 1764265919324,
+                "updatedAt": 1764265919324,
+                "fileName": "28bb016e-329f-46e1-b817-3fd315bdd7f0.csv",
+                "rawName": "ddls_export.csv",
+                "key": "28bb016e-329f-46e1-b817-3fd315bdd7f0.csv",
+                "extension": ".csv",
+                "contentType": "text/csv",
+                "fileSize": 39144,
+                "isEncrypted": False,
+                "redirectUrl": "",
+                "isUploaded": True,
+                "uploadedAt": "2024-01-01T00:00:00Z",
+                "isArchived": False,
+            }
+        }
+    }
+
+    id: str = Field(..., description="UUID of the file")
+    version: str = Field(..., description="Human-readable version string")
+    isActive: bool = Field(..., description="Whether the file is active")
+    createdAt: int = Field(..., description="Unix timestamp in milliseconds")
+    updatedAt: int = Field(..., description="Unix timestamp in milliseconds")
+    fileName: str = Field(..., description="UUID + extension")
+    rawName: str = Field(..., description="Original filename")
+    key: str = Field(..., description="Object store key (uuid+extension)")
+    extension: str = Field(..., description="File extension (e.g., '.csv')")
+    contentType: str = Field(..., description="Content type of the file")
+    fileSize: int = Field(..., description="File size in bytes")
+    isEncrypted: bool = Field(..., description="Whether the file is encrypted")
+    redirectUrl: str = Field(..., description="Redirect URL (empty for now)")
+    isUploaded: bool = Field(..., description="Whether the file is uploaded")
+    uploadedAt: str = Field(
+        ..., description="ISO timestamp or '0001-01-01T00:00:00Z' default"
+    )
+    isArchived: bool = Field(..., description="Whether the file is archived")

application_sdk/templates/__init__.py

@@ -0,0 +1,52 @@
+"""Built-in App templates for common extraction patterns.
+
+Provides v3-style App subclasses intended to be subclassed by connectors for SQL
+metadata extraction and query extraction.
+
+**Preferred (v3.1+):**
+
+    from application_sdk.templates import SqlApp
+
+**Legacy (deprecated, use SqlApp instead):**
+
+    from application_sdk.templates import SqlMetadataExtractor, SqlQueryExtractor
+    from application_sdk.templates import IncrementalSqlMetadataExtractor
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from application_sdk.templates.base_metadata_extractor import BaseMetadataExtractor
+    from application_sdk.templates.incremental_sql_metadata_extractor import (
+        IncrementalSqlMetadataExtractor,
+    )
+    from application_sdk.templates.sql_app import SqlApp
+    from application_sdk.templates.sql_metadata_extractor import SqlMetadataExtractor
+    from application_sdk.templates.sql_query_extractor import SqlQueryExtractor
+
+__all__ = [
+    "SqlApp",
+    "BaseMetadataExtractor",
+    "IncrementalSqlMetadataExtractor",
+    "SqlMetadataExtractor",
+    "SqlQueryExtractor",
+]
+
+_module_map = {
+    "SqlApp": "application_sdk.templates.sql_app",
+    "BaseMetadataExtractor": "application_sdk.templates.base_metadata_extractor",
+    "IncrementalSqlMetadataExtractor": "application_sdk.templates.incremental_sql_metadata_extractor",
+    "SqlMetadataExtractor": "application_sdk.templates.sql_metadata_extractor",
+    "SqlQueryExtractor": "application_sdk.templates.sql_query_extractor",
+}
+
+
+def __getattr__(name: str) -> object:
+    if name in _module_map:
+        import importlib  # noqa: PLC0415 — defensive: keep inline
+
+        module = importlib.import_module(_module_map[name])
+        return getattr(module, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

application_sdk/templates/contracts/__init__.py

@@ -0,0 +1,111 @@
+"""Typed contracts for built-in App implementations."""
+
+from application_sdk.templates.contracts.base_metadata_extraction import (
+    UploadInput,
+    UploadOutput,
+)
+from application_sdk.templates.contracts.incremental_sql import (
+    ExecuteColumnBatchInput,
+    ExecuteColumnBatchOutput,
+    FetchColumnsIncrementalInput,
+    FetchIncrementalMarkerInput,
+    FetchIncrementalMarkerOutput,
+    FetchTablesIncrementalInput,
+    IncrementalExtractionInput,
+    IncrementalExtractionOutput,
+    IncrementalRunContext,
+    IncrementalTaskInput,
+    PrepareColumnQueriesInput,
+    PrepareColumnQueriesOutput,
+    ReadCurrentStateInput,
+    ReadCurrentStateOutput,
+    UpdateMarkerInput,
+    UpdateMarkerOutput,
+    WriteCurrentStateInput,
+    WriteCurrentStateOutput,
+)
+from application_sdk.templates.contracts.sql_metadata import (
+    ExtractionInput,
+    ExtractionOutput,
+    ExtractionTaskInput,
+    ExtractionTaskOutput,
+    FetchColumnsInput,
+    FetchColumnsOutput,
+    FetchDatabasesInput,
+    FetchDatabasesOutput,
+    FetchProceduresInput,
+    FetchProceduresOutput,
+    FetchSchemasInput,
+    FetchSchemasOutput,
+    FetchTablesInput,
+    FetchTablesOutput,
+    FetchViewsInput,
+    FetchViewsOutput,
+    FilterMap,
+    PrimeAuthOutput,
+    TransformInput,
+    TransformOutput,
+    TreeSelectionExtractionInput,
+)
+from application_sdk.templates.contracts.sql_query import (
+    QueryBatchInput,
+    QueryBatchOutput,
+    QueryExtractionInput,
+    QueryExtractionOutput,
+    QueryFetchInput,
+    QueryFetchOutput,
+)
+
+__all__ = [
+    # Base metadata extraction (deprecated upload_to_atlan task)
+    "UploadInput",
+    "UploadOutput",
+    # SQL metadata — base
+    "ExtractionInput",
+    "ExtractionOutput",
+    "ExtractionTaskInput",
+    "ExtractionTaskOutput",
+    "FetchColumnsInput",
+    "FetchColumnsOutput",
+    "FetchDatabasesInput",
+    "FetchDatabasesOutput",
+    "FetchProceduresInput",
+    "FetchProceduresOutput",
+    "FetchSchemasInput",
+    "FetchSchemasOutput",
+    "FetchTablesInput",
+    "FetchTablesOutput",
+    "FetchViewsInput",
+    "FetchViewsOutput",
+    "FilterMap",
+    "TreeSelectionExtractionInput",
+    "PrimeAuthOutput",
+    "TransformInput",
+    "TransformOutput",
+    # Incremental SQL
+    "ExecuteColumnBatchInput",
+    "ExecuteColumnBatchOutput",
+    "FetchColumnsIncrementalInput",
+    "FetchIncrementalMarkerInput",
+    "FetchIncrementalMarkerOutput",
+    "FetchTablesIncrementalInput",
+    "IncrementalExtractionInput",
+    "IncrementalExtractionOutput",
+    "IncrementalRunContext",
+    "IncrementalTaskInput",
+    "PrepareColumnQueriesInput",
+    "PrepareColumnQueriesOutput",
+    "ReadCurrentStateInput",
+    "ReadCurrentStateOutput",
+    "UpdateMarkerInput",
+    "UpdateMarkerOutput",
+    "WriteCurrentStateInput",
+    "WriteCurrentStateOutput",
+    # SQL query
+    "QueryBatchInput",
+    "QueryBatchOutput",
+    "QueryExtractionInput",
+    "QueryExtractionOutput",
+    "QueryFetchInput",
+    "QueryFetchOutput",
+]

application_sdk/templates/contracts/base_metadata_extraction.py

@@ -0,0 +1,32 @@
+"""Typed contracts for the deprecated upload_to_atlan task.
+
+These contracts cover ``BaseMetadataExtractor.upload_to_atlan``, which is
+now a thin ``@deprecated`` wrapper around :meth:`App.upload`.  New code
+should import :class:`UploadInput` / :class:`UploadOutput` directly from
+``application_sdk.contracts.storage`` instead.
+"""
+
+from __future__ import annotations
+
+from application_sdk.contracts.base import Input, Output
+
+
+class UploadInput(Input):
+    """Input for the deprecated ``upload_to_atlan`` task.
+
+    Carries a single ``output_path`` that the wrapper forwards as
+    ``local_path`` on the storage ``UploadInput``.
+    """
+
+    output_path: str = ""
+    """Local path (file or directory) to push to the platform via App.upload."""
+
+
+class UploadOutput(Output):
+    """Output from the deprecated ``upload_to_atlan`` task."""
+
+    migrated_files: int = 0
+    """Number of files successfully uploaded."""
+
+    total_files: int = 0
+    """Total number of files attempted (matches ``migrated_files`` on success)."""