etlplus 0.7.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

etlplus/cli/state.py

@@ -0,0 +1,336 @@
+"""
+:mod:`etlplus.cli.state` module.
+
+Shared state and helper utilities for the ``etlplus`` command-line interface
+(CLI).
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Collection
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+import typer
+
+from .constants import DATA_CONNECTORS
+
+# SECTION: EXPORTS ========================================================== #
+
+__all__ = [
+    # Classes
+    'CliState',
+    # Functions
+    'ensure_state',
+    'infer_resource_type',
+    'infer_resource_type_or_exit',
+    'infer_resource_type_soft',
+    'log_inferred_resource',
+    'optional_choice',
+    'resolve_resource_type',
+    'validate_choice',
+]
+
+
+# SECTION: INTERNAL CONSTANTS =============================================== #
+
+
+_DB_SCHEMES: Final[tuple[str, ...]] = (
+    'postgres://',
+    'postgresql://',
+    'mysql://',
+)
+
+
+# SECTION: DATA CLASSES ===================================================== #
+
+
+@dataclass(slots=True)
+class CliState:
+    """
+    Mutable container for runtime CLI toggles.
+
+    Attributes
+    ----------
+    pretty : bool
+        Whether to pretty-print output.
+    quiet : bool
+        Whether to suppress non-error output.
+    verbose : bool
+        Whether to enable verbose logging.
+    """
+
+    pretty: bool = True
+    quiet: bool = False
+    verbose: bool = False
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def ensure_state(
+    ctx: typer.Context,
+) -> CliState:
+    """
+    Return the :class:`CliState` stored on the :mod:`typer` context.
+
+    Initializes a new :class:`CliState` if none exists.
+
+    Parameters
+    ----------
+    ctx : typer.Context
+        The Typer command context.
+
+    Returns
+    -------
+    CliState
+        The CLI state object.
+    """
+    if not isinstance(getattr(ctx, 'obj', None), CliState):
+        ctx.obj = CliState()
+    return ctx.obj
+
+
+def infer_resource_type(
+    value: str,
+) -> str:
+    """
+    Infer the resource type from a path, URL, or DSN string.
+
+    Parameters
+    ----------
+    value : str
+        The resource identifier (path, URL, or DSN).
+
+    Returns
+    -------
+    str
+        The inferred resource type: ``file``, ``api``, or ``database``.
+
+    Raises
+    ------
+    ValueError
+        If inference fails.
+    """
+    val = (value or '').strip()
+    low = val.lower()
+
+    match (val, low):
+        case ('-', _):
+            return 'file'
+        case (_, inferred) if inferred.startswith(('http://', 'https://')):
+            return 'api'
+        case (_, inferred) if inferred.startswith(_DB_SCHEMES):
+            return 'database'
+
+    path = Path(val)
+    if path.exists() or path.suffix:
+        return 'file'
+
+    raise ValueError(
+        'Could not infer resource type. '
+        'Use --source-type/--target-type to specify it.',
+    )
+
+
+def infer_resource_type_or_exit(
+    value: str,
+) -> str:
+    """
+    Infer a resource type and map ``ValueError`` to ``BadParameter``.
+
+    Parameters
+    ----------
+    value : str
+        The resource identifier (path, URL, or DSN).
+
+    Returns
+    -------
+    str
+        The inferred resource type: ``file``, ``api``, or ``database``.
+
+    Raises
+    ------
+    typer.BadParameter
+        If inference fails.
+    """
+    try:
+        return infer_resource_type(value)
+    except ValueError as exc:  # pragma: no cover - exercised indirectly
+        raise typer.BadParameter(str(exc)) from exc
+
+
+def infer_resource_type_soft(
+    value: str | None,
+) -> str | None:
+    """
+    Make a best-effort inference that tolerates inline payloads.
+
+    Parameters
+    ----------
+    value : str | None
+        The resource identifier (path, URL, DSN, or inline payload).
+
+    Returns
+    -------
+    str | None
+        The inferred resource type, or ``None`` if inference failed.
+    """
+    if value is None:
+        return None
+    try:
+        return infer_resource_type(value)
+    except ValueError:
+        return None
+
+
+def log_inferred_resource(
+    state: CliState,
+    *,
+    role: str,
+    value: str,
+    resource_type: str | None,
+) -> None:
+    """
+    Emit a uniform verbose message for inferred resource types.
+
+    Parameters
+    ----------
+    state : CliState
+        The current CLI state.
+    role : str
+        The resource role, e.g., ``source`` or ``target``.
+    value : str
+        The resource identifier (path, URL, or DSN).
+    resource_type : str | None
+        The inferred resource type, or ``None`` if inference failed.
+    """
+    if state.quiet or not state.verbose or resource_type is None:
+        return
+    print(
+        f'Inferred {role}_type={resource_type} for {role}={value}',
+        file=sys.stderr,
+    )
+
+
+def optional_choice(
+    value: str | None,
+    choices: Collection[str],
+    *,
+    label: str,
+) -> str | None:
+    """
+    Validate optional CLI choice inputs while preserving ``None``.
+
+    Parameters
+    ----------
+    value : str | None
+        The input value to validate, or ``None``.
+    choices : Collection[str]
+        The set of valid choices.
+    label : str
+        The label for error messages.
+
+    Returns
+    -------
+    str | None
+        The validated choice, or ``None`` if input was ``None``.
+    """
+    if value is None:
+        return None
+    return validate_choice(value, choices, label=label)
+
+
+def resolve_resource_type(
+    *,
+    explicit_type: str | None,
+    override_type: str | None,
+    value: str,
+    label: str,
+    conflict_error: str | None = None,
+    legacy_file_error: str | None = None,
+) -> str:
+    """
+    Resolve resource type preference order and validate it.
+
+    Parameters
+    ----------
+    explicit_type : str | None
+        The explicit resource type from the CLI, or ``None`` if not provided.
+    override_type : str | None
+        The override resource type from the CLI, or ``None`` if not provided.
+    value : str
+        The resource identifier (path, URL, or DSN).
+    label : str
+        The label for error messages.
+    conflict_error : str | None, optional
+        The error message to raise if both explicit and override types are
+        provided, by default ``None``.
+    legacy_file_error : str | None, optional
+        The error message to raise if the explicit type is ``file``, by default
+        ``None``.
+
+    Returns
+    -------
+    str
+        The resolved and validated resource type.
+
+    Raises
+    ------
+    typer.BadParameter
+        If there is a conflict between explicit and override types, or if the
+        explicit type is ``file`` when disallowed.
+    """
+    if explicit_type is not None:
+        if override_type is not None and conflict_error:
+            raise typer.BadParameter(conflict_error)
+        if legacy_file_error and explicit_type.strip().lower() == 'file':
+            raise typer.BadParameter(legacy_file_error)
+        candidate = explicit_type
+    else:
+        candidate = override_type or infer_resource_type_or_exit(value)
+    return validate_choice(candidate, DATA_CONNECTORS, label=label)
+
+
+def validate_choice(
+    value: str | object,
+    choices: Collection[str],
+    *,
+    label: str,
+) -> str:
+    """
+    Validate CLI input against a whitelist of choices.
+
+    Parameters
+    ----------
+    value : str | object
+        The input value to validate.
+    choices : Collection[str]
+        The set of valid choices.
+    label : str
+        The label for error messages.
+
+    Returns
+    -------
+    str
+        The validated choice.
+
+    Raises
+    ------
+    typer.BadParameter
+        If the input value is not in the set of valid choices.
+    """
+    v = str(value or '').strip().lower()
+    normalized_choices = {c.lower() for c in choices}
+    if v in normalized_choices:
+        # Preserve original casing from choices when possible for messages
+        for choice in choices:
+            if choice.lower() == v:
+                return choice
+        return v
+    allowed = ', '.join(sorted(choices))
+    raise typer.BadParameter(
+        f"Invalid {label} '{value}'. Choose from: {allowed}",
+    )

etlplus/cli/types.py

@@ -0,0 +1,33 @@
+"""
+:mod:`etlplus.cli.types` module.
+
+Type aliases for :mod:`etlplus.cli` helpers.
+
+Notes
+-----
+- Keeps other modules decoupled from ``typing`` details.
+
+Examples
+--------
+>>> from etlplus.cli.types import DataConnectorContext
+>>> connector: DataConnectorContext = 'source'
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    # Type Aliases
+    'DataConnectorContext',
+]
+
+
+# SECTION: TYPE ALIASES ===================================================== #
+
+
+# Data connector context.
+type DataConnectorContext = Literal['source', 'target']

