etlplus 0.4.6__py3-none-any.whl → 0.7.0__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,13 +24,14 @@ from ..enums import FileFormat
 from ..utils import json_type
 from .app import PROJECT_URL
 from .app import app
-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
+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
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -68,6 +71,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 +158,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 +191,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 ======================================================== #
 
 
@@ -239,7 +329,7 @@ def create_parser() -> argparse.ArgumentParser:
         ),
     )
     _add_format_options(extract_parser, context='source')
-    extract_parser.set_defaults(func=cmd_extract)
+    extract_parser.set_defaults(func=extract_handler)
 
     validate_parser = subparsers.add_parser(
         'validate',
@@ -256,7 +346,7 @@ def create_parser() -> argparse.ArgumentParser:
         default={},
         help='Validation rules as JSON string',
     )
-    validate_parser.set_defaults(func=cmd_validate)
+    validate_parser.set_defaults(func=validate_handler)
 
     transform_parser = subparsers.add_parser(
         'transform',
@@ -304,7 +394,7 @@ def create_parser() -> argparse.ArgumentParser:
             'File targets infer format from the extension.'
         ),
     )
-    transform_parser.set_defaults(func=cmd_transform)
+    transform_parser.set_defaults(func=transform_handler)
 
     load_parser = subparsers.add_parser(
         'load',
@@ -328,13 +418,14 @@ def create_parser() -> argparse.ArgumentParser:
         ),
     )
     _add_format_options(load_parser, context='target')
-    load_parser.set_defaults(func=cmd_load)
+    load_parser.set_defaults(func=load_handler)
 
     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,
     )
@@ -349,35 +440,83 @@ def create_parser() -> argparse.ArgumentParser:
         metavar='JOB',
         help='Run a specific job by name',
     )
-    pipe_parser.set_defaults(func=cmd_pipeline)
+    pipe_parser.set_defaults(func=pipeline_handler)
+
+    render_parser = subparsers.add_parser(
+        'render',
+        help='Render SQL DDL from table schema specs',
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    render_parser.add_argument(
+        '--config',
+        help='Pipeline YAML containing table_schemas',
+    )
+    render_parser.add_argument(
+        '-o',
+        '--output',
+        help='Write SQL to this path (stdout when omitted)',
+    )
+    render_parser.add_argument(
+        '--spec',
+        help='Standalone table spec file (.yml/.yaml/.json)',
+    )
+    render_parser.add_argument(
+        '--table',
+        help='Render only the table matching this name',
+    )
+    render_parser.add_argument(
+        '--template',
+        default='ddl',
+        help='Template key (ddl/view) or path to a Jinja template file',
+    )
+    render_parser.add_argument(
+        '--template-path',
+        dest='template_path',
+        help=(
+            'Explicit path to a Jinja template file (overrides template key).'
+        ),
+    )
+    render_parser.set_defaults(func=render_handler)
 
-    list_parser = subparsers.add_parser(
-        'list',
-        help='List ETL pipeline metadata',
+    check_parser = subparsers.add_parser(
+        'check',
+        help='Inspect ETL pipeline metadata',
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
     )
-    _add_config_option(list_parser)
+    _add_config_option(check_parser)
+    _add_boolean_flag(
+        check_parser,
+        name='jobs',
+        help_text='List ETL jobs',
+    )
     _add_boolean_flag(
-        list_parser,
+        check_parser,
         name='pipelines',
         help_text='List ETL pipelines',
     )
     _add_boolean_flag(
-        list_parser,
+        check_parser,
         name='sources',
         help_text='List data sources',
     )
     _add_boolean_flag(
-        list_parser,
+        check_parser,
+        name='summary',
+        help_text=(
+            'Show pipeline summary (name, version, sources, targets, jobs)'
+        ),
+    )
+    _add_boolean_flag(
+        check_parser,
         name='targets',
         help_text='List data targets',
     )
     _add_boolean_flag(
-        list_parser,
+        check_parser,
         name='transforms',
         help_text='List data transforms',
     )
-    list_parser.set_defaults(func=cmd_list)
+    check_parser.set_defaults(func=check_handler)
 
     run_parser = subparsers.add_parser(
         'run',
@@ -398,7 +537,7 @@ def create_parser() -> argparse.ArgumentParser:
         '--pipeline',
         help='Name of the pipeline to run',
     )
-    run_parser.set_defaults(func=cmd_run)
+    run_parser.set_defaults(func=run_handler)
 
     return parser
 
@@ -422,6 +561,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 +584,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/config/pipeline.py

@@ -190,6 +190,8 @@ class PipelineConfig:
         Target connectors, parsed tolerantly.
     jobs : list[JobConfig]
         Job orchestration definitions.
+    table_schemas : list[dict[str, Any]]
+        Optional DDL-style table specifications used by the render command.
     """
 
     # -- Attributes -- #
@@ -208,6 +210,7 @@ class PipelineConfig:
     transforms: dict[str, dict[str, Any]] = field(default_factory=dict)
     targets: list[Connector] = field(default_factory=list)
     jobs: list[JobConfig] = field(default_factory=list)
+    table_schemas: list[dict[str, Any]] = field(default_factory=list)
 
     # -- Class Methods -- #
 
@@ -312,6 +315,13 @@ class PipelineConfig:
         # Jobs
         jobs = _build_jobs(raw)
 
+        # Table schemas (optional, tolerant pass-through structures).
+        table_schemas: list[dict[str, Any]] = []
+        for entry in raw.get('table_schemas', []) or []:
+            spec = maybe_mapping(entry)
+            if spec is not None:
+                table_schemas.append(dict(spec))
+
         return cls(
             name=name,
             version=version,
@@ -325,4 +335,5 @@ class PipelineConfig:
             transforms=transforms,
             targets=targets,
             jobs=jobs,
+            table_schemas=table_schemas,
         )

etlplus/database/__init__.py

@@ -0,0 +1,42 @@
+"""
+:mod:`etlplus.database` package.
+
+Database utilities for:
+- DDL rendering and schema management.
+- Schema parsing from configuration files.
+- Dynamic ORM generation.
+- Database engine/session management.
+"""
+
+from __future__ import annotations
+
+from .ddl import load_table_spec
+from .ddl import render_table_sql
+from .ddl import render_tables
+from .ddl import render_tables_to_string
+from .engine import engine
+from .engine import load_database_url_from_config
+from .engine import make_engine
+from .engine import session
+from .orm import build_models
+from .orm import load_and_build_models
+from .schema import load_table_specs
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    # Functions
+    'build_models',
+    'load_and_build_models',
+    'load_database_url_from_config',
+    'load_table_spec',
+    'load_table_specs',
+    'make_engine',
+    'render_table_sql',
+    'render_tables',
+    'render_tables_to_string',
+    # Singletons
+    'engine',
+    'session',
+]