etlplus 0.4.6__tar.gz → 0.4.8__tar.gz

{etlplus-0.4.6 → etlplus-0.4.8}/.pre-commit-config.yaml

@@ -159,7 +159,11 @@ repos:
     rev: v1.19.0
     hooks:
       - id: mypy
-        args: [--ignore-missing-imports, --install-types, --non-interactive]
+        args:
+          - --cache-dir=.mypy_cache/pre-commit
+          - --ignore-missing-imports
+          - --install-types
+          - --non-interactive
 
   - repo: https://github.com/pycqa/flake8
     rev: 7.3.0

{etlplus-0.4.6/etlplus.egg-info → etlplus-0.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.4.6
+Version: 0.4.8
 Summary: A Swiss Army knife for simple ETL operations
 Home-page: https://github.com/Dagitali/ETLPlus
 Author: ETLPlus Team
@@ -306,6 +306,19 @@ For YAML-driven pipelines executed end-to-end (extract → validate → transfor
 - Authoring: [`docs/pipeline-guide.md`](docs/pipeline-guide.md)
 - Runner API and internals: [`docs/run-module.md`](docs/run-module.md)
 
+CLI quick reference for pipelines:
+
+```bash
+# List jobs or show a pipeline summary
+etlplus list --config examples/configs/pipeline.yml --jobs
+etlplus list --config examples/configs/pipeline.yml --summary
+
+# Run a job
+etlplus run --config examples/configs/pipeline.yml --job file_to_file_customers
+
+# Deprecated shim (will be removed): etlplus pipeline
+```
+
 ### Complete ETL Pipeline Example
 
 ```bash

{etlplus-0.4.6 → etlplus-0.4.8}/README.md

@@ -264,6 +264,19 @@ For YAML-driven pipelines executed end-to-end (extract → validate → transfor
 - Authoring: [`docs/pipeline-guide.md`](docs/pipeline-guide.md)
 - Runner API and internals: [`docs/run-module.md`](docs/run-module.md)
 
+CLI quick reference for pipelines:
+
+```bash
+# List jobs or show a pipeline summary
+etlplus list --config examples/configs/pipeline.yml --jobs
+etlplus list --config examples/configs/pipeline.yml --summary
+
+# Run a job
+etlplus run --config examples/configs/pipeline.yml --job file_to_file_customers
+
+# Deprecated shim (will be removed): etlplus pipeline
+```
+
 ### Complete ETL Pipeline Example
 
 ```bash

{etlplus-0.4.6 → etlplus-0.4.8}/docs/pipeline-guide.md

@@ -378,31 +378,32 @@ jobs:
 Once you have a pipeline YAML, you can run jobs either from the
 command line or directly from Python.
 
-### CLI: `etlplus pipeline` and `etlplus run`
+### CLI: `etlplus list` (inspect) and `etlplus run` (execute)
 
-List jobs defined in a pipeline file:
+List jobs or show a summary from a pipeline file:
 
 ```bash
-etlplus pipeline --config examples/configs/pipeline.yml --list
+etlplus list --config examples/configs/pipeline.yml --jobs
+etlplus list --config examples/configs/pipeline.yml --summary
 ```
 
 Run a specific job end-to-end (extract → validate → transform → load):
 
 ```bash
-etlplus pipeline --config examples/configs/pipeline.yml --run file_to_file_customers
-
-# Equivalent, using the dedicated run command
 etlplus run --config examples/configs/pipeline.yml --job file_to_file_customers
 ```
 
 Notes:
 
-- Both commands read the same YAML schema described in this guide.
+- These commands read the same YAML schema described in this guide.
 - Environment-variable substitution (e.g. `${GITHUB_TOKEN}`) is applied the same way as when loading
   configs via the Python API.
 - For more details on the orchestration implementation, see
   [Runner internals: etlplus.run](run-module.md).
 
+Deprecated: `etlplus pipeline` is still available as a shim but will be removed in a future release;
+prefer `list` and `run`.
+
 ### Python: `etlplus.run.run`
 
 To trigger a job programmatically, use the high-level runner function exposed by the package:

{etlplus-0.4.6 → etlplus-0.4.8}/etlplus/cli/app.py

@@ -782,8 +782,21 @@ def list_cmd(
         '--pipelines',
         help='List ETL pipelines',
     ),
-    sources: bool = typer.Option(False, '--sources', help='List data sources'),
-    targets: bool = typer.Option(False, '--targets', help='List data targets'),
+    sources: bool = typer.Option(
+        False,
+        '--sources',
+        help='List data sources',
+    ),
+    summary: bool = typer.Option(
+        False,
+        '--summary',
+        help='Show pipeline summary (name, version, sources, targets, jobs)',
+    ),
+    targets: bool = typer.Option(
+        False,
+        '--targets',
+        help='List data targets',
+    ),
     transforms: bool = typer.Option(
         False,
         '--transforms',
@@ -805,6 +818,8 @@ def list_cmd(
         If True, list ETL pipelines.
     sources : bool, optional
         If True, list data sources.
+    summary : bool, optional
+        If True, show pipeline summary (name, version, sources, targets, jobs).
     targets : bool, optional
         If True, list data targets.
     transforms : bool, optional
@@ -820,6 +835,7 @@ def list_cmd(
         state,
         command='list',
         config=config,
+        summary=summary,
         pipelines=pipelines,
         jobs=jobs,
         sources=sources,
@@ -953,7 +969,7 @@ def pipeline_cmd(
     ),
 ) -> int:
     """
-    Inspect or run a pipeline YAML configuration.
+    Deprecated wrapper to inspect or run a pipeline YAML configuration.
 
     Parameters
     ----------

{etlplus-0.4.6 → etlplus-0.4.8}/etlplus/cli/handlers.py

@@ -117,6 +117,8 @@ def _list_sections(
         Metadata output for the list command.
     """
     sections: dict[str, Any] = {}
+    if getattr(args, 'jobs', False):
+        sections['jobs'] = _pipeline_summary(cfg)['jobs']
     if getattr(args, 'pipelines', False):
         sections['pipelines'] = [cfg.name]
     if getattr(args, 'sources', False):
@@ -598,6 +600,12 @@ def cmd_pipeline(
     int
         Zero on success.
     """
+    print(
+        'DEPRECATED: use "etlplus list --summary|--jobs" or '
+        '"etlplus run --job/--pipeline" instead of "etlplus pipeline".',
+        file=sys.stderr,
+    )
+
     cfg = load_pipeline_config(args.config, substitute=True)
 
     list_flag = getattr(args, 'list', False) or getattr(args, 'jobs', False)
@@ -635,6 +643,10 @@ def cmd_list(args: argparse.Namespace) -> int:
         Zero on success.
     """
     cfg = load_pipeline_config(args.config, substitute=True)
+    if getattr(args, 'summary', False):
+        print_json(_pipeline_summary(cfg))
+        return 0
+
     print_json(_list_sections(cfg, args))
     return 0
 

{etlplus-0.4.6 → etlplus-0.4.8}/etlplus/cli/main.py

@@ -10,10 +10,12 @@ This module exposes :func:`main` for the console script as well as
 from __future__ import annotations
 
 import argparse
+import contextlib
 import sys
 from collections.abc import Sequence
 from typing import Literal
 
+import click
 import typer
 
 from .. import __version__
@@ -68,6 +70,32 @@ class _FormatAction(argparse.Action):
 # SECTION: INTERNAL FUNCTIONS =============================================== #
 
 
+def _add_boolean_flag(
+    parser: argparse.ArgumentParser,
+    *,
+    name: str,
+    help_text: str,
+) -> None:
+    """Add a toggle that also supports the ``--no-`` prefix via 3.13.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        Parser receiving the flag.
+    name : str
+        Primary flag name without leading dashes.
+    help_text : str
+        Help text rendered in ``--help`` output.
+    """
+
+    parser.add_argument(
+        f'--{name}',
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help=help_text,
+    )
+
+
 def _add_config_option(
     parser: argparse.ArgumentParser,
     *,
@@ -129,32 +157,6 @@ def _add_format_options(
     )
 
 
-def _add_boolean_flag(
-    parser: argparse.ArgumentParser,
-    *,
-    name: str,
-    help_text: str,
-) -> None:
-    """Add a toggle that also supports the ``--no-`` prefix via 3.13.
-
-    Parameters
-    ----------
-    parser : argparse.ArgumentParser
-        Parser receiving the flag.
-    name : str
-        Primary flag name without leading dashes.
-    help_text : str
-        Help text rendered in ``--help`` output.
-    """
-
-    parser.add_argument(
-        f'--{name}',
-        action=argparse.BooleanOptionalAction,
-        default=False,
-        help=help_text,
-    )
-
-
 def _cli_description() -> str:
     return '\n'.join(
         [
@@ -188,6 +190,93 @@ def _cli_epilog() -> str:
     )
 
 
+def _emit_context_help(
+    ctx: click.Context | None,
+) -> bool:
+    """
+    Mirror Click help output for the provided context onto stderr.
+
+    Parameters
+    ----------
+    ctx : click.Context | None
+        The Click context to emit help for.
+
+    Returns
+    -------
+    bool
+        ``True`` when help was emitted, ``False`` when ``ctx`` was ``None``.
+    """
+    if ctx is None:
+        return False
+
+    with contextlib.redirect_stdout(sys.stderr):
+        ctx.get_help()
+    return True
+
+
+def _emit_root_help(
+    command: click.Command,
+) -> None:
+    """
+    Print the root ``etlplus`` help text to stderr.
+
+    Parameters
+    ----------
+    command : click.Command
+        The root Typer/Click command.
+    """
+    ctx = command.make_context('etlplus', [], resilient_parsing=True)
+    try:
+        _emit_context_help(ctx)
+    finally:
+        ctx.close()
+
+
+def _is_illegal_option_error(
+    exc: click.exceptions.UsageError,
+) -> bool:
+    """
+    Return ``True`` when usage errors stem from invalid options.
+
+    Parameters
+    ----------
+    exc : click.exceptions.UsageError
+        The usage error to inspect.
+
+    Returns
+    -------
+    bool
+        ``True`` when the error indicates illegal options.
+    """
+    return isinstance(
+        exc,
+        (
+            click.exceptions.BadOptionUsage,
+            click.exceptions.NoSuchOption,
+        ),
+    )
+
+
+def _is_unknown_command_error(
+    exc: click.exceptions.UsageError,
+) -> bool:
+    """
+    Return ``True`` when a :class:`UsageError` indicates bad subcommand.
+
+    Parameters
+    ----------
+    exc : click.exceptions.UsageError
+        The usage error to inspect.
+
+    Returns
+    -------
+    bool
+        ``True`` when the error indicates an unknown command.
+    """
+    message = getattr(exc, 'message', None) or str(exc)
+    return message.startswith('No such command ')
+
+
 # SECTION: FUNCTIONS ======================================================== #
 
 
@@ -333,8 +422,9 @@ def create_parser() -> argparse.ArgumentParser:
     pipe_parser = subparsers.add_parser(
         'pipeline',
         help=(
-            'Inspect or run pipeline YAML (see '
-            f'{PROJECT_URL}/blob/main/docs/pipeline-guide.md)'
+            'DEPRECATED: use "list" (for summary/jobs) or "run" (to execute); '
+            'see '
+            f'{PROJECT_URL}/blob/main/docs/pipeline-guide.md'
         ),
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
     )
@@ -357,6 +447,11 @@ def create_parser() -> argparse.ArgumentParser:
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
     )
     _add_config_option(list_parser)
+    _add_boolean_flag(
+        list_parser,
+        name='jobs',
+        help_text='List ETL jobs',
+    )
     _add_boolean_flag(
         list_parser,
         name='pipelines',
@@ -367,6 +462,13 @@ def create_parser() -> argparse.ArgumentParser:
         name='sources',
         help_text='List data sources',
     )
+    _add_boolean_flag(
+        list_parser,
+        name='summary',
+        help_text=(
+            'Show pipeline summary (name, version, sources, targets, jobs)'
+        ),
+    )
     _add_boolean_flag(
         list_parser,
         name='targets',
@@ -422,6 +524,9 @@ def main(
 
     Raises
     ------
+    click.exceptions.UsageError
+        Re-raises Typer/Click usage errors after printing help for unknown
+        commands.
     SystemExit
         Re-raises SystemExit exceptions to preserve exit codes.
 
@@ -442,6 +547,19 @@ def main(
         )
         return int(result or 0)
 
+    except click.exceptions.UsageError as exc:
+        if _is_unknown_command_error(exc):
+            typer.echo(f'Error: {exc}', err=True)
+            _emit_root_help(command)
+            return int(getattr(exc, 'exit_code', 2))
+        if _is_illegal_option_error(exc):
+            typer.echo(f'Error: {exc}', err=True)
+            if not _emit_context_help(exc.ctx):
+                _emit_root_help(command)
+            return int(getattr(exc, 'exit_code', 2))
+
+        raise
+
     except typer.Exit as exc:
         return int(exc.exit_code)
 

{etlplus-0.4.6 → etlplus-0.4.8/etlplus.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.4.6
+Version: 0.4.8
 Summary: A Swiss Army knife for simple ETL operations
 Home-page: https://github.com/Dagitali/ETLPlus
 Author: ETLPlus Team
@@ -306,6 +306,19 @@ For YAML-driven pipelines executed end-to-end (extract → validate → transfor
 - Authoring: [`docs/pipeline-guide.md`](docs/pipeline-guide.md)
 - Runner API and internals: [`docs/run-module.md`](docs/run-module.md)
 
+CLI quick reference for pipelines:
+
+```bash
+# List jobs or show a pipeline summary
+etlplus list --config examples/configs/pipeline.yml --jobs
+etlplus list --config examples/configs/pipeline.yml --summary
+
+# Run a job
+etlplus run --config examples/configs/pipeline.yml --job file_to_file_customers
+
+# Deprecated shim (will be removed): etlplus pipeline
+```
+
 ### Complete ETL Pipeline Example
 
 ```bash

{etlplus-0.4.6 → etlplus-0.4.8}/examples/README.md

@@ -44,12 +44,12 @@ CLI examples:
 
 ```bash
 # List jobs defined in a pipeline file
-etlplus pipeline --config examples/configs/pipeline.yml --list
+etlplus list --config examples/configs/pipeline.yml --jobs
 
-# Run a specific job end-to-end
-etlplus pipeline --config examples/configs/pipeline.yml --run file_to_file_customers
+# Show a pipeline summary (name, version, sources, targets, jobs)
+etlplus list --config examples/configs/pipeline.yml --summary
 
-# Equivalent, using the dedicated run command
+# Run a specific job end-to-end
 etlplus run --config examples/configs/pipeline.yml --job file_to_file_customers
 ```
 

{etlplus-0.4.6 → etlplus-0.4.8}/tests/integration/test_i_pipeline_smoke.py

@@ -2,12 +2,13 @@
 :mod:`tests.integration.test_i_pipeline_smoke` module.
 
 Pipeline smoke integration test suite exercising a minimal file→file job via
-the CLI. Parametrized to verify both empty and non-empty inputs.
+the CLI (using the deprecated-free path). Parametrized to verify both empty
+and non-empty inputs.
 
 Notes
 -----
 - Builds a transient pipeline YAML string per test run.
-- Invokes ``etlplus pipeline --run <job>`` end-to-end.
+- Invokes ``etlplus run --job <job>`` end-to-end.
 - Validates output file contents against input data shape.
 """
 
@@ -85,7 +86,7 @@ class TestPipelineSmoke:
 
         code, out, err = cli_invoke(
             (
-                'pipeline',
+                'run',
                 '--config',
                 str(cfg_path),
                 '--job',

{etlplus-0.4.6 → etlplus-0.4.8}/tests/unit/cli/test_u_cli_main.py

@@ -60,6 +60,7 @@ class TestCreateParser:
 
     def test_extract_parser_sets_handler_and_format_flag(self) -> None:
         """Extract parser should bind handlers and flag explicit formats."""
+        # pylint: disable=protected-access
 
         parser = cli_main_module.create_parser()
         namespace = parser.parse_args(
@@ -74,7 +75,6 @@ class TestCreateParser:
 
     def test_list_parser_supports_boolean_flags(self) -> None:
         """List parser should surface boolean flag wiring."""
-
         parser = cli_main_module.create_parser()
         namespace = parser.parse_args(
             ['list', '--config', 'pipelines.yml', '--targets', '--transforms'],
@@ -95,7 +95,6 @@ class TestMain:
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
         """Test that the command return value is normalized into an ``int``."""
-
         captured: dict[str, object] = {}
 
         def _action(**kwargs: object) -> object:
@@ -161,7 +160,8 @@ class TestMain:
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
         """
-        ``typer.Abort`` should surface as a generic failure (exit code 1).
+        Test that ``typer.Abort`` propagates as a generic failure (exit code
+        1).
         """
 
         def _action(**kwargs: object) -> object:  # noqa: ARG001
@@ -175,7 +175,7 @@ class TestMain:
         self,
         monkeypatch: pytest.MonkeyPatch,
     ) -> None:
-        """``typer.Exit`` should propagate its exit code."""
+        """Test that ``typer.Exit`` propagates its exit code."""
 
         def _action(**kwargs: object) -> object:  # noqa: ARG001
             raise typer.Exit(17)
@@ -188,14 +188,52 @@ class TestMain:
         """Test that no args prints help and exits with exit code 0."""
         assert cli_main([]) == 0
 
+    def test_unknown_subcommand_emits_usage(
+        self,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        """Test that illegal subcommands show help and exit with code 2."""
+        exit_code = cli_main(['definitely-not-real'])
+        captured = capsys.readouterr()
+
+        assert exit_code == 2
+        assert 'No such command' in captured.err
+        assert 'Usage:' in captured.err
+
+    def test_unknown_root_option_emits_usage(
+        self,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        """Test that Unknown root options echo usage details to stderr."""
+
+        exit_code = cli_main(['--definitely-not-real-option'])
+        captured = capsys.readouterr()
+
+        assert exit_code == 2
+        assert 'No such option' in captured.err
+        assert 'Usage:' in captured.err
+
+    def test_unknown_subcommand_option_emits_usage(
+        self,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        """Test that unknown subcommand options surface usage help."""
+
+        exit_code = cli_main(['extract', '--definitely-not-real-option'])
+        captured = capsys.readouterr()
+
+        assert exit_code == 2
+        assert 'No such option' in captured.err
+        assert 'Usage:' in captured.err
+
     def test_value_error_returns_exit_code_1(
         self,
         monkeypatch: pytest.MonkeyPatch,
         capsys: pytest.CaptureFixture[str],
     ) -> None:
         """
-        Test that :class:`ValueError` from a command maps to exit code 1."""
-
+        Test that :class:`ValueError` from a command maps to exit code 1.
+        """
         monkeypatch.setattr(
             cli_app_module,
             'cmd_extract',