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

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__
@@ -22,7 +24,6 @@ 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
@@ -51,7 +52,9 @@ type FormatContext = Literal['source', 'target']
 
 
 class _FormatAction(argparse.Action):
-    """Argparse action that records when ``--format`` is provided."""
+    """
+    Argparse action that records when ``--source-format`` or
+    ``--target-format`` is provided."""
 
     def __call__(
         self,
@@ -67,31 +70,89 @@ 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,
+    *,
+    required: bool = True,
+) -> None:
+    """Attach the shared ``--config`` option used by legacy commands.
+
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        Parser receiving the option.
+    required : bool, optional
+        Whether the flag must be provided. Defaults to ``True``.
+    """
+
+    parser.add_argument(
+        '--config',
+        required=required,
+        help='Path to pipeline YAML configuration file',
+    )
+
+
 def _add_format_options(
     parser: argparse.ArgumentParser,
     *,
     context: FormatContext,
 ) -> None:
-    """Attach shared ``--format`` options to extract/load parsers."""
+    """
+    Attach shared ``--source-format`` or ``--target-format`` options to
+    extract/load parsers.
 
+    Parameters
+    ----------
+    parser : argparse.ArgumentParser
+        Parser to augment.
+    context : FormatContext
+        Context for the format option: either ``'source'`` or ``'target'``
+    """
     parser.set_defaults(_format_explicit=False)
     parser.add_argument(
-        '--strict-format',
-        action='store_true',
+        '--source-format',
+        choices=list(FileFormat.choices()),
+        default='json',
+        action=_FormatAction,
         help=(
-            'Treat providing --format for file '
-            f'{context}s as an error (overrides environment behavior)'
+            f'Format of the {context}. Overrides filename-based inference '
+            'when provided.'
         ),
     )
     parser.add_argument(
-        '--format',
+        '--target-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.'
+            f'Format of the {context}. Overrides filename-based inference '
+            'when provided.'
         ),
     )
 
@@ -103,44 +164,119 @@ def _cli_description() -> str:
             '',
             '    Provide a subcommand and options. Examples:',
             '',
-            '    etlplus extract file in.csv -o out.json',
+            '    etlplus extract file in.csv > out.json',
             '    etlplus validate in.json --rules \'{"required": ["id"]}\'',
             (
-                '    etlplus transform in.json --operations '
-                '\'{"select": ["id"]}\''
+                '    etlplus transform --from file in.csv --operations '
+                '\'{"select": ["id"]}\' --to file -o out.json'
             ),
-            '    etlplus load in.json file out.json',
+            '    etlplus extract in.csv | etlplus load --to file out.json',
             '',
-            '    Enforce error if --format is provided for files. Examples:',
+            '    Override format inference when extensions are misleading:',
             '',
-            '    etlplus extract file in.csv --format csv --strict-format',
-            (
-                '    etlplus load in.json file out.csv --format csv '
-                '--strict-format'
-            ),
+            '    etlplus extract data.txt --source-format csv',
+            '    etlplus load payload.bin --target-format json',
         ],
     )
 
 
-def _cli_epilog(format_env_key: str) -> str:
+def _cli_epilog() -> 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.',
+            'Tip:',
+            '    --source-format and --target-format override format '
+            'inference based on filename extensions when needed.',
         ],
     )
 
 
+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 ======================================================== #
 
 
@@ -157,7 +293,7 @@ def create_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog='etlplus',
         description=_cli_description(),
-        epilog=_cli_epilog(FORMAT_ENV_KEY),
+        epilog=_cli_epilog(),
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
 
@@ -172,6 +308,7 @@ def create_parser() -> argparse.ArgumentParser:
         dest='command',
         help='Available commands',
     )
+    subparsers.required = True
 
     extract_parser = subparsers.add_parser(
         'extract',
@@ -190,11 +327,6 @@ def create_parser() -> argparse.ArgumentParser:
             '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)
 
@@ -231,9 +363,35 @@ def create_parser() -> argparse.ArgumentParser:
         help='Transformation operations as JSON string',
     )
     transform_parser.add_argument(
-        '-o',
-        '--output',
-        help='Output file to save transformed data',
+        '--from',
+        dest='from_',
+        choices=list(DataConnectorType.choices()),
+        help='Override the inferred source type (file, database, api).',
+    )
+    transform_parser.add_argument(
+        '--to',
+        dest='to',
+        choices=list(DataConnectorType.choices()),
+        help='Override the inferred target type (file, database, api).',
+    )
+    transform_parser.add_argument(
+        '--source-format',
+        choices=list(FileFormat.choices()),
+        dest='source_format',
+        help=(
+            'Input payload format when SOURCE is - or a literal payload. '
+            'File sources infer format from the extension.'
+        ),
+    )
+    transform_parser.add_argument(
+        '--target-format',
+        dest='target_format',
+        choices=list(FileFormat.choices()),
+        help=(
+            'Output payload format '
+            'when writing to stdout or non-file targets. '
+            'File targets infer format from the extension.'
+        ),
     )
     transform_parser.set_defaults(func=cmd_transform)
 
