etlplus 0.3.10__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.10 → etlplus-0.3.17}/.github/actions/python-bootstrap/action.yml

@@ -5,6 +5,10 @@
 #
 # 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.
 
 ---
 
@@ -25,7 +29,7 @@ inputs:
 runs:
   using: composite
   steps:
-    - uses: actions/setup-python@v5
+    - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # Pinned v5
       with:
         python-version: ${{ inputs.python-version }}
 

{etlplus-0.3.10 → etlplus-0.3.17}/.github/workflows/ci.yml

@@ -4,6 +4,16 @@
 # 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.
 
 ---
 
@@ -28,9 +38,7 @@ on:
   pull_request:
     branches: [ main, develop ]
 
-permissions:
-  contents: read
-  id-token: write
+permissions: {}
 
 jobs:
   lint:
@@ -38,8 +46,12 @@ jobs:
     strategy: &python-matrix
       matrix:
         python-version: ['3.13', '3.14']
+    permissions: &permissions_read
+      contents: read
     steps:
-      - uses: actions/checkout@v4
+      - &checkout_step
+        name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # Pinned v4
         with:
           fetch-depth: 0
       - uses: ./.github/actions/python-bootstrap
@@ -55,27 +67,44 @@ jobs:
   test:
     runs-on: ubuntu-latest
     strategy: *python-matrix
+    permissions: *permissions_read
     steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
+      - *checkout_step
       - uses: ./.github/actions/python-bootstrap
         with:
           python-version: ${{ matrix.python-version }}
           python-bootstrap: "-e .[dev,yaml]"
-      - name: Run tests
+      - name: Run tests (with coverage)
         run: |
-          pytest -q
+          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: startsWith(github.ref, 'refs/tags/v')
+    if: &release_tag_condition >
+      startsWith(github.ref, 'refs/tags/v') ||
+      startsWith(github.ref, 'refs/tags/rc')
     needs: [lint, test]
+    permissions: *permissions_read
     steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
+      - *checkout_step
       - uses: ./.github/actions/python-bootstrap
         with:
           python-version: '3.13'
@@ -84,7 +113,7 @@ jobs:
         run: |
           python -m build
       - name: Upload distributions
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # Pinned v4
         with:
           name: dist-artifacts
           path: dist/*
@@ -93,21 +122,20 @@ jobs:
   release:
     name: Publish GitHub Release
     runs-on: ubuntu-latest
-    if: startsWith(github.ref, 'refs/tags/v')
+    if: *release_tag_condition
     needs: build
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Download distributions
-        uses: actions/download-artifact@v4
+      - *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@v2
+        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b  # Pinned v2
         with:
           files: dist/*
           generate_release_notes: true
@@ -115,21 +143,18 @@ jobs:
   publish:
     name: Publish to PyPI
     runs-on: ubuntu-latest
-    if: startsWith(github.ref, 'refs/tags/v')
+    if: *release_tag_condition
     needs: build
+    permissions:
+      contents: read
+      id-token: write
     environment:
       name: pypi
       url: https://pypi.org/project/etlplus/
     steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Download distributions
-        uses: actions/download-artifact@v4
-        with:
-          name: dist-artifacts
-          path: dist
+      - *checkout_step
+      - *download_dist_step
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e  # Pinned v1
         with:
           verbose: true

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.3.10
+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.10 → etlplus-0.3.17/etlplus.egg-info}/PKG-INFO

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

@@ -1,3 +1,4 @@
+.coveragerc
 .editorconfig
 .gitattributes
 .gitignore
@@ -86,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.10 → 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]]:
     """