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

etlplus/cli/io.py

@@ -0,0 +1,343 @@
+"""
+:mod:`etlplus.cli.io` module.
+
+Shared I/O helpers for CLI handlers (stdin/stdout, payload hydration).
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import io as _io
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+from typing import cast
+
+from ..enums import FileFormat
+from ..file import File
+from ..types import JSONData
+from ..utils import json_type
+from ..utils import print_json
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    # Functions
+    'emit_json',
+    'emit_or_write',
+    'explicit_cli_format',
+    'infer_payload_format',
+    'materialize_file_payload',
+    'parse_text_payload',
+    'presentation_flags',
+    'read_csv_rows',
+    'read_stdin_text',
+    'resolve_cli_payload',
+    'write_json_output',
+]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def emit_json(
+    data: Any,
+    *,
+    pretty: bool,
+) -> None:
+    """
+    Emit JSON honoring pretty/compact preference.
+
+    Parameters
+    ----------
+    data : Any
+        Data to serialize as JSON.
+    pretty : bool
+        Whether to pretty-print JSON output.
+    """
+    if pretty:
+        print_json(data)
+        return
+    dumped = json.dumps(data, ensure_ascii=False, separators=(',', ':'))
+    print(dumped)
+
+
+def emit_or_write(
+    data: Any,
+    output_path: str | None,
+    *,
+    pretty: bool,
+    success_message: str,
+) -> None:
+    """
+    Emit JSON or persist to disk based on ``output_path``.
+
+    Parameters
+    ----------
+    data : Any
+        The data to serialize.
+    output_path : str | None
+        Target file path; when falsy or ``'-'`` data is emitted to stdout.
+    pretty : bool
+        Whether to pretty-print JSON emission.
+    success_message : str
+        Message printed when writing to disk succeeds.
+    """
+    if write_json_output(
+        data,
+        output_path,
+        success_message=success_message,
+    ):
+        return
+    emit_json(data, pretty=pretty)
+
+
+def explicit_cli_format(
+    args: argparse.Namespace,
+) -> str | None:
+    """
+    Return explicit format hint when provided on CLI.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        The argparse namespace containing CLI arguments.
+
+    Returns
+    -------
+    str | None
+        The explicit format hint if provided, otherwise None.
+    """
+    if not getattr(args, '_format_explicit', False):
+        return None
+    for attr in ('format', 'target_format', 'source_format'):
+        value = getattr(args, attr, None)
+        if value is None:
+            continue
+        normalized = str(value).strip().lower()
+        if normalized:
+            return normalized
+    return None
+
+
+def infer_payload_format(
+    text: str,
+) -> str:
+    """
+    Infer JSON vs CSV from payload text.
+
+    Parameters
+    ----------
+    text : str
+        The payload text to analyze.
+
+    Returns
+    -------
+    str
+        The inferred format: either 'json' or 'csv'.
+    """
+    stripped = text.lstrip()
+    if stripped.startswith('{') or stripped.startswith('['):
+        return 'json'
+    return 'csv'
+
+
+def materialize_file_payload(
+    source: object,
+    *,
+    format_hint: str | None,
+    format_explicit: bool,
+) -> JSONData | object:
+    """
+    Return structured payloads when ``source`` references a file.
+
+    Parameters
+    ----------
+    source : object
+        The source payload, potentially a file path.
+    format_hint : str | None
+        An optional format hint (e.g., 'json', 'csv').
+    format_explicit : bool
+        Whether the format hint was explicitly provided.
+
+    Returns
+    -------
+    JSONData | object
+        The materialized payload if a file was read, otherwise the original
+        source.
+    """
+    if isinstance(source, (dict, list)):
+        return cast(JSONData, source)
+    if not isinstance(source, (str, os.PathLike)):
+        return source
+
+    path = Path(source)
+
+    normalized_hint = (format_hint or '').strip().lower()
+    fmt: FileFormat | None = None
+
+    if format_explicit and normalized_hint:
+        try:
+            fmt = FileFormat(normalized_hint)
+        except ValueError:
+            fmt = None
+    elif not format_explicit:
+        suffix = path.suffix.lower().lstrip('.')
+        if suffix:
+            try:
+                fmt = FileFormat(suffix)
+            except ValueError:
+                fmt = None
+
+    if fmt is None:
+        return source
+    if fmt == FileFormat.CSV:
+        return read_csv_rows(path)
+    return File(path, fmt).read()
+
+
+def parse_text_payload(
+    text: str,
+    fmt: str | None,
+) -> JSONData | str:
+    """
+    Parse JSON/CSV text into a Python payload.
+
+    Parameters
+    ----------
+    text : str
+        The text payload to parse.
+    fmt : str | None
+        An optional format hint (e.g., 'json', 'csv').
+
+    Returns
+    -------
+    JSONData | str
+        The parsed payload as JSON data or raw text.
+    """
+    effective = (fmt or '').strip().lower() or infer_payload_format(text)
+    if effective == 'json':
+        return cast(JSONData, json_type(text))
+    if effective == 'csv':
+        reader = csv.DictReader(_io.StringIO(text))
+        return [dict(row) for row in reader]
+    return text
+
+
+def presentation_flags(
+    args: argparse.Namespace,
+) -> tuple[bool, bool]:
+    """
+    Return (pretty, quiet) toggles with safe defaults.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        The argparse namespace containing CLI arguments.
+
+    Returns
+    -------
+    tuple[bool, bool]
+        A tuple containing the pretty and quiet flags.
+    """
+    return getattr(args, 'pretty', True), getattr(args, 'quiet', False)
+
+
+def read_csv_rows(
+    path: Path,
+) -> list[dict[str, str]]:
+    """
+    Read CSV rows into dictionaries.
+
+    Parameters
+    ----------
+    path : Path
+        The path to the CSV file.
+
+    Returns
+    -------
+    list[dict[str, str]]
+        The list of CSV rows as dictionaries.
+    """
+    with path.open(newline='', encoding='utf-8') as handle:
+        reader = csv.DictReader(handle)
+        return [dict(row) for row in reader]
+
+
+def read_stdin_text() -> str:
+    """Return entire stdin payload."""
+    return sys.stdin.read()
+
+
+def resolve_cli_payload(
+    source: object,
+    *,
+    format_hint: str | None,
+    format_explicit: bool,
+    hydrate_files: bool = True,
+) -> JSONData | object:
+    """
+    Normalize CLI-provided payloads, honoring stdin and inline data.
+
+    Parameters
+    ----------
+    source : object
+        The source payload, potentially stdin or a file path.
+    format_hint : str | None
+        An optional format hint (e.g., 'json', 'csv').
+    format_explicit : bool
+        Whether the format hint was explicitly provided.
+    hydrate_files : bool, optional
+        Whether to materialize file-based payloads. Default is True.
+
+    Returns
+    -------
+    JSONData | object
+        The resolved payload.
+    """
+    if isinstance(source, (os.PathLike, str)) and str(source) == '-':
+        text = read_stdin_text()
+        return parse_text_payload(text, format_hint)
+
+    if not hydrate_files:
+        return source
+
+    return materialize_file_payload(
+        source,
+        format_hint=format_hint,
+        format_explicit=format_explicit,
+    )
+
+
+def write_json_output(
+    data: Any,
+    output_path: str | None,
+    *,
+    success_message: str,
+) -> bool:
+    """
+    Persist JSON data to disk when output path provided.
+
+    Parameters
+    ----------
+    data : Any
+        The data to serialize as JSON.
+    output_path : str | None
+        The output file path, or None/'-' to skip writing.
+    success_message : str
+        The message to print upon successful write.
+
+    Returns
+    -------
+    bool
+        True if data was written to disk; False if not.
+    """
+    if not output_path or output_path == '-':
+        return False
+    File(Path(output_path), FileFormat.JSON).write_json(data)
+    print(f'{success_message} {output_path}')
+    return True

etlplus/cli/main.py

@@ -12,26 +12,21 @@ 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__
-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 check_handler
-from .handlers import extract_handler
-from .handlers import load_handler
-from .handlers import pipeline_handler
-from .handlers import render_handler
-from .handlers import run_handler
-from .handlers import transform_handler
-from .handlers import validate_handler
+from . import handlers
+from .commands import app
+from .constants import CLI_DESCRIPTION
+from .constants import CLI_EPILOG
+from .constants import DATA_CONNECTORS
+from .constants import FILE_FORMATS
+from .constants import PROJECT_URL
+from .options import add_argparse_format_options
+from .types import DataConnectorContext
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -43,31 +38,6 @@ __all__ = [
 ]
 
 
-# SECTION: TYPE ALIASES ===================================================== #
-
-
-type FormatContext = Literal['source', 'target']
-
-
-# SECTION: INTERNAL CLASSES ================================================= #
-
-
-class _FormatAction(argparse.Action):
-    """
-    Argparse action that records when ``--source-format`` or
-    ``--target-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 =============================================== #
 
 
@@ -122,7 +92,7 @@ def _add_config_option(
 def _add_format_options(
     parser: argparse.ArgumentParser,
     *,
-    context: FormatContext,
+    context: DataConnectorContext,
 ) -> None:
     """
     Attach shared ``--source-format`` or ``--target-format`` options to
@@ -132,63 +102,11 @@ def _add_format_options(
     ----------
     parser : argparse.ArgumentParser
         Parser to augment.
-    context : FormatContext
+    context : DataConnectorContext
         Context for the format option: either ``'source'`` or ``'target'``
     """
     parser.set_defaults(_format_explicit=False)
-    parser.add_argument(
-        '--source-format',
-        choices=list(FileFormat.choices()),
-        default='json',
-        action=_FormatAction,
-        help=(
-            f'Format of the {context}. Overrides filename-based inference '
-            'when provided.'
-        ),
-    )
-    parser.add_argument(
-        '--target-format',
-        choices=list(FileFormat.choices()),
-        default='json',
-        action=_FormatAction,
-        help=(
-            f'Format of the {context}. Overrides filename-based inference '
-            'when provided.'
-        ),
-    )
-
-
-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 > out.json',
-            '    etlplus validate in.json --rules \'{"required": ["id"]}\'',
-            (
-                '    etlplus transform --from file in.csv --operations '
-                '\'{"select": ["id"]}\' --to file -o out.json'
-            ),
-            '    etlplus extract in.csv | etlplus load --to file out.json',
-            '',
-            '    Override format inference when extensions are misleading:',
-            '',
-            '    etlplus extract data.txt --source-format csv',
-            '    etlplus load payload.bin --target-format json',
-        ],
-    )
-
-
-def _cli_epilog() -> str:
-    return '\n'.join(
-        [
-            'Tip:',
-            '    --source-format and --target-format override format '
-            'inference based on filename extensions when needed.',
-        ],
-    )
+    add_argparse_format_options(parser, context=context)
 
 
 def _emit_context_help(
@@ -293,8 +211,8 @@ def create_parser() -> argparse.ArgumentParser:
 
     parser = argparse.ArgumentParser(
         prog='etlplus',
-        description=_cli_description(),
-        epilog=_cli_epilog(),
+        description=CLI_DESCRIPTION,
+        epilog=CLI_EPILOG,
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
 
@@ -305,6 +223,25 @@ def create_parser() -> argparse.ArgumentParser:
         version=f'%(prog)s {__version__}',
     )
 
+    parser.add_argument(
+        '--pretty',
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help='Pretty-print JSON output (default: pretty).',
+    )
+    parser.add_argument(
+        '--quiet',
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help='Suppress warnings and non-essential output.',
+    )
+    parser.add_argument(
+        '--verbose',
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help='Emit extra diagnostics to stderr.',
+    )
+
     subparsers = parser.add_subparsers(
         dest='command',
         help='Available commands',
@@ -318,7 +255,7 @@ def create_parser() -> argparse.ArgumentParser:
     )
     extract_parser.add_argument(
         'source_type',
-        choices=list(DataConnectorType.choices()),
+        choices=sorted(DATA_CONNECTORS),
         help='Type of source to extract from',
     )
     extract_parser.add_argument(
@@ -329,7 +266,7 @@ def create_parser() -> argparse.ArgumentParser:
         ),
     )
     _add_format_options(extract_parser, context='source')
