etlplus 0.5.5__tar.gz → 0.6.1__tar.gz

{etlplus-0.5.5/etlplus.egg-info → etlplus-0.6.1}/PKG-INFO

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

{etlplus-0.5.5 → etlplus-0.6.1}/etlplus/cli/handlers.py

@@ -18,8 +18,8 @@ from typing import cast
 
 from ..config import PipelineConfig
 from ..config import load_pipeline_config
-from ..ddl import load_table_spec
-from ..ddl import render_tables
+from ..database import load_table_spec
+from ..database import render_tables
 from ..enums import FileFormat
 from ..extract import extract
 from ..file import File

etlplus-0.6.1/etlplus/database/__init__.py

@@ -0,0 +1,23 @@
+"""
+:mod:`etlplus.database` package.
+
+This package defines database-related utilities for ETLPlus, including:
+- DDL rendering and schema 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
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'load_table_spec',
+    'render_table_sql',
+    'render_tables',
+    'render_tables_to_string',
+]

{etlplus-0.5.5/etlplus → etlplus-0.6.1/etlplus/database}/ddl.py

@@ -11,18 +11,20 @@ can emit DDLs without shelling out to that script.
 from __future__ import annotations
 
 import importlib.resources
-import json
 import os
 from collections.abc import Iterable
 from collections.abc import Mapping
 from pathlib import Path
 from typing import Any
+from typing import Final
 
 from jinja2 import DictLoader
 from jinja2 import Environment
 from jinja2 import FileSystemLoader
 from jinja2 import StrictUndefined
 
+from ..file import File
+
 # SECTION: EXPORTS ========================================================== #
 
 
@@ -31,13 +33,26 @@ __all__ = [
     'load_table_spec',
     'render_table_sql',
     'render_tables',
+    'render_tables_to_string',
 ]
 
 
+# SECTION: INTERNAL CONSTANTS =============================================== #
+
+
+_SUPPORTED_SPEC_SUFFIXES: Final[frozenset[str]] = frozenset(
+    {
+        '.json',
+        '.yml',
+        '.yaml',
+    },
+)
+
+
 # SECTION: CONSTANTS ======================================================== #
 
 
-TEMPLATES = {
+TEMPLATES: Final[dict[str, str]] = {
     'ddl': 'ddl.sql.j2',
     'view': 'view.sql.j2',
 }
@@ -46,12 +61,68 @@ TEMPLATES = {
 # SECTION: INTERNAL FUNCTIONS =============================================== #
 
 
-def _build_env(
+def _load_template_text(
+    filename: str,
+) -> str:
+    """Return the bundled template text.
+
+    Parameters
+    ----------
+    filename : str
+        Template filename located inside the package data folder.
+
+    Returns
+    -------
+    str
+        Raw template contents.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the template file cannot be located in package data.
+    """
+
+    try:
+        return (
+            importlib.resources.files(
+                'etlplus.templates',
+            )
+            .joinpath(filename)
+            .read_text(encoding='utf-8')
+        )
+    except FileNotFoundError as exc:  # pragma: no cover - deployment guard
+        raise FileNotFoundError(
+            f'Could not load template {filename} '
+            f'from etlplus.templates package data.',
+        ) from exc
+
+
+def _resolve_template(
     *,
     template_key: str | None,
     template_path: str | None,
-) -> Environment:
-    """Return a Jinja2 environment using a built-in or file template."""
+) -> tuple[Environment, str]:
+    """Return environment and template name for rendering.
+
+    Parameters
+    ----------
+    template_key : str | None
+        Named template key bundled with the package.
+    template_path : str | None
+        Explicit template file override.
+
+    Returns
+    -------
+    tuple[Environment, str]
+        Pair of configured Jinja environment and the template identifier.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the provided template path does not exist.
+    ValueError
+        If the template key is unknown.
+    """
     file_override = template_path or os.environ.get('TEMPLATE_NAME')
     if file_override:
         path = Path(file_override)
@@ -64,8 +135,7 @@ def _build_env(
             trim_blocks=True,
             lstrip_blocks=True,
         )
-        env.globals['TEMPLATE_NAME'] = path.name
-        return env
+        return env, path.name
 
     key = (template_key or 'ddl').strip()
     if key not in TEMPLATES:
@@ -84,51 +154,59 @@ def _build_env(
         trim_blocks=True,
         lstrip_blocks=True,
     )
-    env.globals['TEMPLATE_NAME'] = key
-    return env
+    return env, key
 
 
-def _load_template_text(filename: str) -> str:
-    """Return the raw template text bundled with the package."""
+# SECTION: FUNCTIONS ======================================================== #
 
-    try:
-        return (
-            importlib.resources.files(
-                'etlplus.templates',
-            )
-            .joinpath(filename)
-            .read_text(encoding='utf-8')
-        )
-    except FileNotFoundError as exc:  # pragma: no cover - deployment guard
-        raise FileNotFoundError(
-            f'Could not load template {filename} '
-            f'from etlplus.templates package data.',
-        ) from exc
 
+def load_table_spec(
+    path: Path | str,
+) -> dict[str, Any]:
+    """
+    Load a table specification from disk.
 
