etlplus 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

etlplus/cli/options.py

@@ -0,0 +1,115 @@
+"""
+:mod:`etlplus.cli.options` module.
+
+Shared command-line interface (CLI) option helpers for both Typer and argparse
+entry points.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+
+from .constants import DEFAULT_FILE_FORMAT
+from .constants import FILE_FORMATS
+from .types import DataConnectorContext
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    # Classes
+    'FormatAction',
+    # Functions
+    'add_argparse_format_options',
+    'typer_format_option_kwargs',
+]
+
+
+# SECTION: CLASSES ========================================================== #
+
+
+class FormatAction(argparse.Action):
+    """Record when a format override flag is provided."""
+
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: str | Sequence[object] | None,
+        option_string: str | None = None,
+    ) -> None:  # pragma: no cover - argparse wiring
+        setattr(namespace, self.dest, values)
+        namespace._format_explicit = True
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def add_argparse_format_options(
+    parser: argparse.ArgumentParser,
+    *,
+    context: DataConnectorContext,
+) -> None:
+    """
+    Attach ``--source-format`` and ``--target-format`` arguments.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        Parser receiving the options.
+    context : DataConnectorContext
+        Either ``'source'`` or ``'target'`` to tailor help text.
+    """
+    parser.set_defaults(_format_explicit=False)
+    parser.add_argument(
+        '--source-format',
+        choices=sorted(FILE_FORMATS),
+        default=DEFAULT_FILE_FORMAT,
+        action=FormatAction,
+        help=(
+            f'Format of the {context}. Overrides filename-based inference '
+            'when provided.'
+        ),
+    )
+    parser.add_argument(
+        '--target-format',
+        choices=sorted(FILE_FORMATS),
+        default=DEFAULT_FILE_FORMAT,
+        action=FormatAction,
+        help=(
+            f'Format of the {context}. Overrides filename-based inference '
+            'when provided.'
+        ),
+    )
+
+
+def typer_format_option_kwargs(
+    *,
+    context: DataConnectorContext,
+    rich_help_panel: str = 'Format overrides',
+) -> dict[str, object]:
+    """
+    Return common Typer option kwargs for format overrides.
+
+    Parameters
+    ----------
+    context : DataConnectorContext
+        Either ``'source'`` or ``'target'`` to tailor help text.
+    rich_help_panel : str, optional
+        The rich help panel name. Default is ``'Format overrides'``.
+
+    Returns
+    -------
+    dict[str, object]
+        The Typer option keyword arguments.
+    """
+    return {
+        'metavar': 'FORMAT',
+        'show_default': False,
+        'rich_help_panel': rich_help_panel,
+        'help': (
+            f'Payload format when the {context} is stdin/inline or a '
+            'non-file connector. File connectors infer from extensions.'
+        ),
+    }

etlplus/cli/state.py

@@ -0,0 +1,411 @@
+"""
+:mod:`etlplus.cli.state` module.
+
+Shared state and helper utilities for the ``etlplus`` command-line interface
+(CLI).
+"""
+
+from __future__ import annotations
+
+import argparse
+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',
+    'format_namespace_kwargs',
+    'infer_resource_type',
+    'infer_resource_type_or_exit',
+    'infer_resource_type_soft',
+    'log_inferred_resource',
+    'ns',
+    'optional_choice',
+    'resolve_resource_type',
+    'stateful_namespace',
+    '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 format_namespace_kwargs(
+    *,
+    format_value: str | None,
+    default: str,
+) -> dict[str, object]:
+    """
+    Return common namespace kwargs for format handling.
+
+    Parameters
+    ----------
+    format_value : str | None
+        The explicit format value from the CLI, or ``None`` if not provided.
+    default : str
+        The default format to use if none is provided.
+
+    Returns
+    -------
+    dict[str, object]
+        The namespace keyword arguments for format handling.
+    """
+    return {
+        'format': (format_value or default),
+        '_format_explicit': (format_value is not None),
+    }
+
+
+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 --from/--to 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 not state.verbose or resource_type is None:
+        return
+    print(
+        f'Inferred {role}_type={resource_type} for {role}={value}',
+        file=sys.stderr,
+    )
+
+
+def ns(
+    **kwargs: object,
+) -> argparse.Namespace:
+    """
+    Build an :class:`argparse.Namespace` for the legacy handlers.
+
+    Parameters
+    ----------
+    **kwargs : object
+        Keyword arguments to include in the namespace.
+
+    Returns
+    -------
+    argparse.Namespace
+        The constructed namespace.
+    """
+    return argparse.Namespace(**kwargs)
+
+
+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 stateful_namespace(
+    state: CliState,
+    *,
+    command: str,
+    **kwargs: object,
+) -> argparse.Namespace:
+    """
+    Attach CLI state toggles to a handler namespace.
+
+    Parameters
+    ----------
+    state : CliState
+        The current CLI state.
+    command : str
+        The command name.
+    **kwargs : object
+        Additional keyword arguments for the namespace.
+
+    Returns
+    -------
+    argparse.Namespace
+        The constructed namespace with state toggles.
+    """
+    return ns(
+        command=command,
+        pretty=state.pretty,
+        quiet=state.quiet,
+        verbose=state.verbose,
+        **kwargs,
+    )
+
+
+def validate_choice(
+    value: str,
+    choices: Collection[str],
+    *,
+    label: str,
+) -> str:
+    """
+    Validate CLI input against a whitelist of choices.
+
+    Parameters
+    ----------
+    value : str
+        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 = (value or '').strip()
+    if v in choices:
+        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-0.8.0.dist-info → etlplus-0.8.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.8.0
+Version: 0.8.2
 Summary: A Swiss Army knife for simple ETL operations
 Home-page: https://github.com/Dagitali/ETLPlus
 Author: ETLPlus Team

