etlplus 0.15.0__py3-none-any.whl → 0.16.6__py3-none-any.whl

etlplus/connector/connector.py

@@ -0,0 +1,26 @@
+"""
+:mod:`etlplus.connector.connector` module.
+
+Compatibility re-exports for connector configuration classes.
+"""
+
+from __future__ import annotations
+
+from .api import ConnectorApi
+from .database import ConnectorDb
+from .file import ConnectorFile
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    # Type aliases
+    'Connector',
+]
+
+
+# SECTION: TYPED ALIASES ==================================================== #
+
+
+# Type alias representing any supported connector
+type Connector = ConnectorApi | ConnectorDb | ConnectorFile

etlplus/connector/core.py

@@ -0,0 +1,132 @@
+"""
+:mod:`etlplus.connector.core` module.
+
+Protocols and base classes for connector implementations.
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from abc import abstractmethod
+from dataclasses import dataclass
+from typing import Protocol
+from typing import Self
+from typing import runtime_checkable
+
+from ..types import StrAnyMap
+from .types import ConnectorType
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'ConnectorBase',
+    'ConnectorProtocol',
+]
+
+
+# SECTION: PROTOCOLS ======================================================== #
+
+
+@runtime_checkable
+class ConnectorProtocol(Protocol):
+    """
+    Structural contract for connector implementations.
+
+    Attributes
+    ----------
+    name : str
+        Unique connector name.
+    type : ConnectorType
+        Connector kind.
+    """
+
+    # -- Attributes -- #
+
+    name: str
+    type: ConnectorType
+
+    # -- Class Methods -- #
+
+    @classmethod
+    def from_obj(cls, obj: StrAnyMap) -> Self:
+        """
+        Parse a mapping into a connector instance.
+
+        Parameters
+        ----------
+        obj : StrAnyMap
+            Mapping with at least ``name``.
+
+        Returns
+        -------
+        Self
+            Parsed connector instance.
+        """
+        ...
+
+    # -- Internal Static Methods -- #
+
+    @staticmethod
+    def _require_name(obj: StrAnyMap, *, kind: str) -> str:
+        """
+        Extract and validate the ``name`` field from connector mappings.
+
+        Parameters
+        ----------
+        obj : StrAnyMap
+            Connector mapping with a ``name`` entry.
+        kind : str
+            Connector kind used in the error message.
+
+        Returns
+        -------
+        str
+            Valid connector name.
+
+        Raises
+        ------
+        TypeError
+            If ``name`` is missing or not a string.
+        """
+        name = obj.get('name')
+        if not isinstance(name, str):
+            raise TypeError(f'Connector{kind} requires a "name" (str)')
+        return name
+
+
+# SECTION: ABSTRACT BASE DATA CLASSES ======================================= #
+
+
+@dataclass(kw_only=True, slots=True)
+class ConnectorBase(ABC, ConnectorProtocol):
+    """
+    Abstract base class for connector implementations.
+
+    Attributes
+    ----------
+    name : str
+        Unique connector name.
+    type : ConnectorType
+        Connector kind.
+    """
+
+    name: str
+    type: ConnectorType
+
+    @classmethod
+    @abstractmethod
+    def from_obj(cls, obj: StrAnyMap) -> Self:
+        """
+        Parse a mapping into a connector instance.
+
+        Parameters
+        ----------
+        obj : StrAnyMap
+            Mapping with at least ``name``.
+
+        Returns
+        -------
+        Self
+            Parsed connector instance.
+        """

etlplus/connector/database.py

@@ -0,0 +1,122 @@
+"""
+:mod:`etlplus.connector.database` module.
+
+Database connector configuration dataclass.
+
+Notes
+-----
+- TypedDicts in this module are intentionally ``total=False`` and are not
+    enforced at runtime.
+- :meth:`*.from_obj` constructors accept :class:`Mapping[str, Any]` and perform
+    tolerant parsing and light casting. This keeps the runtime permissive while
+    improving autocomplete and static analysis for contributors.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Self
+from typing import TypedDict
+from typing import overload
+
+from ..types import StrAnyMap
+from .core import ConnectorBase
+from .enums import DataConnectorType
+from .types import ConnectorType
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'ConnectorDb',
+    'ConnectorDbConfigDict',
+]
+
+
+# SECTION: TYPED DICTS ====================================================== #
+
+
+class ConnectorDbConfigDict(TypedDict, total=False):
+    """
+    Shape accepted by :meth:`ConnectorDb.from_obj` (all keys optional).
+
+    See Also
+    --------
+    - :meth:`etlplus.connector.database.ConnectorDb.from_obj`
+    """
+
+    name: str
+    type: ConnectorType
+    connection_string: str
+    query: str
+    table: str
+    mode: str
+
+
+# SECTION: DATA CLASSES ===================================================== #
+
+
+@dataclass(kw_only=True, slots=True)
+class ConnectorDb(ConnectorBase):
+    """
+    Configuration for a database-based data connector.
+
+    Attributes
+    ----------
+    type : ConnectorType
+        Connector kind, always ``'database'``.
+    connection_string : str | None
+        Connection string/DSN for the database.
+    query : str | None
+        Query to execute for extraction (optional).
+    table : str | None
+        Target/source table name (optional).
+    mode : str | None
+        Load mode hint (e.g., ``'append'``, ``'replace'``) - future use.
+    """
+
+    # -- Attributes -- #
+
+    type: ConnectorType = DataConnectorType.DATABASE
+    connection_string: str | None = None
+    query: str | None = None
+    table: str | None = None
+    mode: str | None = None  # append|replace|upsert (future)
+
+    # -- Class Methods -- #
+
+    @classmethod
+    @overload
+    def from_obj(cls, obj: ConnectorDbConfigDict) -> Self: ...
+
+    @classmethod
+    @overload
+    def from_obj(cls, obj: StrAnyMap) -> Self: ...
+
+    @classmethod
+    def from_obj(
+        cls,
+        obj: StrAnyMap,
+    ) -> Self:
+        """
+        Parse a mapping into a ``ConnectorDb`` instance.
+
+        Parameters
+        ----------
+        obj : StrAnyMap
+            Mapping with at least ``name``.
+
+        Returns
+        -------
+        Self
+            Parsed connector instance.
+        """
+        name = cls._require_name(obj, kind='Db')
+
+        return cls(
+            name=name,
+            connection_string=obj.get('connection_string'),
+            query=obj.get('query'),
+            table=obj.get('table'),
+            mode=obj.get('mode'),
+        )