@@ -269,11 +427,7 @@ def create_parser() -> argparse.ArgumentParser:
         ),
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
     )
-    pipe_parser.add_argument(
-        '--config',
-        required=True,
-        help='Path to pipeline YAML configuration file',
-    )
+    _add_config_option(pipe_parser)
     pipe_parser.add_argument(
         '--list',
         action='store_true',
@@ -291,30 +445,26 @@ def create_parser() -> argparse.ArgumentParser:
         help='List ETL pipeline metadata',
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
     )
-    list_parser.add_argument(
-        '--config',
-        required=True,
-        help='Path to pipeline YAML configuration file',
+    _add_config_option(list_parser)
+    _add_boolean_flag(
+        list_parser,
+        name='pipelines',
+        help_text='List ETL pipelines',
     )
-    list_parser.add_argument(
-        '--pipelines',
-        action='store_true',
-        help='List ETL pipelines',
-    )
-    list_parser.add_argument(
-        '--sources',
-        action='store_true',
-        help='List data sources',
+    _add_boolean_flag(
+        list_parser,
+        name='sources',
+        help_text='List data sources',
     )
-    list_parser.add_argument(
-        '--targets',
-        action='store_true',
-        help='List data targets',
+    _add_boolean_flag(
+        list_parser,
+        name='targets',
+        help_text='List data targets',
     )
-    list_parser.add_argument(
-        '--transforms',
-        action='store_true',
-        help='List data transforms',
+    _add_boolean_flag(
+        list_parser,
+        name='transforms',
+        help_text='List data transforms',
     )
     list_parser.set_defaults(func=cmd_list)
 
@@ -326,11 +476,7 @@ def create_parser() -> argparse.ArgumentParser:
         ),
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
     )
-    run_parser.add_argument(
-        '--config',
-        required=True,
-        help='Path to pipeline YAML configuration file',
-    )
+    _add_config_option(run_parser)
     run_parser.add_argument(
         '-j',
         '--job',
@@ -365,6 +511,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.
 
@@ -385,6 +534,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.1.dist-info → etlplus-0.4.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.4.1
+Version: 0.4.7
 Summary: A Swiss Army knife for simple ETL operations
 Home-page: https://github.com/Dagitali/ETLPlus
 Author: ETLPlus Team
@@ -67,7 +67,7 @@ package and command-line interface for data extraction, validation, transformati
       - [Load Data](#load-data)
     - [Python API](#python-api)
     - [Complete ETL Pipeline Example](#complete-etl-pipeline-example)
-    - [Environment Variables](#environment-variables)
+    - [Format Overrides](#format-overrides)
   - [Transformation Operations](#transformation-operations)
     - [Filter Operations](#filter-operations)
     - [Aggregation Functions](#aggregation-functions)
@@ -79,6 +79,8 @@ package and command-line interface for data extraction, validation, transformati
       - [Test Layers](#test-layers)
     - [Code Coverage](#code-coverage)
     - [Linting](#linting)
+    - [Updating Demo Snippets](#updating-demo-snippets)
+    - [Releasing to PyPI](#releasing-to-pypi)
   - [Links](#links)
   - [License](#license)
   - [Contributing](#contributing)
@@ -169,9 +171,9 @@ etlplus --version
 
 #### Extract Data
 
-Note: For file sources, the format is inferred from the filename extension; the `--format` option is
-ignored.  To treat passing `--format` as an error for file sources, either set
-`ETLPLUS_FORMAT_BEHAVIOR=error` or pass the CLI flag `--strict-format`.
+Note: For file sources, the format is normally inferred from the filename extension. Use
+`--source-format` to override inference when a file lacks an extension or when you want to force a
+specific parser.
 
 Extract from JSON file:
 ```bash
@@ -212,6 +214,20 @@ etlplus validate examples/data/sample.json --rules '{"email": {"type": "string",
 
 #### Transform Data
 
+When piping data through `etlplus transform`, use `--source-format` whenever the SOURCE argument is
+`-` or a literal payload, mirroring the `etlplus extract` semantics. Use `--target-format` to
+control the emitted format for stdout or other non-file outputs, just like `etlplus load`. File
+paths continue to infer formats from their extensions. Use `--from` to override the inferred source
+connector type and `--to` to override the inferred target connector type, matching the `etlplus
+extract`/`etlplus load` behavior.
+
+Transform file inputs while overriding connector types:
+```bash
+etlplus transform --from file examples/data/sample.json \
+  --operations '{"select": ["name", "email"]}' \
+  --to file -o temp/selected_output.json
+```
+
 Filter and select fields:
 ```bash
 etlplus transform '[{"name": "John", "age": 30}, {"name": "Jane", "age": 25}]' \
@@ -235,19 +251,24 @@ etlplus transform examples/data/sample.json --operations '{"map": {"name": "new_
 
 #### Load Data
 
+`etlplus load` consumes JSON from stdin; provide only the target argument plus optional flags.
+
 Load to JSON file:
 ```bash
-etlplus load '{"name": "John", "age": 30}' file temp/sample_output.json
+etlplus extract file examples/data/sample.json \
+  | etlplus load --to file temp/sample_output.json
 ```
 
 Load to CSV file:
 ```bash
-etlplus load '[{"name": "John", "age": 30}]' file temp/sample_output.csv
+etlplus extract file examples/data/sample.csv \
+  | etlplus load --to file temp/sample_output.csv
 ```
 
 Load to REST API:
 ```bash
-etlplus load examples/data/sample.json api https://api.example.com/endpoint
+cat examples/data/sample.json \
+  | etlplus load --to api https://api.example.com/endpoint
 ```
 
 ### Python API
@@ -301,41 +322,28 @@ etlplus validate temp/sample_transformed.json \
   --rules '{"name": {"type": "string", "required": true}, "email": {"type": "string", "required": true}}'
 
 # 4. Load to CSV
-etlplus load temp/sample_transformed.json file temp/sample_output.csv
+cat temp/sample_transformed.json \
+  | etlplus load --to temp/sample_output.csv
 ```
 
-### Environment Variables
-
-ETLPlus honors a small number of environment toggles to refine CLI behavior:
+### Format Overrides
 
-- `ETLPLUS_FORMAT_BEHAVIOR`: controls what happens when `--format` is provided for
-  file sources or targets (extract/load) where the format is inferred from the
-  filename extension.
-  - `error|fail|strict`: treat as error (non-zero exit)
-  - `warn` (default): print a warning to stderr
-  - `ignore|silent`: no message
-- Precedence: the CLI flag `--strict-format` overrides the environment.
+`--source-format` and `--target-format` override whichever format would normally be inferred from a
+file extension. This is useful when an input lacks an extension (for example, `records.txt` that
+actually contains CSV) or when you intentionally want to treat a file as another format.
 
 Examples (zsh):
 
 ```zsh
-# Warn (default)
-etlplus extract file data.csv --format csv
-etlplus load data.json file out.csv --format csv
-
-# Enforce error via environment
-ETLPLUS_FORMAT_BEHAVIOR=error \
-  etlplus extract file data.csv --format csv
-ETLPLUS_FORMAT_BEHAVIOR=error \
-  etlplus load data.json file out.csv --format csv
-
-# Equivalent strict behavior via flag (overrides environment)
-etlplus extract file data.csv --format csv --strict-format
-etlplus load data.json file out.csv --format csv --strict-format
-
-# Recommended: rely on extension, no --format needed for files
-etlplus extract file data.csv
-etlplus load data.json file out.csv
+# Force CSV parsing for an extension-less file
+etlplus extract --from file data.txt --source-format csv
+
+# Write CSV to a file without the .csv suffix
+etlplus load --to file output.bin --target-format csv < data.json
+
+# Leave the flags off when extensions already match the desired format
+etlplus extract --from file data.csv
+etlplus load --to file data.json < data.json
 ```
 
 ## Transformation Operations

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

@@ -31,9 +31,9 @@ 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=xNsre2GDErbQv3Cwd3hwRHpkkoh-ZYIbBLrnKrFs0VI,25268
-etlplus/cli/handlers.py,sha256=QlZTTg9R493J2R4z81yRS1Zt3XEGeiqmszGT_GT2c5A,16059
-etlplus/cli/main.py,sha256=nofNgGqfStGdyNLV6O8k8XguRNhMIm92EhuO68nGPOE,11148
+etlplus/cli/app.py,sha256=pc9VDUb3Qc8u5-XyDrHJkrSR9D3bq4e9zLbaD8KzyfY,32618
+etlplus/cli/handlers.py,sha256=aI_ZlnJCGGkVnVJJPhmPRCXc31MxtLaOeqqJoo3ci48,15816
+etlplus/cli/main.py,sha256=LaE3q4jbQ8KTTvs4D_khpOdlTKrdaPmxB28WML6hnLg,15059
 etlplus/config/__init__.py,sha256=VZWzOg7d2YR9NT6UwKTv44yf2FRUMjTHynkm1Dl5Qzo,1486
 etlplus/config/connector.py,sha256=0-TIwevHbKRHVmucvyGpPd-3tB1dKHB-dj0yJ6kq5eY,9809
 etlplus/config/jobs.py,sha256=hmzRCqt0OvCEZZR4ONKrd3lvSv0OmayjLc4yOBk3ug8,7399
@@ -43,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.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,,
+etlplus-0.4.7.dist-info/licenses/LICENSE,sha256=MuNO63i6kWmgnV2pbP2SLqP54mk1BGmu7CmbtxMmT-U,1069
+etlplus-0.4.7.dist-info/METADATA,sha256=zD88Gnu6IAFvbIR_L--yZE5EN2VpEK-Q3B1CZypmF9I,17278
+etlplus-0.4.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+etlplus-0.4.7.dist-info/entry_points.txt,sha256=6w-2-jzuPa55spzK34h-UKh2JTEShh38adFRONNP9QE,45
+etlplus-0.4.7.dist-info/top_level.txt,sha256=aWWF-udn_sLGuHTM6W6MLh99ArS9ROkUWO8Mi8y1_2U,8
+etlplus-0.4.7.dist-info/RECORD,,