-    extract_parser.set_defaults(func=extract_handler)
+    extract_parser.set_defaults(func=handlers.extract_handler)
 
     validate_parser = subparsers.add_parser(
         'validate',
@@ -346,7 +283,7 @@ def create_parser() -> argparse.ArgumentParser:
         default={},
         help='Validation rules as JSON string',
     )
-    validate_parser.set_defaults(func=validate_handler)
+    validate_parser.set_defaults(func=handlers.validate_handler)
 
     transform_parser = subparsers.add_parser(
         'transform',
@@ -366,18 +303,18 @@ def create_parser() -> argparse.ArgumentParser:
     transform_parser.add_argument(
         '--from',
         dest='from_',
-        choices=list(DataConnectorType.choices()),
+        choices=sorted(DATA_CONNECTORS),
         help='Override the inferred source type (file, database, api).',
     )
     transform_parser.add_argument(
         '--to',
         dest='to',
-        choices=list(DataConnectorType.choices()),
+        choices=sorted(DATA_CONNECTORS),
         help='Override the inferred target type (file, database, api).',
     )
     transform_parser.add_argument(
         '--source-format',
-        choices=list(FileFormat.choices()),
+        choices=sorted(FILE_FORMATS),
         dest='source_format',
         help=(
             'Input payload format when SOURCE is - or a literal payload. '
@@ -387,14 +324,14 @@ def create_parser() -> argparse.ArgumentParser:
     transform_parser.add_argument(
         '--target-format',
         dest='target_format',
-        choices=list(FileFormat.choices()),
+        choices=sorted(FILE_FORMATS),
         help=(
             'Output payload format '
             'when writing to stdout or non-file targets. '
             'File targets infer format from the extension.'
         ),
     )
-    transform_parser.set_defaults(func=transform_handler)
+    transform_parser.set_defaults(func=handlers.transform_handler)
 
     load_parser = subparsers.add_parser(
         'load',
@@ -407,7 +344,7 @@ def create_parser() -> argparse.ArgumentParser:
     )
     load_parser.add_argument(
         'target_type',
-        choices=list(DataConnectorType.choices()),
+        choices=sorted(DATA_CONNECTORS),
         help='Type of target to load to',
     )
     load_parser.add_argument(
@@ -418,29 +355,7 @@ def create_parser() -> argparse.ArgumentParser:
         ),
     )
     _add_format_options(load_parser, context='target')
-    load_parser.set_defaults(func=load_handler)
-
-    pipe_parser = subparsers.add_parser(
-        'pipeline',
-        help=(
-            'DEPRECATED: use "list" (for summary/jobs) or "run" (to execute); '
-            'see '
-            f'{PROJECT_URL}/blob/main/docs/pipeline-guide.md'
-        ),
-        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
-    )
-    _add_config_option(pipe_parser)
-    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=pipeline_handler)
+    load_parser.set_defaults(func=handlers.load_handler)
 
     render_parser = subparsers.add_parser(
         'render',
@@ -476,7 +391,7 @@ def create_parser() -> argparse.ArgumentParser:
             'Explicit path to a Jinja template file (overrides template key).'
         ),
     )
-    render_parser.set_defaults(func=render_handler)
+    render_parser.set_defaults(func=handlers.render_handler)
 
     check_parser = subparsers.add_parser(
         'check',
@@ -516,7 +431,7 @@ def create_parser() -> argparse.ArgumentParser:
         name='transforms',
         help_text='List data transforms',
     )
-    check_parser.set_defaults(func=check_handler)
+    check_parser.set_defaults(func=handlers.check_handler)
 
     run_parser = subparsers.add_parser(
         'run',
@@ -537,7 +452,7 @@ def create_parser() -> argparse.ArgumentParser:
         '--pipeline',
         help='Name of the pipeline to run',
     )
-    run_parser.set_defaults(func=run_handler)
+    run_parser.set_defaults(func=handlers.run_handler)
 
     return parser