etlplus/database/__init__.py

@@ -18,6 +18,7 @@ from .engine import engine
 from .engine import load_database_url_from_config
 from .engine import make_engine
 from .engine import session
+from .orm import Base
 from .orm import build_models
 from .orm import load_and_build_models
 from .schema import load_table_specs
@@ -36,6 +37,7 @@ __all__ = [
     'render_table_sql',
     'render_tables',
     'render_tables_to_string',
+    'Base',
     # Singletons
     'engine',
     'session',

etlplus/database/ddl.py

@@ -15,7 +15,6 @@ import os
 from collections.abc import Iterable
 from collections.abc import Mapping
 from pathlib import Path
-from typing import Any
 from typing import Final
 
 from jinja2 import DictLoader
@@ -24,6 +23,9 @@ from jinja2 import FileSystemLoader
 from jinja2 import StrictUndefined
 
 from ..file import File
+from ..types import StrAnyMap
+from ..types import StrPath
+from ..types import TemplateKey
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -52,7 +54,7 @@ _SUPPORTED_SPEC_SUFFIXES: Final[frozenset[str]] = frozenset(
 # SECTION: CONSTANTS ======================================================== #
 
 
-TEMPLATES: Final[dict[str, str]] = {
+TEMPLATES: Final[dict[TemplateKey, str]] = {
     'ddl': 'ddl.sql.j2',
     'view': 'view.sql.j2',
 }
@@ -64,7 +66,8 @@ TEMPLATES: Final[dict[str, str]] = {
 def _load_template_text(
     filename: str,
 ) -> str:
-    """Return the bundled template text.
+    """
+    Return the bundled template text.
 
     Parameters
     ----------
@@ -99,16 +102,17 @@ def _load_template_text(
 
 def _resolve_template(
     *,
-    template_key: str | None,
-    template_path: str | None,
+    template_key: TemplateKey | None,
+    template_path: StrPath | None,
 ) -> tuple[Environment, str]:
-    """Return environment and template name for rendering.
+    """
+    Return environment and template name for rendering.
 
     Parameters
     ----------
-    template_key : str | None
+    template_key : TemplateKey | None
         Named template key bundled with the package.
-    template_path : str | None
+    template_path : StrPath | None
         Explicit template file override.
 
     Returns
@@ -123,7 +127,11 @@ def _resolve_template(
     ValueError
         If the template key is unknown.
     """
-    file_override = template_path or os.environ.get('TEMPLATE_NAME')
+    file_override = (
+        str(template_path)
+        if template_path is not None
+        else os.environ.get('TEMPLATE_NAME')
+    )
     if file_override:
         path = Path(file_override)
         if not path.exists():
@@ -137,14 +145,14 @@ def _resolve_template(
         )
         return env, path.name
 
-    key = (template_key or 'ddl').strip()
+    key: TemplateKey = template_key or 'ddl'
     if key not in TEMPLATES:
         choices = ', '.join(sorted(TEMPLATES))
         raise ValueError(
             f'Unknown template key "{key}". Choose from: {choices}',
         )
 
-    # Load template from package data
+    # Load template from package data.
     template_filename = TEMPLATES[key]
     template_source = _load_template_text(template_filename)
 
@@ -161,19 +169,19 @@ def _resolve_template(
 
 
 def load_table_spec(
-    path: Path | str,
-) -> dict[str, Any]:
+    path: StrPath,
+) -> StrAnyMap:
     """
     Load a table specification from disk.
 
     Parameters
     ----------
-    path : Path | str
+    path : StrPath
         Path to the JSON or YAML specification file.
 
     Returns
     -------
-    dict[str, Any]
+    StrAnyMap
         Parsed table specification mapping.
 
     Raises
@@ -210,9 +218,9 @@ def load_table_spec(
 
 
 def render_table_sql(
-    spec: Mapping[str, Any],
+    spec: StrAnyMap,
     *,
-    template: str | None = 'ddl',
+    template: TemplateKey | None = 'ddl',
     template_path: str | None = None,
 ) -> str:
     """
@@ -220,9 +228,9 @@ def render_table_sql(
 
     Parameters
     ----------
-    spec : Mapping[str, Any]
+    spec : StrAnyMap
         Table specification mapping.
-    template : str | None, optional
+    template : TemplateKey | None, optional
         Template key to use (default: 'ddl').
     template_path : str | None, optional
         Path to a custom template file (overrides ``template``).
@@ -241,9 +249,9 @@ def render_table_sql(
 
 
 def render_tables(
-    specs: Iterable[Mapping[str, Any]],
+    specs: Iterable[StrAnyMap],
     *,
-    template: str | None = 'ddl',
+    template: TemplateKey | None = 'ddl',
     template_path: str | None = None,
 ) -> list[str]:
     """
@@ -251,9 +259,9 @@ def render_tables(
 
     Parameters
     ----------
-    specs : Iterable[Mapping[str, Any]]
+    specs : Iterable[StrAnyMap]
         Table specification mappings.
-    template : str | None, optional
+    template : TemplateKey | None, optional
         Template key to use (default: 'ddl').
     template_path : str | None, optional
         Path to a custom template file (overrides ``template``).
@@ -271,21 +279,21 @@ def render_tables(
 
 
 def render_tables_to_string(
-    spec_paths: Iterable[Path | str],
+    spec_paths: Iterable[StrPath],
     *,
-    template: str | None = 'ddl',
-    template_path: Path | str | None = None,
+    template: TemplateKey | None = 'ddl',
+    template_path: StrPath | None = None,
 ) -> str:
     """
     Render one or more specs and concatenate the SQL payloads.
 
     Parameters
     ----------
-    spec_paths : Iterable[Path | str]
+    spec_paths : Iterable[StrPath]
         Paths to table specification files.
-    template : str | None, optional
+    template : TemplateKey | None, optional
         Template key bundled with ETLPlus. Defaults to ``'ddl'``.
-    template_path : Path | str | None, optional
+    template_path : StrPath | None, optional
         Custom Jinja template to override the bundled templates.
 
     Returns

etlplus/database/engine.py

@@ -10,12 +10,15 @@ import os
 from collections.abc import Mapping
 from pathlib import Path
 from typing import Any
+from typing import Final
 
 from sqlalchemy import create_engine
 from sqlalchemy.engine import Engine
 from sqlalchemy.orm import sessionmaker
 
 from ..file import File
+from ..types import StrAnyMap
+from ..types import StrPath
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -33,7 +36,7 @@ __all__ = [
 # SECTION: INTERNAL CONSTANTS =============================================== #
 
 
-DATABASE_URL: str = (
+DATABASE_URL: Final[str] = (
     os.getenv('DATABASE_URL')
     or os.getenv('DATABASE_DSN')
     or 'sqlite+pysqlite:///:memory:'
@@ -43,13 +46,15 @@ DATABASE_URL: str = (
 # SECTION: INTERNAL FUNCTIONS =============================================== #
 
 
-def _resolve_url_from_mapping(cfg: Mapping[str, Any]) -> str | None:
+def _resolve_url_from_mapping(
+    cfg: StrAnyMap,
+) -> str | None:
     """
     Return a URL/DSN from a mapping if present.
 
     Parameters
     ----------
-    cfg : Mapping[str, Any]
+    cfg : StrAnyMap
         Configuration mapping potentially containing connection fields.
 
     Returns
@@ -74,7 +79,7 @@ def _resolve_url_from_mapping(cfg: Mapping[str, Any]) -> str | None:
 
 
 def load_database_url_from_config(
-    path: str | Path,
+    path: StrPath,
     *,
     name: str | None = None,
 ) -> str:
@@ -88,7 +93,7 @@ def load_database_url_from_config(
 
     Parameters
     ----------
-    path : str | Path
+    path : StrPath
         Location of the configuration file.
     name : str | None, optional
         Named database entry under the ``databases`` map (default: