etlplus 0.5.5__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.5.5
+Version: 0.7.0
 Summary: A Swiss Army knife for simple ETL operations
 Home-page: https://github.com/Dagitali/ETLPlus
 Author: ETLPlus Team
@@ -21,7 +21,10 @@ Requires-Dist: jinja2>=3.1.6
 Requires-Dist: pyodbc>=5.3.0
 Requires-Dist: python-dotenv>=1.2.1
 Requires-Dist: pandas>=2.3.3
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: PyYAML>=6.0.3
 Requires-Dist: requests>=2.32.5
+Requires-Dist: SQLAlchemy>=2.0.45
 Requires-Dist: typer>=0.21.0
 Provides-Extra: dev
 Requires-Dist: black>=25.9.0; extra == "dev"

{etlplus-0.5.5 → etlplus-0.7.0}/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.7.0/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',
+]

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

@@ -1,5 +1,5 @@
 """
-:mod:`etlplus.ddl` module.
+:mod:`etlplus.database.ddl` module.
 
 DDL rendering utilities for pipeline table schemas.
 
@@ -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.7.0/etlplus/database/engine.py

@@ -0,0 +1,146 @@
+"""
+:mod:`etlplus.database.engine` module.
+
+Lightweight engine/session factory with optional config-driven URL loading.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from sqlalchemy import create_engine
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import sessionmaker
+
+from ..file import File
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    # Functions
+    'load_database_url_from_config',
+    'make_engine',
+    # Singletons
+    'engine',
+    'session',
+]
+
+
+# SECTION: INTERNAL CONSTANTS =============================================== #
+
+
+DATABASE_URL: str = (
+    os.getenv('DATABASE_URL')
+    or os.getenv('DATABASE_DSN')
+    or 'sqlite+pysqlite:///:memory:'
+)
+
+
+# SECTION: INTERNAL FUNCTIONS =============================================== #
+
+
+def _resolve_url_from_mapping(cfg: Mapping[str, Any]) -> str | None:
+    """
+    Return a URL/DSN from a mapping if present.
+
+    Parameters
+    ----------
+    cfg : Mapping[str, Any]
+        Configuration mapping potentially containing connection fields.
+
+    Returns
+    -------
+    str | None
+        Resolved URL/DSN string, if present.
+    """
+    conn = cfg.get('connection_string') or cfg.get('url') or cfg.get('dsn')
+    if isinstance(conn, str) and conn.strip():
+        return conn.strip()
+
+    # Some configs nest defaults.
+    # E.g., databases: { mssql: { default: {...} } }
+    default_cfg = cfg.get('default')
+    if isinstance(default_cfg, Mapping):
+        return _resolve_url_from_mapping(default_cfg)
+
+    return None
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def load_database_url_from_config(
+    path: str | Path,
+    *,
+    name: str | None = None,
+) -> str:
+    """
+    Extract a database URL/DSN from a YAML/JSON config file.
+
+    The loader is schema-tolerant: it looks for a top-level "databases" map
+    and then for a named entry (``name``). Each entry may contain either a
+    ``connection_string``/``url``/``dsn`` or a nested ``default`` block with
+    those fields.
+
+    Parameters
+    ----------
+    path : str | Path
+        Location of the configuration file.
+    name : str | None, optional
+        Named database entry under the ``databases`` map (default:
+        ``default``).
+
+    Returns
+    -------
+    str
+        Resolved database URL/DSN string.
+
+    Raises
+    ------
+    KeyError
+        If the specified database entry is not found.
+    TypeError
+        If the config structure is invalid.
+    ValueError
+        If no connection string/URL/DSN is found for the specified entry.
+    """
+    cfg = File.read_file(Path(path))
+    if not isinstance(cfg, Mapping):
+        raise TypeError('Database config must be a mapping')
+
+    databases = cfg.get('databases') if isinstance(cfg, Mapping) else None
+    if not isinstance(databases, Mapping):
+        raise KeyError('Config missing top-level "databases" mapping')
+
+    target = name or 'default'
+    entry = databases.get(target)
+    if entry is None:
+        raise KeyError(f'Database entry "{target}" not found in config')
+    if not isinstance(entry, Mapping):
+        raise TypeError(f'Database entry "{target}" must be a mapping')
+
+    url = _resolve_url_from_mapping(entry)
+    if not url:
+        raise ValueError(
+            f'Database entry "{target}" lacks connection_string/url/dsn',
+        )
+    return url
+
+
+def make_engine(url: str | None = None, **engine_kwargs: Any) -> Engine:
+    """Create a SQLAlchemy Engine, defaulting to env config if no URL given."""
+
+    resolved_url = url or DATABASE_URL
+    return create_engine(resolved_url, pool_pre_ping=True, **engine_kwargs)
+
+
+# SECTION: SINGLETONS ======================================================= #
+
+
+# Default engine/session for callers that rely on module-level singletons.
+engine = make_engine()
+session = sessionmaker(bind=engine, autoflush=False, autocommit=False)