etlplus 0.3.25__py3-none-any.whl → 0.4.1__py3-none-any.whl

etlplus/cli/main.py

@@ -0,0 +1,404 @@
+"""
+:mod:`etlplus.cli.main` module.
+
+Entry point helpers for the Typer-powered ``etlplus`` CLI.
+
+This module exposes :func:`main` for the console script as well as
+:func:`create_parser` for callers that still need an ``argparse`` parser.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from typing import Literal
+
+import typer
+
+from .. import __version__
+from ..enums import DataConnectorType
+from ..enums import FileFormat
+from ..utils import json_type
+from .app import PROJECT_URL
+from .app import app
+from .handlers import FORMAT_ENV_KEY
+from .handlers import cmd_extract
+from .handlers import cmd_list
+from .handlers import cmd_load
+from .handlers import cmd_pipeline
+from .handlers import cmd_run
+from .handlers import cmd_transform
+from .handlers import cmd_validate
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    # Functions
+    'create_parser',
+    'main',
+]
+
+
+# SECTION: TYPE ALIASES ===================================================== #
+
+
+type FormatContext = Literal['source', 'target']
+
+
+# SECTION: INTERNAL CLASSES ================================================= #
+
+
+class _FormatAction(argparse.Action):
+    """Argparse action that records when ``--format`` 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
+        setattr(namespace, self.dest, values)
+        namespace._format_explicit = True
+
+
+# SECTION: INTERNAL FUNCTIONS =============================================== #
+
+
+def _add_format_options(
+    parser: argparse.ArgumentParser,
+    *,
+    context: FormatContext,
+) -> None:
+    """Attach shared ``--format`` options to extract/load parsers."""
+
+    parser.set_defaults(_format_explicit=False)
+    parser.add_argument(
+        '--strict-format',
+        action='store_true',
+        help=(
+            'Treat providing --format for file '
+            f'{context}s as an error (overrides environment behavior)'
+        ),
+    )
+    parser.add_argument(
+        '--format',
+        choices=list(FileFormat.choices()),
+        default='json',
+        action=_FormatAction,
+        help=(
+            f'Format of the {context} when not a file. For file {context}s '
+            'this option is ignored and the format is inferred from the '
+            'filename extension.'
+        ),
+    )
+
+
+def _cli_description() -> str:
+    return '\n'.join(
+        [
+            'ETLPlus - A Swiss Army knife for simple ETL operations.',
+            '',
+            '    Provide a subcommand and options. Examples:',
+            '',
+            '    etlplus extract file in.csv -o out.json',
+            '    etlplus validate in.json --rules \'{"required": ["id"]}\'',
+            (
+                '    etlplus transform in.json --operations '
+                '\'{"select": ["id"]}\''
+            ),
+            '    etlplus load in.json file out.json',
+            '',
+            '    Enforce error if --format is provided for files. Examples:',
+            '',
+            '    etlplus extract file in.csv --format csv --strict-format',
+            (
+                '    etlplus load in.json file out.csv --format csv '
+                '--strict-format'
+            ),
+        ],
+    )
+
+
+def _cli_epilog(format_env_key: str) -> str:
+    return '\n'.join(
+        [
+            'Environment:',
+            (
+                f'    {format_env_key} controls behavior when '
+                '--format is provided for files.'
+            ),
+            '    Values:',
+            '        - error|fail|strict: treat as error',
+            '        - warn (default): print a warning',
+            '        - ignore|silent: no message',
+            '',
+            'Note:',
+            '    --strict-format overrides the environment behavior.',
+        ],
+    )
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """
+    Return the legacy :mod:`argparse` parser wired to current handlers.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Parser compatible with historical ``etlplus`` entry points.
+    """
+
+    parser = argparse.ArgumentParser(
+        prog='etlplus',
+        description=_cli_description(),
+        epilog=_cli_epilog(FORMAT_ENV_KEY),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument(
+        '-V',
+        '--version',
+        action='version',
+        version=f'%(prog)s {__version__}',
+    )
+
+    subparsers = parser.add_subparsers(
+        dest='command',
+        help='Available commands',
+    )
+
+    extract_parser = subparsers.add_parser(
+        'extract',
+        help='Extract data from sources (files, databases, REST APIs)',
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    extract_parser.add_argument(
+        'source_type',
+        choices=list(DataConnectorType.choices()),
+        help='Type of source to extract from',
+    )
+    extract_parser.add_argument(
+        'source',
+        help=(
+            'Source location (file path, database connection string, '
+            'or API URL)'
+        ),
+    )
+    extract_parser.add_argument(
+        '-o',
+        '--output',
+        help='Output file to save extracted data (JSON format)',
+    )
+    _add_format_options(extract_parser, context='source')
+    extract_parser.set_defaults(func=cmd_extract)
+
+    validate_parser = subparsers.add_parser(
+        'validate',
+        help='Validate data from sources',
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    validate_parser.add_argument(
+        'source',
+        help='Data source to validate (file path or JSON string)',
+    )
+    validate_parser.add_argument(
+        '--rules',
+        type=json_type,
+        default={},
+        help='Validation rules as JSON string',
+    )
+    validate_parser.set_defaults(func=cmd_validate)
+
+    transform_parser = subparsers.add_parser(
+        'transform',
+        help='Transform data',
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    transform_parser.add_argument(
+        'source',
+        help='Data source to transform (file path or JSON string)',
+    )
+    transform_parser.add_argument(
+        '--operations',
+        type=json_type,
+        default={},
+        help='Transformation operations as JSON string',
+    )
+    transform_parser.add_argument(
+        '-o',
+        '--output',
+        help='Output file to save transformed data',
+    )
+    transform_parser.set_defaults(func=cmd_transform)
+
+    load_parser = subparsers.add_parser(
+        'load',
+        help='Load data to targets (files, databases, REST APIs)',
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    load_parser.add_argument(
+        'source',
+        help='Data source to load (file path or JSON string)',
+    )
+    load_parser.add_argument(
+        'target_type',
+        choices=list(DataConnectorType.choices()),
+        help='Type of target to load to',
+    )
+    load_parser.add_argument(
+        'target',
+        help=(
+            'Target location (file path, database connection string, '
+            'or API URL)'
+        ),
+    )
+    _add_format_options(load_parser, context='target')
+    load_parser.set_defaults(func=cmd_load)
+
+    pipe_parser = subparsers.add_parser(
+        'pipeline',
+        help=(
+            'Inspect or run pipeline YAML (see '
+            f'{PROJECT_URL}/blob/main/docs/pipeline-guide.md)'
+        ),
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    pipe_parser.add_argument(
+        '--config',
+        required=True,
+        help='Path to pipeline YAML configuration file',
+    )
+    pipe_parser.add_argument(
+        '--list',
+        action='store_true',
+        help='List available job names and exit',
+    )
+    pipe_parser.add_argument(
+        '--run',
+        metavar='JOB',
+        help='Run a specific job by name',
+    )
+    pipe_parser.set_defaults(func=cmd_pipeline)
+
+    list_parser = subparsers.add_parser(
+        'list',
+        help='List ETL pipeline metadata',
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    list_parser.add_argument(
+        '--config',
+        required=True,
+        help='Path to pipeline YAML configuration file',
+    )
+    list_parser.add_argument(
+        '--pipelines',
+        action='store_true',
+        help='List ETL pipelines',
+    )
+    list_parser.add_argument(
+        '--sources',
+        action='store_true',
+        help='List data sources',
+    )
+    list_parser.add_argument(
+        '--targets',
+        action='store_true',
+        help='List data targets',
+    )
+    list_parser.add_argument(
+        '--transforms',
+        action='store_true',
+        help='List data transforms',
+    )
+    list_parser.set_defaults(func=cmd_list)
+
+    run_parser = subparsers.add_parser(
+        'run',
+        help=(
+            'Run an ETL pipeline '
+            f'(see {PROJECT_URL}/blob/main/docs/run-module.md)'
+        ),
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    run_parser.add_argument(
+        '--config',
+        required=True,
+        help='Path to pipeline YAML configuration file',
+    )
+    run_parser.add_argument(
+        '-j',
+        '--job',
+        help='Name of the job to run',
+    )
+    run_parser.add_argument(
+        '-p',
+        '--pipeline',
+        help='Name of the pipeline to run',
+    )
+    run_parser.set_defaults(func=cmd_run)
+
+    return parser
+
+
+def main(
+    argv: list[str] | None = None,
+) -> int:
+    """
+    Run the Typer-powered CLI and normalize exit codes.
+
+    Parameters
+    ----------
+    argv : list[str] | None, optional
+        Sequence of command-line arguments excluding the program name. When
+        ``None``, defaults to ``sys.argv[1:]``.
+
+    Returns
+    -------
+    int
+        A conventional POSIX exit code: zero on success, non-zero on error.
+
+    Raises
+    ------
+    SystemExit
+        Re-raises SystemExit exceptions to preserve exit codes.
+
+    Notes
+    -----
+    This function uses Typer (Click) for parsing/dispatch, but preserves the
+    existing `cmd_*` handlers by adapting parsed arguments into an
+    :class:`argparse.Namespace`.
+    """
+    resolved_argv = sys.argv[1:] if argv is None else list(argv)
+    command = typer.main.get_command(app)
+
+    try:
+        result = command.main(
+            args=resolved_argv,
+            prog_name='etlplus',
+            standalone_mode=False,
+        )
+        return int(result or 0)
+
+    except typer.Exit as exc:
+        return int(exc.exit_code)
+
+    except typer.Abort:
+        return 1
+
+    except KeyboardInterrupt:  # pragma: no cover - interactive path
+        # Conventional exit code for SIGINT
+        return 130
+
+    except SystemExit as e:
+        print(f'Error: {e}', file=sys.stderr)
+        raise e
+
+    except (OSError, TypeError, ValueError) as e:
+        print(f'Error: {e}', file=sys.stderr)
+        return 1

{etlplus-0.3.25.dist-info → etlplus-0.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.3.25
+Version: 0.4.1
 Summary: A Swiss Army knife for simple ETL operations
 Home-page: https://github.com/Dagitali/ETLPlus
 Author: ETLPlus Team
@@ -22,6 +22,7 @@ Requires-Dist: pyodbc>=5.3.0
 Requires-Dist: python-dotenv>=1.2.1
 Requires-Dist: pandas>=2.3.3
 Requires-Dist: requests>=2.32.5
+Requires-Dist: typer>=0.21.0
 Provides-Extra: dev
 Requires-Dist: black>=25.9.0; extra == "dev"
 Requires-Dist: build>=1.2.2; extra == "dev"

{etlplus-0.3.25.dist-info → etlplus-0.4.1.dist-info}/RECORD

@@ -1,7 +1,6 @@
 etlplus/__init__.py,sha256=M2gScnyir6WOMAh_EuoQIiAzdcTls0_5hbd_Q6of8I0,1021
-etlplus/__main__.py,sha256=lSbVOF5Mnd_ljmCqK7nTuF_MRDYTkL73eZEFeUQ_vnI,510
+etlplus/__main__.py,sha256=btoROneNiigyfBU7BSzPKZ1R9gzBMpxcpsbPwmuHwTM,479
 etlplus/__version__.py,sha256=1E0GMK_yUWCMQFKxXjTvyMwofi0qT2k4CDNiHWiymWE,327
-etlplus/cli.py,sha256=dmMW5dLbFiDRGne97qDsqr3YuU30g_Ekl_vo7bgDLig,21752
 etlplus/enums.py,sha256=V_j18Ud2BCXpFsBk2pZGrvCVrvAMJ7uja1z9fppFGso,10175
 etlplus/extract.py,sha256=f44JdHhNTACxgn44USx05paKTwq7LQY-V4wANCW9hVM,6173
 etlplus/file.py,sha256=RxIAsGDN4f_vNA2B5-ct88JNd_ISAyYbooIRE5DstS8,17972
@@ -31,6 +30,10 @@ etlplus/api/pagination/paginator.py,sha256=wtdY_er4yfjx5yTUQJ1gPq-IuWmpLAHeG5buB
 etlplus/api/rate_limiting/__init__.py,sha256=ZySB1dZettEDnWvI1EHf_TZ9L08M_kKsNR-Y_lbU6kI,1070
 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=xNsre2GDErbQv3Cwd3hwRHpkkoh-ZYIbBLrnKrFs0VI,25268
+etlplus/cli/handlers.py,sha256=QlZTTg9R493J2R4z81yRS1Zt3XEGeiqmszGT_GT2c5A,16059
+etlplus/cli/main.py,sha256=nofNgGqfStGdyNLV6O8k8XguRNhMIm92EhuO68nGPOE,11148
 etlplus/config/__init__.py,sha256=VZWzOg7d2YR9NT6UwKTv44yf2FRUMjTHynkm1Dl5Qzo,1486
 etlplus/config/connector.py,sha256=0-TIwevHbKRHVmucvyGpPd-3tB1dKHB-dj0yJ6kq5eY,9809
 etlplus/config/jobs.py,sha256=hmzRCqt0OvCEZZR4ONKrd3lvSv0OmayjLc4yOBk3ug8,7399
@@ -40,9 +43,9 @@ etlplus/config/types.py,sha256=a0epJ3z16HQ5bY3Ctf8s_cQPa3f0HHcwdOcjCP2xoG4,4954
 etlplus/config/utils.py,sha256=4SUHMkt5bKBhMhiJm-DrnmE2Q4TfOgdNCKz8PJDS27o,3443
 etlplus/validation/__init__.py,sha256=Pe5Xg1_EA4uiNZGYu5WTF3j7odjmyxnAJ8rcioaplSQ,1254
 etlplus/validation/utils.py,sha256=Mtqg449VIke0ziy_wd2r6yrwJzQkA1iulZC87FzXMjo,10201
-etlplus-0.3.25.dist-info/licenses/LICENSE,sha256=MuNO63i6kWmgnV2pbP2SLqP54mk1BGmu7CmbtxMmT-U,1069
-etlplus-0.3.25.dist-info/METADATA,sha256=QehDLWQ0MN7sUykhLs9gQgOrT3ru_QgaEFftJCkgNgw,16730
-etlplus-0.3.25.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-etlplus-0.3.25.dist-info/entry_points.txt,sha256=6w-2-jzuPa55spzK34h-UKh2JTEShh38adFRONNP9QE,45
-etlplus-0.3.25.dist-info/top_level.txt,sha256=aWWF-udn_sLGuHTM6W6MLh99ArS9ROkUWO8Mi8y1_2U,8
-etlplus-0.3.25.dist-info/RECORD,,
+etlplus-0.4.1.dist-info/licenses/LICENSE,sha256=MuNO63i6kWmgnV2pbP2SLqP54mk1BGmu7CmbtxMmT-U,1069
+etlplus-0.4.1.dist-info/METADATA,sha256=PGl9CCUvlxyqz_zNfG_ibDQ5iOxib70Vas1xeWURgA4,16758
+etlplus-0.4.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+etlplus-0.4.1.dist-info/entry_points.txt,sha256=6w-2-jzuPa55spzK34h-UKh2JTEShh38adFRONNP9QE,45
+etlplus-0.4.1.dist-info/top_level.txt,sha256=aWWF-udn_sLGuHTM6W6MLh99ArS9ROkUWO8Mi8y1_2U,8
+etlplus-0.4.1.dist-info/RECORD,,