etlplus 0.3.17__tar.gz → 0.4.0__tar.gz

{etlplus-0.3.17 → etlplus-0.4.0}/Makefile

@@ -253,7 +253,7 @@ venv: ## Create the virtual environment (at $(VENV_DIR))
 	else \
 		$(call ECHO_INFO, "Using existing venv: $(VENV_DIR)"); \
 	fi
-	@$(PYTHON) -m pip install --upgrade pip setuptool wheel >/dev/null
+	@$(PYTHON) -m pip install --upgrade pip setuptools wheel >/dev/null
 	@$(call ECHO_OK,"venv ready")
 
 ##@ CI

{etlplus-0.3.17/etlplus.egg-info → etlplus-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.3.17
+Version: 0.4.0
 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.17 → etlplus-0.4.0}/etlplus/cli.py

@@ -26,6 +26,8 @@ from typing import Any
 from typing import Literal
 from typing import cast
 
+import typer
+
 from . import __version__
 from .config import PipelineConfig
 from .config import load_pipeline_config
@@ -90,6 +92,9 @@ PROJECT_URL = 'https://github.com/Dagitali/ETLPlus'
 _FORMAT_ERROR_STATES = {'error', 'fail', 'strict'}
 _FORMAT_SILENT_STATES = {'ignore', 'silent'}
 
+_SOURCE_CHOICES = set(DataConnectorType.choices())
+_FORMAT_CHOICES = set(FileFormat.choices())
+
 
 # SECTION: TYPE ALIASES ===================================================== #
 