-# SECTION: FUNCTIONS ======================================================== #
+    Parameters
+    ----------
+    path : Path | str
+        Path to the JSON or YAML specification file.
 
+    Returns
+    -------
+    dict[str, Any]
+        Parsed table specification mapping.
 
-def load_table_spec(path: Path | str) -> dict[str, Any]:
-    """Load a table spec from JSON or YAML."""
+    Raises
+    ------
+    ImportError
+        If the file cannot be read due to missing dependencies.
+    RuntimeError
+        If the YAML dependency is missing for YAML specs.
+    TypeError
+        If the loaded spec is not a mapping.
+    ValueError
+        If the file suffix is not supported.
+    """
 
     spec_path = Path(path)
-    text = spec_path.read_text(encoding='utf-8')
     suffix = spec_path.suffix.lower()
 
-    if suffix == '.json':
-        return json.loads(text)
+    if suffix not in _SUPPORTED_SPEC_SUFFIXES:
+        raise ValueError('Spec must be .json, .yml, or .yaml')
 
-    if suffix in {'.yml', '.yaml'}:
-        try:
-            import yaml  # type: ignore
-        except Exception as exc:  # pragma: no cover
+    try:
+        spec = File.read_file(spec_path)
+    except ImportError as e:
+        if suffix in {'.yml', '.yaml'}:
             raise RuntimeError(
                 'Missing dependency: pyyaml is required for YAML specs.',
-            ) from exc
-        return yaml.safe_load(text)
+            ) from e
+        raise
 
-    raise ValueError('Spec must be .json, .yml, or .yaml')
+    if not isinstance(spec, Mapping):
+        raise TypeError('Table spec must be a mapping')
+
+    return dict(spec)
 
 
 def render_table_sql(
@@ -153,16 +231,11 @@ def render_table_sql(
     -------
     str
         Rendered SQL string.
-
-    Raises
-    ------
-    TypeError
-        If the loaded template name is not a string.
     """
-    env = _build_env(template_key=template, template_path=template_path)
-    template_name = env.globals.get('TEMPLATE_NAME')
-    if not isinstance(template_name, str):
-        raise TypeError('TEMPLATE_NAME must be a string.')
+    env, template_name = _resolve_template(
+        template_key=template,
+        template_path=template_path,
+    )
     tmpl = env.get_template(template_name)
     return tmpl.render(spec=spec).rstrip() + '\n'
 
@@ -195,3 +268,44 @@ def render_tables(
         render_table_sql(spec, template=template, template_path=template_path)
         for spec in specs
     ]
+
+
+def render_tables_to_string(
+    spec_paths: Iterable[Path | str],
+    *,
+    template: str | None = 'ddl',
+    template_path: Path | str | None = None,
+) -> str:
+    """
+    Render one or more specs and concatenate the SQL payloads.
+
+    Parameters
+    ----------
+    spec_paths : Iterable[Path | str]
+        Paths to table specification files.
+    template : str | None, optional
+        Template key bundled with ETLPlus. Defaults to ``'ddl'``.
+    template_path : Path | str | None, optional
+        Custom Jinja template to override the bundled templates.
+
+    Returns
+    -------
+    str
+        Concatenated SQL payload suitable for writing to disk or stdout.
+    """
+
+    resolved_template_path = (
+        str(template_path) if template_path is not None else None
+    )
+    rendered_sql: list[str] = []
+    for spec_path in spec_paths:
+        spec = load_table_spec(spec_path)
+        rendered_sql.append(
+            render_table_sql(
+                spec,
+                template=template,
+                template_path=resolved_template_path,
+            ),
+        )
+
+    return ''.join(rendered_sql)

{etlplus-0.5.5 → etlplus-0.6.1/etlplus.egg-info}/PKG-INFO

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

{etlplus-0.5.5 → etlplus-0.6.1}/etlplus.egg-info/SOURCES.txt

@@ -22,7 +22,6 @@ docs/snippets/installation_version.md
 etlplus/__init__.py
 etlplus/__main__.py
 etlplus/__version__.py
-etlplus/ddl.py
 etlplus/enums.py
 etlplus/extract.py
 etlplus/file.py
@@ -69,6 +68,8 @@ etlplus/config/pipeline.py
 etlplus/config/profile.py
 etlplus/config/types.py
 etlplus/config/utils.py
+etlplus/database/__init__.py
+etlplus/database/ddl.py
 etlplus/templates/__init__.py
 etlplus/templates/ddl.sql.j2
 etlplus/templates/view.sql.j2