etlplus/connector/enums.py

@@ -0,0 +1,52 @@
+"""
+:mod:`etlplus.connector.enums` module.
+
+Connector enums and helpers.
+"""
+
+from __future__ import annotations
+
+from ..enums import CoercibleStrEnum
+from ..types import StrStrMap
+
+# SECTION: EXPORTS ========================================================= #
+
+
+__all__ = [
+    # Enums
+    'DataConnectorType',
+]
+
+
+# SECTION: ENUMS ============================================================ #
+
+
+class DataConnectorType(CoercibleStrEnum):
+    """Supported data connector types."""
+
+    # -- Constants -- #
+
+    API = 'api'
+    DATABASE = 'database'
+    FILE = 'file'
+
+    # -- Class Methods -- #
+
+    @classmethod
+    def aliases(cls) -> StrStrMap:
+        """
+        Return a mapping of common aliases for each enum member.
+
+        Returns
+        -------
+        StrStrMap
+            A mapping of alias names to their corresponding enum member names.
+        """
+        return {
+            'http': 'api',
+            'https': 'api',
+            'rest': 'api',
+            'db': 'database',
+            'filesystem': 'file',
+            'fs': 'file',
+        }

etlplus/connector/file.py

@@ -0,0 +1,120 @@
+"""
+:mod:`etlplus.connector.file` module.
+
+File connector configuration dataclass.
+
+Notes
+-----
+- TypedDicts in this module are intentionally ``total=False`` and are not
+    enforced at runtime.
+- :meth:`*.from_obj` constructors accept :class:`Mapping[str, Any]` and perform
+    tolerant parsing and light casting. This keeps the runtime permissive while
+    improving autocomplete and static analysis for contributors.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field
+from typing import Any
+from typing import Self
+from typing import TypedDict
+from typing import overload
+
+from ..types import StrAnyMap
+from ..utils import coerce_dict
+from .core import ConnectorBase
+from .enums import DataConnectorType
+from .types import ConnectorType
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'ConnectorFile',
+    'ConnectorFileConfigDict',
+]
+
+
+# SECTION: TYPED DICTS ====================================================== #
+
+
+class ConnectorFileConfigDict(TypedDict, total=False):
+    """
+    Shape accepted by :meth:`ConnectorFile.from_obj` (all keys optional).
+
+    See Also
+    --------
+    - :meth:`etlplus.connector.file.ConnectorFile.from_obj`
+    """
+
+    name: str
+    type: ConnectorType
+    format: str
+    path: str
+    options: StrAnyMap
+
+
+# SECTION: DATA CLASSES ===================================================== #
+
+
+@dataclass(kw_only=True, slots=True)
+class ConnectorFile(ConnectorBase):
+    """
+    Configuration for a file-based data connector.
+
+    Attributes
+    ----------
+    type : ConnectorType
+        Connector kind, always ``'file'``.
+    format : str | None
+        File format (e.g., ``'json'``, ``'csv'``).
+    path : str | None
+        File path or URI.
+    options : dict[str, Any]
+        Reader/writer format options.
+    """
+
+    # -- Attributes -- #
+
+    type: ConnectorType = DataConnectorType.FILE
+    format: str | None = None
+    path: str | None = None
+    options: dict[str, Any] = field(default_factory=dict)
+
+    # -- Class Methods -- #
+
+    @classmethod
+    @overload
+    def from_obj(cls, obj: ConnectorFileConfigDict) -> Self: ...
+
+    @classmethod
+    @overload
+    def from_obj(cls, obj: StrAnyMap) -> Self: ...
+
+    @classmethod
+    def from_obj(
+        cls,
+        obj: StrAnyMap,
+    ) -> Self:
+        """
+        Parse a mapping into a ``ConnectorFile`` instance.
+
+        Parameters
+        ----------
+        obj : StrAnyMap
+            Mapping with at least ``name``.
+
+        Returns
+        -------
+        Self
+            Parsed connector instance.
+        """
+        name = cls._require_name(obj, kind='File')
+
+        return cls(
+            name=name,
+            format=obj.get('format'),
+            path=obj.get('path'),
+            options=coerce_dict(obj.get('options')),
+        )

etlplus/connector/types.py

@@ -0,0 +1,40 @@
+"""
+:mod:`etlplus.connector.types` module.
+
+Connector type aliases for :mod:`etlplus.connector`.
+
+Examples
+--------
+>>> from etlplus.connector import Connector
+>>> src: Connector = {
+>>>     "type": "file",
+>>>     "path": "/data/input.csv",
+>>> }
+>>> tgt: Connector = {
+>>>     "type": "database",
+>>>     "connection_string": "postgresql://user:pass@localhost/db",
+>>> }
+>>> from etlplus.api import RetryPolicyDict
+>>> rp: RetryPolicyDict = {"max_attempts": 3, "backoff": 0.5}
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from .enums import DataConnectorType
+
+# SECTION: EXPORTS  ========================================================= #
+
+
+__all__ = [
+    # Type Aliases
+    'ConnectorType',
+]
+
+
+# SECTION: TYPE ALIASES ===================================================== #
+
+
+# Literal type for supported connector kinds (strings or enum members)
+type ConnectorType = DataConnectorType | Literal['api', 'database', 'file']

