etlplus 0.3.5__tar.gz → 0.3.17__tar.gz

etlplus-0.3.17/.coveragerc

@@ -0,0 +1,21 @@
+# .coveragerc
+# ETLPlus
+#
+# Copyright © 2025 Dagitali LLC. All rights reserved.
+#
+# An optional pytest-cov configuration file. Limits coverage measurement to the
+# ETLPlus package and ignore test modules.
+#
+# See:
+# 1. https://pytest-cov.readthedocs.io/en/latest/config.html
+
+[run]
+source = etlplus
+branch = true
+omit =
+    tests/*
+    */tests/*
+
+[report]
+skip_covered = true
+show_missing = true

etlplus-0.3.17/.github/actions/python-bootstrap/action.yml

@@ -0,0 +1,42 @@
+# action.yml
+# ETLPlus
+#
+# Copyright © 2025 Dagitali LLC. All rights reserved.
+#
+# A GitHub Actions action to set up Python and install Python package
+# dependencies.
+#
+# Notes
+# - External GitHub Actions action references are each pinned to specific SHA
+#   to limit supply-chain risk.
+
+---
+
+name: Setup Python and Install Dependencies
+
+description: >-
+  Sets up the requested Python runtime, upgrades pip, and installs the provided
+  dependency list to keep workflow jobs consistent.
+
+inputs:
+  python-version:
+    description: Python version to install via actions/setup-python
+    required: true
+  python-bootstrap:
+    description: Arguments passed to "pip install"
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # Pinned v5
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Upgrade pip
+      shell: bash
+      run: python -m pip install --upgrade pip
+
+    - name: Install dependencies
+      shell: bash
+      run: pip install ${{ inputs.python-bootstrap }}

etlplus-0.3.17/.github/workflows/ci.yml

@@ -0,0 +1,160 @@
+# ci.yml
+# ETLPlus
+#
+# Copyright © 2025 Dagitali LLC. All rights reserved.
+#
+# A GitHub Actions workflow configuration file for Continuous Integration (CI).
+#
+# Notes
+# - The workflow includes jobs for linting, testing, building distributions,
+#   and publishing releases to GitHub and PyPI.
+# - The workflow is hardened by removing global permissions and setting per-job
+#   scopes.
+# - To harden workflow security, global permissions are absent, and per-job
+#   permissions are set as needed.
+# - External GitHub Actions action references are each pinned to specific SHA
+#   to limit supply-chain risk.
+
+---
+
+name: CI
+
+on:
+  push:
+    branches:
+      # GitFlow branches
+      - main
+      - develop
+      - '**/feature/**'
+      - '**/bugfix/**'
+      - '**/release/**'
+      - '**/hotfix/**'
+
+      # Extended branches
+      - '**/chore/**'
+      - '**/ci/**'
+      - '**/docs/**'
+    tags: [ 'v*.*.*' ]
+  pull_request:
+    branches: [ main, develop ]
+
+permissions: {}
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    strategy: &python-matrix
+      matrix:
+        python-version: ['3.13', '3.14']
+    permissions: &permissions_read
+      contents: read
+    steps:
+      - &checkout_step
+        name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # Pinned v4
+        with:
+          fetch-depth: 0
+      - uses: ./.github/actions/python-bootstrap
+        with:
+          python-version: ${{ matrix.python-version }}
+          python-bootstrap: ".[dev]"
+      - name: Ruff check
+        run: |
+          ruff version
+          ruff check .
+          ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy: *python-matrix
+    permissions: *permissions_read
+    steps:
+      - *checkout_step
+      - uses: ./.github/actions/python-bootstrap
+        with:
+          python-version: ${{ matrix.python-version }}
+          python-bootstrap: "-e .[dev,yaml]"
+      - name: Run tests (with coverage)
+        run: |
+          pytest -q \
+            --cov \
+            --cov-branch \
+            --cov-config=.coveragerc \
+            --cov-report=term-missing \
+            --cov-report=xml \
+            tests/
+
+      - name: Upload coverage reports to Codecov
+        if: matrix.python-version == '3.13'
+        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de  # Pinned v5.5.2
+        with:
+          fail_ci_if_error: true
+          files: coverage.xml
+          flags: unit
+          name: etlplus
+          token: ${{ secrets.CODECOV_TOKEN }}  # Omit for public repo
+          verbose: true
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    if: &release_tag_condition >
+      startsWith(github.ref, 'refs/tags/v') ||
+      startsWith(github.ref, 'refs/tags/rc')
+    needs: [lint, test]
+    permissions: *permissions_read
+    steps:
+      - *checkout_step
+      - uses: ./.github/actions/python-bootstrap
+        with:
+          python-version: '3.13'
+          python-bootstrap: build
+      - name: Build distributions
+        run: |
+          python -m build
+      - name: Upload distributions
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # Pinned v4
+        with:
+          name: dist-artifacts
+          path: dist/*
+          if-no-files-found: error
+
+  release:
+    name: Publish GitHub Release
+    runs-on: ubuntu-latest
+    if: *release_tag_condition
+    needs: build
+    permissions:
+      contents: write
+    steps:
+      - *checkout_step
+      - &download_dist_step
+        name: Download distributions
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # Pinned v4
+        with:
+          name: dist-artifacts
+          path: dist
+      - name: Publish GitHub release
+        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b  # Pinned v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    if: *release_tag_condition
+    needs: build
+    permissions:
+      contents: read
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/etlplus/
+    steps:
+      - *checkout_step
+      - *download_dist_step
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e  # Pinned v1
+        with:
+          verbose: true

{etlplus-0.3.5 → etlplus-0.3.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.3.5
+Version: 0.3.17
 Summary: A Swiss Army knife for simple ETL operations
 Home-page: https://github.com/Dagitali/ETLPlus
 Author: ETLPlus Team

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.3.5
+Version: 0.3.17
 Summary: A Swiss Army knife for simple ETL operations
 Home-page: https://github.com/Dagitali/ETLPlus
 Author: ETLPlus Team

{etlplus-0.3.5 → etlplus-0.3.17}/etlplus.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+.coveragerc
 .editorconfig
 .gitattributes
 .gitignore
@@ -13,6 +14,7 @@ REFERENCES.md
 pyproject.toml
 pytest.ini
 setup.py
+.github/actions/python-bootstrap/action.yml
 .github/workflows/ci.yml
 docs/pipeline-guide.md
 docs/snippets/installation_version.md
@@ -85,9 +87,13 @@ tests/integration/test_i_run_profile_pagination_defaults.py
 tests/integration/test_i_run_profile_rate_limit_defaults.py
 tests/unit/conftest.py
 tests/unit/test_u_cli.py
+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_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

etlplus-0.3.17/tests/conftest.py

@@ -0,0 +1,210 @@
+"""
+:mod:`tests.conftest` module.
+
+Global pytest fixtures shared across unit, integration, and end-to-end tests.
+
+Notes
+-----
+- Provides CLI helpers so tests no longer need to monkeypatch ``sys.argv``
+    inline.
+- Supplies JSON file factories that rely on ``tmp_path`` for automatic
+    cleanup.
+- Keeps docstrings NumPy-formatted to satisfy numpydoc linting.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+from typing import Protocol
+
+import pytest
+from requests import PreparedRequest  # type: ignore[import]
+
+from etlplus.cli import main
+
+# SECTION: HELPERS ========================================================== #
+
+
+def _coerce_cli_args(
+    cli_args: tuple[str | Sequence[str], ...],
+) -> tuple[str, ...]:
+    """
+    Normalize CLI arguments into a ``tuple[str, ...]``.
+
+    Parameters
+    ----------
+    cli_args : tuple[str | Sequence[str], ...]
+        Arguments provided to ``cli_runner``/``cli_invoke``.
+
+    Returns
+    -------
+    tuple[str, ...]
+        Normalized argument tuple safe to concatenate with ``sys.argv``.
+    """
+    if (
+        len(cli_args) == 1
+        and isinstance(cli_args[0], Sequence)
+        and not isinstance(cli_args[0], (str, bytes))
+    ):
+        return tuple(str(part) for part in cli_args[0])
+    return tuple(str(part) for part in cli_args)
+
+
+class CliInvoke(Protocol):
+    """Protocol describing the :func:`cli_invoke` fixture."""
+
+    def __call__(
+        self,
+        *cli_args: str | Sequence[str],
+    ) -> tuple[int, str, str]: ...
+
+
+class CliRunner(Protocol):
+    """Protocol describing the ``cli_runner`` fixture."""
+
+    def __call__(self, *cli_args: str | Sequence[str]) -> int: ...
+
+
+class JsonFactory(Protocol):
+    """Protocol describing the :func:`json_file_factory` fixture."""
+
+    def __call__(
+        self,
+        payload: Any,
+        *,
+        filename: str | None = None,
+        ensure_ascii: bool = False,
+    ) -> Path: ...
+
+
+class RequestFactory(Protocol):
+    """Protocol describing prepared-request factories."""
+
+    def __call__(
+        self,
+        url: str | None = None,
+    ) -> PreparedRequest: ...
+
+
+# SECTION: FIXTURES ========================================================= #
+
+
+@pytest.fixture(name='base_url')
+def base_url_fixture() -> str:
+    """Return the canonical base URL shared across tests."""
+
+    return 'https://api.example.com'
+
+
+@pytest.fixture(name='json_file_factory')
+def json_file_factory_fixture(
+    tmp_path: Path,
+) -> JsonFactory:
+    """
+    Create JSON files under ``tmp_path`` and return their paths.
+
+    Parameters
+    ----------
+    tmp_path : Path
+        Temporary directory managed by pytest.
+
+    Returns
+    -------
+    JsonFactory
+        Factory that persists the provided payload as JSON and returns the
+        resulting path.
+
+    Examples
+    --------
+    >>> path = json_file_factory({'name': 'Ada'})
+    >>> path.exists()
+    True
+    """
+
+    def _create(
+        payload: Any,
+        *,
+        filename: str | None = None,
+        ensure_ascii: bool = False,
+    ) -> Path:
+        target = tmp_path / (filename or 'payload.json')
+        data = (
+            payload
+            if isinstance(payload, str)
+            else json.dumps(payload, indent=2, ensure_ascii=ensure_ascii)
+        )
+        target.write_text(data)
+        return target
+
+    return _create
+
+
+@pytest.fixture(name='cli_runner')
+def cli_runner_fixture(
+    monkeypatch: pytest.MonkeyPatch,
+) -> CliRunner:
+    """
+    Invoke ``etlplus`` CLI commands with isolated ``sys.argv`` state.
+
+    Parameters
+    ----------
+    monkeypatch : pytest.MonkeyPatch
+        Built-in pytest fixture used to patch ``sys.argv``.
+
+    Returns
+    -------
+    CliRunner
+        Helper that accepts CLI arguments, runs :func:`etlplus.cli.main`, and
+        returns the exit code.
+
+    Examples
+    --------
+    >>> cli_runner(('extract', 'file', 'data.json'))
+    0
+    """
+
+    def _run(*cli_args: str | Sequence[str]) -> int:
+        args = _coerce_cli_args(cli_args)
+        monkeypatch.setattr(sys, 'argv', ['etlplus', *args])
+        return main()
+
+    return _run
+
+
+@pytest.fixture
+def cli_invoke(
+    cli_runner: CliRunner,
+    capsys: pytest.CaptureFixture[str],
+) -> CliInvoke:
+    """
+    Run CLI commands and return exit code, stdout, and stderr.
+
+    Parameters
+    ----------
+    cli_runner : CliRunner
+        Helper fixture defined above.
+    capsys : pytest.CaptureFixture[str]
+        Pytest fixture for capturing stdout/stderr.
+
+    Returns
+    -------
+    CliInvoke
+        Helper that yields ``(exit_code, stdout, stderr)`` tuples.
+
+    Examples
+    --------
+    >>> code, out, err = cli_invoke(('extract', 'file', 'data.json'))
+    >>> code
+    0
+    """
+
+    def _invoke(*cli_args: str | Sequence[str]) -> tuple[int, str, str]:
+        exit_code = cli_runner(*cli_args)
+        captured = capsys.readouterr()
+        return exit_code, captured.out, captured.err
+
+    return _invoke

{etlplus-0.3.5 → etlplus-0.3.17}/tests/integration/conftest.py

@@ -11,6 +11,7 @@ Notes
 from __future__ import annotations
 
 import importlib
+import json
 import pathlib
 from collections.abc import Callable
 from typing import Any
@@ -34,6 +35,12 @@ from etlplus.config import PipelineConfig
 # SECTION: HELPERS ========================================================== #
 
 
+pytestmark = pytest.mark.integration
+
+
+# SECTION: HELPERS ========================================================== #
+
+
 # Directory-level marker for integration tests.
 pytestmark = pytest.mark.integration
 
@@ -55,8 +62,8 @@ class FakeEndpointClientProtocol(Protocol):
 # SECTION: FIXTURES ========================================================= #
 
 
-@pytest.fixture
-def capture_load_to_api(
+@pytest.fixture(name='capture_load_to_api')
+def capture_load_to_api_fixture(
     monkeypatch: pytest.MonkeyPatch,
 ) -> dict[str, Any]:
     """
@@ -112,8 +119,8 @@ def capture_load_to_api(
     return seen
 
 
-@pytest.fixture
-def fake_endpoint_client() -> tuple[
+@pytest.fixture(name='fake_endpoint_client')
+def fake_endpoint_client_fixture() -> tuple[
     type[FakeEndpointClientProtocol],
     list[FakeEndpointClientProtocol],
 ]:  # noqa: ANN201
@@ -170,9 +177,83 @@ def fake_endpoint_client() -> tuple[
     return FakeClient, created
 
 
-@pytest.fixture
-def pipeline_cfg_factory(
+@pytest.fixture(name='file_to_api_pipeline_factory')
+def file_to_api_pipeline_factory_fixture(
+    tmp_path: pathlib.Path,
+    base_url: str,
+) -> Callable[..., PipelineConfig]:
+    """Build a pipeline wiring a JSON file source to an API target."""
+
+    def _make(
+        *,
+        payload: Any | None = None,
+        base_url: str = base_url,
+        base_path: str | None = '/v1',
+        endpoint_path: str = '/ingest',
+        endpoint_name: str = 'ingest',
+        method: str = 'post',
+        headers: dict[str, str] | None = None,
+        job_name: str = 'send',
+        target_name: str = 'ingest_out',
+    ) -> PipelineConfig:
+        source_path = tmp_path / f'{job_name}_input.json'
+        effective_payload = payload if payload is not None else {'ok': True}
+        text = (
+            effective_payload
+            if isinstance(effective_payload, str)
+            else json.dumps(effective_payload)
+        )
+        source_path.write_text(text, encoding='utf-8')
+
+        profile = ApiProfileConfig(
+            base_url=base_url,
+            headers={},
+            base_path=base_path or '',
+            auth={},
+            rate_limit_defaults=None,
+            pagination_defaults=None,
+        )
+        api = ApiConfig(
+            base_url=base_url,
+            profiles={'default': profile},
+            endpoints={endpoint_name: EndpointConfig(path=endpoint_path)},
+        )
+
+        src = ConnectorFile(
+            name='file_src',
+            type='file',
+            format='json',
+            path=str(source_path),
+        )
+        tgt = ConnectorApi(
+            name=target_name,
+            type='api',
+            api='svc',
+            endpoint=endpoint_name,
+            method=method,
+            headers=headers or {},
+        )
+
+        return PipelineConfig(
+            apis={'svc': api},
+            sources=[src],
+            targets=[tgt],
+            jobs=[
+                JobConfig(
+                    name=job_name,
+                    extract=ExtractRef(source='file_src'),
+                    load=LoadRef(target=target_name),
+                ),
+            ],
+        )
+
+    return _make
+
+
+@pytest.fixture(name='pipeline_cfg_factory')
+def pipeline_cfg_factory_fixture(
     tmp_path: pathlib.Path,
+    base_url: str,
 ) -> Callable[..., PipelineConfig]:
     """
     Factory to build a minimal PipelineConfig for runner tests.
@@ -185,6 +266,8 @@ def pipeline_cfg_factory(
     ----------
     tmp_path : pathlib.Path
         The pytest temporary path fixture.
+    base_url : str
+        Common base URL used across tests.
 
     Returns
     -------
@@ -196,9 +279,10 @@ def pipeline_cfg_factory(
         *,
         pagination_defaults: PaginationConfig | None = None,
         rate_limit_defaults: RateLimitConfig | None = None,
+        extract_options: dict[str, Any] | None = None,
     ) -> PipelineConfig:
         prof = ApiProfileConfig(
-            base_url='https://api.example.com',
+            base_url=base_url,
             headers={},
             base_path='/v1',
             auth={},
@@ -219,24 +303,29 @@ def pipeline_cfg_factory(
             format='json',
             path=str(out_path),
         )
+        job = JobConfig(
+            name='job',
+            extract=ExtractRef(source='s'),
+            load=LoadRef(target='t'),
+        )
+        if extract_options is not None:
+            if job.extract is None:
+                msg = 'job.extract is None; cannot set options'
+                raise ValueError(msg)
+            job.extract.options = extract_options
+
         return PipelineConfig(
             apis={'svc': api},
             sources=[src],
             targets=[tgt],
-            jobs=[
-                JobConfig(
-                    name='job',
-                    extract=ExtractRef(source='s'),
-                    load=LoadRef(target='t'),
-                ),
-            ],
+            jobs=[job],
         )
 
     return _make
 
 
-@pytest.fixture
-def run_patched(
+@pytest.fixture(name='run_patched')
+def run_patched_fixture(
     monkeypatch: pytest.MonkeyPatch,
 ) -> Callable[..., dict[str, Any]]:
     """