@@ -129,6 +130,7 @@ 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/database/test_u_database_ddl.py
 tests/unit/validation/test_u_validation_utils.py
 tools/run_pipeline.py
 tools/update_demo_snippets.py

{etlplus-0.5.5 → etlplus-0.6.1}/tests/unit/cli/test_u_cli_app.py

@@ -1,5 +1,5 @@
 """
-:mod:`tests.unit.test_u_cli_app` module.
+:mod:`tests.unit.cli.test_u_cli_app` module.
 
 Unit tests for :mod:`etlplus.cli.app`.
 """

{etlplus-0.5.5 → etlplus-0.6.1}/tests/unit/cli/test_u_cli_handlers.py

@@ -1,5 +1,5 @@
 """
-:mod:`tests.unit.test_u_cli_handlers` module.
+:mod:`tests.unit.cli.test_u_cli_handlers` module.
 
 Unit tests for :mod:`etlplus.cli.handlers`.
 """

{etlplus-0.5.5 → etlplus-0.6.1}/tests/unit/cli/test_u_cli_main.py

@@ -1,5 +1,5 @@
 """
-:mod:`tests.unit.test_u_cli_main` module.
+:mod:`tests.unit.cli.test_u_cli_main` module.
 
 Unit tests for :mod:`etlplus.cli.main`.
 """

etlplus-0.6.1/tests/unit/database/test_u_database_ddl.py