etlplus/connector/utils.py

@@ -0,0 +1,122 @@
+"""
+:mod:`etlplus.connector.utils` module.
+
+Shared connector parsing helpers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from .api import ConnectorApi
+from .connector import Connector
+from .database import ConnectorDb
+from .enums import DataConnectorType
+from .file import ConnectorFile
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    # Functions
+    'parse_connector',
+]
+
+
+# SECTION: INTERNAL FUNCTIONS =============================================== #
+
+
+def _coerce_connector_type(
+    obj: Mapping[str, Any],
+) -> DataConnectorType:
+    """
+    Normalize and validate the connector ``type`` field.
+
+    Parameters
+    ----------
+    obj : Mapping[str, Any]
+        Mapping with a ``type`` entry.
+
+    Returns
+    -------
+    DataConnectorType
+        Normalized connector type enum.
+
+    Raises
+    ------
+    TypeError
+        If ``type`` is missing or unsupported.
+    """
+    if 'type' not in obj:
+        raise TypeError('Connector requires a "type"')
+    try:
+        return DataConnectorType.coerce(obj.get('type'))
+    except ValueError as exc:
+        allowed = ', '.join(DataConnectorType.choices())
+        raise TypeError(
+            f'Unsupported connector type: {obj.get("type")!r}. '
+            f'Expected one of {allowed}.',
+        ) from exc
+
+
+def _load_connector(
+    kind: DataConnectorType,
+) -> type[Connector]:
+    """
+    Resolve the connector class for the requested kind.
+
+    Parameters
+    ----------
+    kind : DataConnectorType
+        Connector kind enum.
+
+    Returns
+    -------
+    type[Connector]
+        Connector class corresponding to *kind*.
+    """
+    match kind:
+        case DataConnectorType.API:
+            return ConnectorApi
+        case DataConnectorType.DATABASE:
+            return ConnectorDb
+        case DataConnectorType.FILE:
+            return ConnectorFile
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def parse_connector(
+    obj: Mapping[str, Any],
+) -> Connector:
+    """
+    Dispatch to a concrete connector constructor based on ``type``.
+
+    Parameters
+    ----------
+    obj : Mapping[str, Any]
+        Mapping with at least ``name`` and ``type``.
+
+    Returns
+    -------
+    Connector
+        Concrete connector instance.
+
+    Raises
+    ------
+    TypeError
+        If the mapping is invalid or the connector type is unsupported.
+
+    Notes
+    -----
+    Delegates to the tolerant ``from_obj`` constructors for each connector
+    kind. Connector types are normalized via
+    :class:`etlplus.connector.enums.DataConnectorType`, so common aliases
+    (e.g., ``'db'`` or ``'http'``) are accepted.
+    """
+    if not isinstance(obj, Mapping):
+        raise TypeError('Connector configuration must be a mapping.')
+    connector_cls = _load_connector(_coerce_connector_type(obj))
+    return connector_cls.from_obj(obj)

etlplus/database/ddl.py

@@ -233,7 +233,7 @@ def render_table_sql(
     template : TemplateKey | None, optional
         Template key to use (default: 'ddl').
     template_path : str | None, optional
-        Path to a custom template file (overrides ``template``).
+        Path to a custom template file (overrides *template*).
 
     Returns
     -------
@@ -264,7 +264,7 @@ def render_tables(
     template : TemplateKey | None, optional
         Template key to use (default: 'ddl').
     template_path : str | None, optional
-        Path to a custom template file (overrides ``template``).
+        Path to a custom template file (overrides *template*).
 
     Returns
     -------

etlplus/database/engine.py

@@ -87,7 +87,7 @@ def load_database_url_from_config(
     Extract a database URL/DSN from a YAML/JSON config file.
 
     The loader is schema-tolerant: it looks for a top-level "databases" map
-    and then for a named entry (``name``). Each entry may contain either a
+    and then for a named entry (*name*). Each entry may contain either a
     ``connection_string``/``url``/``dsn`` or a nested ``default`` block with
     those fields.
 
@@ -136,9 +136,25 @@ def load_database_url_from_config(
     return url
 
 
-def make_engine(url: str | None = None, **engine_kwargs: Any) -> Engine:
-    """Create a SQLAlchemy Engine, defaulting to env config if no URL given."""
+def make_engine(
+    url: str | None = None,
+    **engine_kwargs: Any,
+) -> Engine:
+    """
+    Create a SQLAlchemy Engine, defaulting to env config if no URL given.
+
+    Parameters
+    ----------
+    url : str | None, optional
+        Database URL/DSN string. When omitted, ``DATABASE_URL`` is used.
+    **engine_kwargs : Any
+        Extra keyword arguments forwarded to ``create_engine``.
 
+    Returns
+    -------
+    Engine
+        Configured SQLAlchemy engine instance.
+    """
     resolved_url = url or DATABASE_URL
     return create_engine(resolved_url, pool_pre_ping=True, **engine_kwargs)
 

etlplus/database/orm.py

@@ -201,12 +201,14 @@ def build_models(
 ) -> ModelRegistry:
     """
     Build SQLAlchemy ORM models from table specifications.
+
     Parameters
     ----------
     specs : list[TableSpec]
         List of table specifications.
     base : type[DeclarativeBase], optional
         Base class for the ORM models (default: :class:`Base`).
+
     Returns
     -------
     ModelRegistry