{etlplus-0.8.0.dist-info → etlplus-0.8.2.dist-info}/RECORD

@@ -31,9 +31,14 @@ etlplus/api/rate_limiting/__init__.py,sha256=ZySB1dZettEDnWvI1EHf_TZ9L08M_kKsNR-
 etlplus/api/rate_limiting/config.py,sha256=2b4wIynblN-1EyMqI4aXa71SljzSjXYh5N1Nngr3jOg,9406
 etlplus/api/rate_limiting/rate_limiter.py,sha256=Uxozqd_Ej5Lsj-M-mLT2WexChgWh7x35_YP10yqYPQA,7159
 etlplus/cli/__init__.py,sha256=J97-Rv931IL1_b4AXnB7Fbbd7HKnHBpx18NQfC_kE6c,299
-etlplus/cli/app.py,sha256=kQuMmY-RqadRGWS5yDpkKl5bWdOpqbR0jqsXCORLsMA,34532
-etlplus/cli/handlers.py,sha256=5Blk5LSqTVSwTPPGEcbOw2NwNTTbFFOTxlpUdy5r2bA,17928
-etlplus/cli/main.py,sha256=1U2WS-yIxTEr6ZJJkQFtisCxOcZ3cdnjIxUTewapN5M,15878
+etlplus/cli/commands.py,sha256=laIfpxnnJM1XZvxQxaH1IheZbIsELruC1V3BeT2l8y0,16299
+etlplus/cli/constants.py,sha256=NJ6IvNyYEI8IdB7eMcc-vteQiiIwqid5YvmUk-5DRHY,1839
+etlplus/cli/handlers.py,sha256=F8ZtXWdtMvhDYYDUjZ3JkGFJh2xfWsE2PKX5ZRhP0RI,11310
+etlplus/cli/io.py,sha256=wHoKfgl-VT15cfiVeW3uPz_U7tPQ1ag7EQkRZtxPd38,7987
+etlplus/cli/main.py,sha256=iD4zSgJwsfzhqlBCNxD7a7y5ZutqB9upxCnGtNaZ_B8,14006
+etlplus/cli/options.py,sha256=44rgksvi0c9Evt_QzITnErVEuyGTaUulkQYZZgCke7k,3060
+etlplus/cli/state.py,sha256=ymiGJbnEO766BOYaqm_-qZaqBwdKYnGRuttrNVhDms0,9439
+etlplus/cli/types.py,sha256=tclhKVJXDqHzlTQBYKARfqMgDOcuBJ-Zej2pvFy96WM,652
 etlplus/config/__init__.py,sha256=VZWzOg7d2YR9NT6UwKTv44yf2FRUMjTHynkm1Dl5Qzo,1486
 etlplus/config/connector.py,sha256=0-TIwevHbKRHVmucvyGpPd-3tB1dKHB-dj0yJ6kq5eY,9809
 etlplus/config/jobs.py,sha256=hmzRCqt0OvCEZZR4ONKrd3lvSv0OmayjLc4yOBk3ug8,7399
@@ -52,9 +57,9 @@ etlplus/templates/ddl.sql.j2,sha256=s8fMWvcb4eaJVXkifuib1aQPljtZ8buuyB_uA-ZdU3Q,
 etlplus/templates/view.sql.j2,sha256=Iy8DHfhq5yyvrUKDxqp_aHIEXY4Tm6j4wT7YDEFWAhk,2180
 etlplus/validation/__init__.py,sha256=Pe5Xg1_EA4uiNZGYu5WTF3j7odjmyxnAJ8rcioaplSQ,1254
 etlplus/validation/utils.py,sha256=Mtqg449VIke0ziy_wd2r6yrwJzQkA1iulZC87FzXMjo,10201
-etlplus-0.8.0.dist-info/licenses/LICENSE,sha256=MuNO63i6kWmgnV2pbP2SLqP54mk1BGmu7CmbtxMmT-U,1069
-etlplus-0.8.0.dist-info/METADATA,sha256=VjENPm-4JBGKuJ_NIjRLjce135eB7_ZTOFY6ZmAdS30,19328
-etlplus-0.8.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-etlplus-0.8.0.dist-info/entry_points.txt,sha256=6w-2-jzuPa55spzK34h-UKh2JTEShh38adFRONNP9QE,45
-etlplus-0.8.0.dist-info/top_level.txt,sha256=aWWF-udn_sLGuHTM6W6MLh99ArS9ROkUWO8Mi8y1_2U,8
-etlplus-0.8.0.dist-info/RECORD,,
+etlplus-0.8.2.dist-info/licenses/LICENSE,sha256=MuNO63i6kWmgnV2pbP2SLqP54mk1BGmu7CmbtxMmT-U,1069
+etlplus-0.8.2.dist-info/METADATA,sha256=djlodCP_KPtdG2OKttP5QcpxJHCy3-0enqnIXKIZZEY,19328
+etlplus-0.8.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+etlplus-0.8.2.dist-info/entry_points.txt,sha256=6w-2-jzuPa55spzK34h-UKh2JTEShh38adFRONNP9QE,45
+etlplus-0.8.2.dist-info/top_level.txt,sha256=aWWF-udn_sLGuHTM6W6MLh99ArS9ROkUWO8Mi8y1_2U,8
+etlplus-0.8.2.dist-info/RECORD,,