@@ -0,0 +1,265 @@
+"""
+:mod:`tests.unit.database.test_u_database_ddl` module.
+
+Unit tests for :mod:`etlplus.database.ddl`.
+"""
+
+from __future__ import annotations
+
+import json
+from copy import deepcopy
+from pathlib import Path
+
+import pytest
+
+from etlplus.database import ddl
+
+# SECTION: HELPERS ========================================================== #
+
+
+pytestmark = pytest.mark.unit
+
+
+# SECTION: FIXTURES ========================================================= #
+
+
+@pytest.fixture(name='sample_spec')
+def fixture_sample_spec() -> dict[str, object]:
+    """Sample table specification for testing."""
+    return {
+        'schema': 'dbo',
+        'table': 'widgets',
+        'create_schema': False,
+        'columns': [
+            {
+                'name': 'id',
+                'type': 'INT',
+                'nullable': False,
+                'identity': {'seed': 1, 'increment': 1},
+            },
+            {
+                'name': 'name',
+                'type': 'NVARCHAR(255)',
+                'nullable': True,
+            },
+        ],
+        'primary_key': {
+            'columns': ['id'],
+        },
+        'indexes': [
+            {
+                'name': 'IX_widgets_name',
+                'columns': ['name'],
+                'unique': True,
+            },
+        ],
+        'foreign_keys': [],
+    }
+
+
+# SECTION: TESTS ============================================================ #
+
+
+class TestLoadTableSpec:
+    """Unit test suite for :func:`load_table_spec`."""
+
+    def test_missing_yaml_dependency(
+        self,
+        tmp_path: Path,
+        sample_spec: dict[str, object],
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test that loading a YAML spec without PyYAML raises RuntimeError."""
+        yaml = pytest.importorskip('yaml')
+        spec_path = tmp_path / 'spec.yaml'
+        spec_path.write_text(
+            yaml.safe_dump(sample_spec, sort_keys=False),
+            encoding='utf-8',
+        )
+
+        import etlplus.file as file_mod
+
+        file_mod._YAML_CACHE.clear()
+
+        def _raise_import_error() -> None:
+            raise ImportError('forced failure for test')
+
+        monkeypatch.setattr(file_mod, '_get_yaml', _raise_import_error)
+
+        with pytest.raises(RuntimeError):
+            ddl.load_table_spec(spec_path)
+
+    def test_requires_mapping(self, tmp_path: Path) -> None:
+        """Test that loading a spec requires a mapping at the top level."""
+        spec_path = tmp_path / 'array.json'
+        spec_path.write_text(
+            json.dumps([{'not': 'mapping'}]),
+            encoding='utf-8',
+        )
+
+        with pytest.raises(TypeError):
+            ddl.load_table_spec(spec_path)
+
+    @pytest.mark.parametrize(
+        'extension',
+        ['json', 'yaml'],
+        ids=['json', 'yaml'],
+    )
+    def test_roundtrip(
+        self,
+        tmp_path: Path,
+        extension: str,
+        sample_spec: dict[str, object],
+    ) -> None:
+        """Test loading a table spec from JSON and YAML formats."""
+        spec_path = tmp_path / f'spec.{extension}'
+        materialized = deepcopy(sample_spec)
+        if extension == 'json':
+            spec_path.write_text(json.dumps(materialized), encoding='utf-8')
+        else:
+            yaml = pytest.importorskip('yaml')
+            spec_path.write_text(
+                yaml.safe_dump(materialized, sort_keys=False),
+                encoding='utf-8',
+            )
+
+        loaded = ddl.load_table_spec(spec_path)
+        assert loaded == materialized
+
+    def test_unsupported_suffix(self, tmp_path: Path) -> None:
+        """
+        Test that loading a spec with an unsupported suffix raises ValueError.
+        """
+        spec_path = tmp_path / 'spec.txt'
+        spec_path.write_text('{}', encoding='utf-8')
+
+        with pytest.raises(ValueError):
+            ddl.load_table_spec(spec_path)
+
+
+class TestRenderTableSql:
+    """Unit test suite for :func:`render_table_sql`."""
+
+    def test_custom_template_path(
+        self,
+        tmp_path: Path,
+        sample_spec: dict[str, object],
+    ) -> None:
+        """Test rendering SQL with a custom template path."""
+        template_path = tmp_path / 'custom.sql.j2'
+        template_path.write_text('{{ spec.table }}', encoding='utf-8')
+
+        sql = ddl.render_table_sql(
+            sample_spec,
+            template_path=str(template_path),
+        )
+
+        assert sql == f'{sample_spec["table"]}\n'
+
+    def test_default_template(
+        self,
+        sample_spec: dict[str, object],
+    ) -> None:
+        """Test rendering SQL with the default template."""
+        sql = ddl.render_table_sql(sample_spec)
+        assert f'CREATE TABLE [dbo].[{sample_spec["table"]}' in sql
+        assert '[id] INT' in sql
+
+    def test_env_override(
+        self,
+        tmp_path: Path,
+        sample_spec: dict[str, object],
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """
+        Test rendering SQL with an environment variable override for the
+        template path.
+        """
+        template_path = tmp_path / 'env_template.sql.j2'
+        template_path.write_text(
+            '{{ spec.schema }}.{{ spec.table }}',
+            encoding='utf-8',
+        )
+        monkeypatch.setenv('TEMPLATE_NAME', str(template_path))
+
+        sql = ddl.render_table_sql(sample_spec, template=None)
+
+        assert sql == 'dbo.widgets\n'
+
+    def test_missing_template_path(
+        self,
+        sample_spec: dict[str, object],
+    ) -> None:
+        """Test that a missing template path raises FileNotFoundError."""
+        missing = Path('/nonexistent/template.sql.j2')
+        with pytest.raises(FileNotFoundError):
+            ddl.render_table_sql(sample_spec, template_path=str(missing))
+
+    def test_unknown_template_key(
+        self,
+        sample_spec: dict[str, object],
+    ) -> None:
+        """Test that an unknown template key raises ValueError."""
+        with pytest.raises(ValueError):
+            ddl.render_table_sql(sample_spec, template='does_not_exist')
+
+
+class TestRenderTablesToString:
+    """
+    Unit test suite for :func:`render_tables_to_string`.
+    """
+
+    def test_custom_template(
+        self,
+        tmp_path: Path,
+        sample_spec: dict[str, object],
+    ) -> None:
+        """
+        Test rendering multiple table specs to a string with a custom template.
+        """
+        template_path = tmp_path / 'concat_template.sql.j2'
+        template_path.write_text('{{ spec.table }}', encoding='utf-8')
+
+        path = tmp_path / 'spec.json'
+        path.write_text(json.dumps(sample_spec), encoding='utf-8')
+
+        sql = ddl.render_tables_to_string(
+            [path],
+            template_path=template_path,
+        )
+
+        assert sql == f'{sample_spec["table"]}\n'
+
+    def test_from_paths(
+        self,
+        tmp_path: Path,
+        sample_spec: dict[str, object],
+    ) -> None:
+        """
+        Test rendering multiple table specs from file paths into a single SQL
+        string.
+        """
+        spec_paths: list[Path] = []
+        for idx, table_name in enumerate(('widgets', 'widgets_history')):
+            materialized = deepcopy(sample_spec)
+            materialized['table'] = table_name
+            path = tmp_path / f'spec_{idx}.json'
+            path.write_text(json.dumps(materialized), encoding='utf-8')
+            spec_paths.append(path)
+
+        sql = ddl.render_tables_to_string(spec_paths)
+
+        assert 'widgets' in sql
+        assert 'widgets_history' in sql
+
+    def test_templates_constant_exposes_builtin_keys(self) -> None:
+        """Test that TEMPLATES constant includes expected built-in keys."""
+        assert {'ddl', 'view'}.issubset(set(ddl.TEMPLATES))
+
+
+class TestTemplate:
+    """Unit test suite for ``TEMPLATE``."""
+
+    def test_builtin_keys_exposure(self) -> None:
+        """Test that TEMPLATES constant includes expected built-in keys."""
+        assert {'ddl', 'view'}.issubset(set(ddl.TEMPLATES))