@@ -292,6 +297,12 @@ def _materialize_csv_payload(
     return _read_csv_rows(path)
 
 
+def _ns(**kwargs: object) -> argparse.Namespace:
+    """Create an :class:`argparse.Namespace` for legacy command handlers."""
+
+    return argparse.Namespace(**kwargs)
+
+
 def _pipeline_summary(
     cfg: PipelineConfig,
 ) -> dict[str, Any]:
@@ -341,6 +352,18 @@ def _read_csv_rows(
         return [dict(row) for row in reader]
 
 
+def _validate_choice(value: str, choices: set[str], *, label: str) -> str:
+    """Validate a string against allowed choices for nice CLI errors."""
+
+    v = (value or '').strip()
+    if v in choices:
+        return v
+    allowed = ', '.join(sorted(choices))
+    raise typer.BadParameter(
+        f"Invalid {label} '{value}'. Choose from: {allowed}",
+    )
+
+
 def _write_json_output(
     data: Any,
     output_path: str | None,
@@ -838,31 +861,326 @@ def main(
     int
         Zero on success, non-zero on error.
 
+    Raises
+    ------
+    SystemExit
+        Re-raises SystemExit exceptions to preserve exit codes.
+
     Notes
     -----
-    This function prints results to stdout and errors to stderr.
+    This function uses Typer (Click) for parsing/dispatch, but preserves the
+    existing `cmd_*` handlers by adapting parsed arguments into an
+    :class:`argparse.Namespace`.
     """
-    parser = create_parser()
-    args = parser.parse_args(argv)
-
-    if not args.command:
-        parser.print_help()
-        return 0
+    argv = sys.argv[1:] if argv is None else argv
+    command = typer.main.get_command(app)
 
     try:
-        # Prefer argparse's dispatch to avoid duplicating logic.
-        func = getattr(args, 'func', None)
-        if callable(func):
-            return int(func(args))
+        result = command.main(
+            args=list(argv),
+            prog_name='etlplus',
+            standalone_mode=False,
+        )
+        return int(result or 0)
 
-        # Fallback: no subcommand function bound.
-        parser.print_help()
-        return 0
+    except typer.Exit as exc:
+        return int(exc.exit_code)
+
+    except typer.Abort:
+        return 1
 
     except KeyboardInterrupt:
         # 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
+
+
+# SECTION: TYPER APP ======================================================== #
+
+
+app = typer.Typer(
+    name='etlplus',
+    help='ETLPlus - A Swiss Army knife for simple ETL operations.',
+    add_completion=True,
+)
+
+
+@app.callback(invoke_without_command=True)
+def _root(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False,
+        '-V',
+        '--version',
+        is_eager=True,
+        help='Show the version and exit.',
+    ),
+) -> None:
+    """Root command callback to show help or version."""
+
+    if version:
+        typer.echo(f'etlplus {__version__}')
+        raise typer.Exit(0)
+
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit(0)
+
+
+@app.command('extract')
+def extract_cmd(
+    source_type: str = typer.Argument(
+        ...,
+        help='Type of source to extract from',
+    ),
+    source: str = typer.Argument(
+        ...,
+        help=(
+            'Source location '
+            '(file path, database connection string, or API URL)'
+        ),
+    ),
+    output: str | None = typer.Option(
+        None,
+        '-o',
+        '--output',
+        help='Output file to save extracted data (JSON format)',
+    ),
+    strict_format: bool = typer.Option(
+        False,
+        '--strict-format',
+        help=(
+            'Treat providing --format for file sources as an error '
+            '(overrides environment behavior)'
+        ),
+    ),
+    source_format: str | None = typer.Option(
+        None,
+        '--format',
+        help=(
+            'Format of the source when not a file. For file sources this '
+            'option is ignored and the format is inferred from the filename '
+            'extension.'
+        ),
+    ),
+) -> int:
+    """Typer front-end for :func:`cmd_extract`."""
+
+    source_type = _validate_choice(
+        source_type,
+        _SOURCE_CHOICES,
+        label='source_type',
+    )
+    if source_format is not None:
+        source_format = _validate_choice(
+            source_format,
+            _FORMAT_CHOICES,
+            label='format',
+        )
+
+    ns = _ns(
+        command='extract',
+        source_type=source_type,
+        source=source,
+        output=output,
+        strict_format=strict_format,
+        format=(source_format or 'json'),
+        _format_explicit=(source_format is not None),
+    )
+    return int(cmd_extract(ns))
+
+
+@app.command('validate')
+def validate_cmd(
+    source: str = typer.Argument(
+        ...,
+        help='Data source to validate (file path or JSON string)',
+    ),
+    rules: str = typer.Option(
+        '{}',
+        '--rules',
+        help='Validation rules as JSON string',
+    ),
+) -> int:
+    """Typer front-end for :func:`cmd_validate`."""
+
+    ns = _ns(command='validate', source=source, rules=json_type(rules))
+    return int(cmd_validate(ns))
+
+
+@app.command('transform')
+def transform_cmd(
+    source: str = typer.Argument(
+        ...,
+        help='Data source to transform (file path or JSON string)',
+    ),
+    operations: str = typer.Option(
+        '{}',
+        '--operations',
+        help='Transformation operations as JSON string',
+    ),
+    output: str | None = typer.Option(
+        None,
+        '-o',
+        '--output',
+        help='Output file to save transformed data',
+    ),
+) -> int:
+    """Typer front-end for :func:`cmd_transform`."""
+
+    ns = _ns(
+        command='transform',
+        source=source,
+        operations=json_type(operations),
+        output=output,
+    )
+    return int(cmd_transform(ns))
+
+
+@app.command('load')
+def load_cmd(
+    source: str = typer.Argument(
+        ...,
+        help='Data source to load (file path or JSON string)',
+    ),
+    target_type: str = typer.Argument(..., help='Type of target to load to'),
+    target: str = typer.Argument(
+        ...,
+        help=(
+            'Target location '
+            '(file path, database connection string, or API URL)'
+        ),
+    ),
+    strict_format: bool = typer.Option(
+        False,
+        '--strict-format',
+        help=(
+            'Treat providing --format for file targets as an error '
+            '(overrides environment behavior)'
+        ),
+    ),
+    target_format: str | None = typer.Option(
+        None,
+        '--format',
+        help=(
+            'Format of the target when not a file. For file targets this '
+            'option is ignored and the format is inferred from the filename '
+            'extension.'
+        ),
+    ),
+) -> int:
+    """Typer front-end for :func:`cmd_load`."""
+
+    target_type = _validate_choice(
+        target_type,
+        _SOURCE_CHOICES,
+        label='target_type',
+    )
+    if target_format is not None:
+        target_format = _validate_choice(
+            target_format,
+            _FORMAT_CHOICES,
+            label='format',
+        )
+
+    ns = _ns(
+        command='load',
+        source=source,
+        target_type=target_type,
+        target=target,
+        strict_format=strict_format,
+        format=(target_format or 'json'),
+        _format_explicit=(target_format is not None),
+    )
+    return int(cmd_load(ns))
+
+
+@app.command('pipeline')
+def pipeline_cmd(
+    config: str = typer.Option(
+        ...,
+        '--config',
+        help='Path to pipeline YAML configuration file',
+    ),
+    list_: bool = typer.Option(
+        False,
+        '--list',
+        help='List available job names and exit',
+    ),
+    run_job: str | None = typer.Option(
+        None,
+        '--run',
+        metavar='JOB',
+        help='Run a specific job by name',
+    ),
+) -> int:
+    """Typer front-end for :func:`cmd_pipeline`."""
+
+    ns = _ns(command='pipeline', config=config, list=list_, run=run_job)
+    return int(cmd_pipeline(ns))
+
+
+@app.command('list')
+def list_cmd(
+    config: str = typer.Option(
+        ...,
+        '--config',
+        help='Path to pipeline YAML configuration file',
+    ),
+    pipelines: bool = typer.Option(
+        False,
+        '--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'),
+    transforms: bool = typer.Option(
+        False,
+        '--transforms',
+        help='List data transforms',
+    ),
+) -> int:
+    """Typer front-end for :func:`cmd_list`."""
+
+    ns = _ns(
+        command='list',
+        config=config,
+        pipelines=pipelines,
+        sources=sources,
+        targets=targets,
+        transforms=transforms,
+    )
+    return int(cmd_list(ns))
+
+
+@app.command('run')
+def run_cmd(
+    config: str = typer.Option(
+        ...,
+        '--config',
+        help='Path to pipeline YAML configuration file',
+    ),
+    job: str | None = typer.Option(
+        None,
+        '-j',
+        '--job',
+        help='Name of the job to run',
+    ),
+    pipeline: str | None = typer.Option(
+        None,
+        '-p',
+        '--pipeline',
+        help='Name of the pipeline to run',
+    ),
+) -> int:
+    """Typer front-end for :func:`cmd_run`."""
+
+    ns = _ns(command='run', config=config, job=job, pipeline=pipeline)
+    return int(cmd_run(ns))

{etlplus-0.3.17 → etlplus-0.4.0}/etlplus/transform.py

@@ -67,6 +67,18 @@ from .types import StepSpec
 from .types import StrPath
 from .utils import to_number
 
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'apply_aggregate',
+    'apply_filter',
+    'apply_map',
+    'apply_select',
+    'apply_sort',
+    'transform',
+]
+
 # SECTION: INTERNAL FUNCTIONS ============================================== #
 
 

{etlplus-0.3.17 → etlplus-0.4.0/etlplus.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.3.17
+Version: 0.4.0
 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.17 → etlplus-0.4.0}/etlplus.egg-info/SOURCES.txt

@@ -91,12 +91,14 @@ tests/unit/test_u_enums.py
 tests/unit/test_u_extract.py
 tests/unit/test_u_file.py
 tests/unit/test_u_load.py
+tests/unit/test_u_main.py
 tests/unit/test_u_mixins.py
 tests/unit/test_u_run.py
 tests/unit/test_u_run_helpers.py
 tests/unit/test_u_transform.py
 tests/unit/test_u_utils.py
 tests/unit/test_u_validate.py
+tests/unit/test_u_version.py
 tests/unit/api/conftest.py
 tests/unit/api/test_u_auth.py
 tests/unit/api/test_u_config.py
@@ -110,7 +112,10 @@ tests/unit/api/test_u_rate_limiter.py
 tests/unit/api/test_u_request_manager.py
 tests/unit/api/test_u_retry_manager.py
 tests/unit/api/test_u_transport.py
+tests/unit/api/test_u_types.py
+tests/unit/config/test_u_config_utils.py
 tests/unit/config/test_u_connector.py
+tests/unit/config/test_u_jobs.py
 tests/unit/config/test_u_pipeline.py
 tests/unit/validation/test_u_validation_utils.py
 tools/run_pipeline.py

{etlplus-0.3.17 → etlplus-0.4.0}/etlplus.egg-info/requires.txt

@@ -3,6 +3,7 @@ pyodbc>=5.3.0
 python-dotenv>=1.2.1
 pandas>=2.3.3
 requests>=2.32.5
+typer>=0.21.0
 
 [dev]
 black>=25.9.0

{etlplus-0.3.17 → etlplus-0.4.0}/pyproject.toml

@@ -28,6 +28,7 @@ dependencies = [
   "python-dotenv>=1.2.1",
   "pandas>=2.3.3",
   "requests>=2.32.5",
+  "typer>=0.21.0",
 ]
 
 [project.optional-dependencies]

{etlplus-0.3.17 → etlplus-0.4.0}/setup.py

@@ -43,10 +43,11 @@ setup(
     python_requires='>=3.13,<3.15',
     install_requires=[
         'jinja2>=3.1.6',
+        'pandas>=2.3.3',
         'pyodbc>=5.3.0',
         'python-dotenv>=1.2.1',
-        'pandas>=2.3.3',
         'requests>=2.32.5',
+        'typer>=0.21.0',
     ],
     extras_require={
         'dev': [

{etlplus-0.3.17 → etlplus-0.4.0}/tests/integration/test_i_cli.py

@@ -21,8 +21,8 @@ from typing import TYPE_CHECKING
 import pytest
 
 if TYPE_CHECKING:  # pragma: no cover - typing helpers only
-    from tests._typing import CliInvoke
-    from tests._typing import JsonFactory
+    from tests.conftest import CliInvoke
+    from tests.conftest import JsonFactory
 
 
 # SECTION: HELPERS ========================================================== #

{etlplus-0.3.17 → etlplus-0.4.0}/tests/unit/api/test_u_auth.py

@@ -1,7 +1,7 @@
 """
 :mod:`tests.unit.api.test_u_auth` module.
 
-Unit tests for ``etlplus.api.auth``.
+Unit tests for :mod:`etlplus.api.auth`.
 
 Notes
 -----

{etlplus-0.3.17 → etlplus-0.4.0}/tests/unit/api/test_u_endpoint_client.py

@@ -1,7 +1,7 @@
 """
 :mod:`tests.unit.api.test_u_endpoint_client` module.
 
-Unit tests for ``etlplus.api.endpoint_client``.
+Unit tests for :mod:`etlplus.api.endpoint_client`.
 
 Notes
 -----
@@ -41,6 +41,12 @@ pytestmark = pytest.mark.unit
 
 EXAMPLE_BASE_URL = 'https://example.test'
 
+type CursorConfigFactory = Callable[..., CursorPaginationConfigMap]
+type StubRequestManager = Callable[
+    [Sequence[dict[str, Any]]],
+    list[dict[str, Any]],
+]
+
 # Optional Hypothesis import with safe stubs when missing.
 try:  # pragma: no try
     from hypothesis import given  # type: ignore[import-not-found]
@@ -110,6 +116,7 @@ def _page_responder(
     Callable[..., list[dict[str, Any]]]
         Handler compatible with ``patch_request_once``.
     """
+    # pylint: disable=unused-argument
 
     def _handler(
         self: EndpointClient,
@@ -155,6 +162,7 @@ def _stub_request_manager(
     ValueError
         If ``responses`` is empty.
     """
+    # pylint: disable=unused-argument
 
     if not responses:
         msg = 'responses must contain at least one payload'
@@ -375,12 +383,9 @@ class TestCursorPagination:
     )
     def test_page_size_normalizes(
         self,
-        cursor_cfg: Callable[..., CursorPaginationConfigMap],
+        cursor_cfg: CursorConfigFactory,
         client_factory: Callable[..., EndpointClient],
-        stub_request_manager: Callable[
-            [Sequence[dict[str, Any]]],
-            list[dict[str, Any]],
-        ],
+        stub_request_manager: StubRequestManager,
         raw_page_size: Any,
         expected_limit: int,
     ) -> None:
@@ -389,12 +394,11 @@ class TestCursorPagination:
 
         Parameters
         ----------
-        cursor_cfg : Callable[..., CursorPaginationConfigMap]
+        cursor_cfg : CursorConfigFactory
             Factory for cursor pagination config.
         client_factory : Callable[..., EndpointClient]
             Factory fixture used to construct :class:`EndpointClient`.
-        stub_request_manager : Callable[[Sequence[dict[str, Any]]],
-                                       list[dict[str, Any]]]
+        stub_request_manager : StubRequestManager
             Fixture that patches the underlying :class:`RequestManager`.
         raw_page_size : Any
             Raw page size input.
@@ -473,6 +477,7 @@ class TestRequestOptionIntegration:
         client_factory: Callable[..., EndpointClient],
     ) -> None:
         """Paginated iterations override RequestOptions params per call."""
+        # pylint: disable=unused-argument
 
         client = client_factory(base_url=EXAMPLE_BASE_URL, endpoints={})
         observed: list[RequestOptions] = []
@@ -512,24 +517,20 @@ class TestRequestOptionIntegration:
 
     def test_adds_limit_and_advances_cursor(
         self,
-        cursor_cfg: Callable[..., CursorPaginationConfigMap],
+        cursor_cfg: CursorConfigFactory,
         client_factory: Callable[..., EndpointClient],
-        stub_request_manager: Callable[
-            [Sequence[dict[str, Any]]],
-            list[dict[str, Any]],
-        ],
+        stub_request_manager: StubRequestManager,
     ) -> None:
         """
         Test that limit is added and cursor advances correctly.
 
         Parameters
         ----------
-        cursor_cfg : Callable[..., CursorPaginationConfigMap]
+        cursor_cfg : CursorConfigFactory
             Factory for cursor pagination config.
         client_factory : Callable[..., EndpointClient]
             Factory fixture used to construct :class:`EndpointClient`.
-        stub_request_manager : Callable[[Sequence[dict[str, Any]]],
-                                       list[dict[str, Any]]]
+        stub_request_manager : StubRequestManager
             Fixture that patches :class:`RequestManager` responses.
         """
         calls = stub_request_manager(
@@ -561,7 +562,7 @@ class TestRequestOptionIntegration:
         self,
         base_url: str,
         patch_request_once: Callable[[Callable[..., Any]], Callable[..., Any]],
-        cursor_cfg: Callable[..., CursorPaginationConfigMap],
+        cursor_cfg: CursorConfigFactory,
         client_factory: Callable[..., EndpointClient],
     ) -> None:
         """
@@ -577,7 +578,7 @@ class TestRequestOptionIntegration:
             Common base URL used across tests.
         patch_request_once : Callable[[Callable[..., Any]], Callable[..., Any]]
             Helper that patches the request helper for deterministic failures.
-        cursor_cfg : Callable[..., CursorPaginationConfigMap]
+        cursor_cfg : CursorConfigFactory
             Factory for cursor pagination config.
         client_factory : Callable[..., EndpointClient]
             Factory fixture used to construct :class:`EndpointClient`.
@@ -700,7 +701,7 @@ class TestRequestOptionIntegration:
 
     def test_retry_backoff_sleeps(
         self,
-        cursor_cfg: Callable[..., CursorPaginationConfigMap],
+        cursor_cfg: CursorConfigFactory,
         capture_sleeps: list[float],
         jitter: Callable[[list[float]], list[float]],
         patch_request_once: Callable[[Callable[..., Any]], Callable[..., Any]],
@@ -713,7 +714,7 @@ class TestRequestOptionIntegration:
 
         Parameters
         ----------
-        cursor_cfg : Callable[..., CursorPaginationConfigMap]
+        cursor_cfg : CursorConfigFactory
             Factory for cursor pagination config.
         capture_sleeps : list[float]
             List to capture sleep durations.

{etlplus-0.3.17 → etlplus-0.4.0}/tests/unit/api/test_u_rate_limiter.py

@@ -48,7 +48,7 @@ def fixed_limiter_fixture() -> RateLimiter:
     return RateLimiter.fixed(0.25)
 
 
-# SECTION: TESTS =========================================================== #
+# SECTION: TESTS ============================================================ #
 
 
 @pytest.mark.unit