etlplus 0.15.0__py3-none-any.whl → 0.15.2__py3-none-any.whl

etlplus/ops/utils.py

@@ -7,13 +7,11 @@ The helpers defined here embrace a "high cohesion, low coupling" design by
 isolating normalization, configuration, and logging responsibilities. The
 resulting surface keeps ``maybe_validate`` focused on orchestration while
 offloading ancillary concerns to composable helpers.
-
 """
 
 from __future__ import annotations
 
 from collections.abc import Callable
-from collections.abc import Mapping
 from dataclasses import dataclass
 from types import MappingProxyType
 from typing import Any
@@ -23,7 +21,7 @@ from typing import TypedDict
 from typing import cast
 
 from ..types import StrAnyMap
-from ..utils import normalized_str
+from ..utils import normalize_choice
 
 # SECTION: TYPED DICTIONARIES =============================================== #
 
@@ -320,7 +318,7 @@ def _normalize_phase(
     """
     return cast(
         ValidationPhase,
-        _normalize_choice(
+        normalize_choice(
             value,
             mapping=_PHASE_CHOICES,
             default='before_transform',
@@ -346,7 +344,7 @@ def _normalize_severity(
     """
     return cast(
         ValidationSeverity,
-        _normalize_choice(
+        normalize_choice(
             value,
             mapping=_SEVERITY_CHOICES,
             default='error',
@@ -372,7 +370,7 @@ def _normalize_window(
     """
     return cast(
         ValidationWindow,
-        _normalize_choice(
+        normalize_choice(
             value,
             mapping=_WINDOW_CHOICES,
             default='both',
@@ -380,33 +378,6 @@ def _normalize_window(
     )
 
 
-def _normalize_choice(
-    value: str | None,
-    *,
-    mapping: Mapping[str, str],
-    default: str,
-) -> str:
-    """
-    Normalize a text value against a mapping with a default fallback.
-
-    Parameters
-    ----------
-    value : str | None
-        Input text to normalize.
-    mapping : Mapping[str, str]
-        Mapping of accepted values to normalized outputs.
-    default : str
-        Default to return when input is missing or unrecognized.
-
-    Returns
-    -------
-    str
-        Normalized value.
-    """
-    normalized = normalized_str(value)
-    return mapping.get(normalized, default)
-
-
 def _rule_name(
     rules: Ruleset,
 ) -> str | None:

etlplus/ops/validate.py

@@ -11,8 +11,8 @@ Highlights
 ----------
 - Centralized type map and helpers for clarity and reuse.
 - Consistent error wording; field and item paths like ``[2].email``.
-- Small, focused public API with ``load_data``, ``validate_field``,
-  ``validate``.
+- Small, focused public API with :func:`load_data`, :func:`validate_field`,
+    :func:`validate`.
 
 Examples
 --------
@@ -66,7 +66,7 @@ TYPE_MAP: Final[dict[str, type | tuple[type, ...]]] = {
 }
 
 
-# SECTION: CLASSES ========================================================== #
+# SECTION: TYPED DICTS ====================================================== #
 
 
 class FieldRules(TypedDict, total=False):

etlplus/types.py

@@ -11,8 +11,9 @@ Notes
 
 See Also
 --------
-- :mod:`etlplus.api.types` for HTTP-specific aliases
-- :mod:`etlplus.config.types` for TypedDict surfaces
+- :mod:`etlplus.api.types` for HTTP-specific aliases and data classes
+- :mod:`etlplus.workflow.types` for workflow-specific aliases and TypedDict
+    surfaces
 
 Examples
 --------

etlplus/utils.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 import json
 from collections.abc import Callable
+from collections.abc import Iterable
 from collections.abc import Mapping
 from typing import Any
 from typing import TypeVar
@@ -25,6 +26,7 @@ __all__ = [
     # Mapping utilities
     'cast_str_dict',
     'coerce_dict',
+    'deep_substitute',
     'maybe_mapping',
     # Float coercion
     'to_float',
@@ -39,7 +41,8 @@ __all__ = [
     # Generic number coercion
     'to_number',
     # Text processing
-    'normalized_str',
+    'normalize_choice',
+    'normalize_str',
 ]
 
 
@@ -56,6 +59,52 @@ Num = TypeVar('Num', int, float)
 # -- Data Utilities -- #
 
 
+def deep_substitute(
+    value: Any,
+    vars_map: StrAnyMap | None,
+    env_map: Mapping[str, str] | None,
+) -> Any:
+    """
+    Recursively substitute ``${VAR}`` tokens in nested structures.
+
+    Only strings are substituted; other types are returned as-is.
+
+    Parameters
+    ----------
+    value : Any
+        The value to perform substitutions on.
+    vars_map : StrAnyMap | None
+        Mapping of variable names to replacement values (lower precedence).
+    env_map : Mapping[str, str] | None
+        Mapping of environment variables overriding ``vars_map`` values
+        (higher precedence).
+
+    Returns
+    -------
+    Any
+        New structure with substitutions applied where tokens were found.
+    """
+    substitutions = _prepare_substitutions(vars_map, env_map)
+
+    def _apply(node: Any) -> Any:
+        match node:
+            case str():
+                return _replace_tokens(node, substitutions)
+            case Mapping():
+                return {k: _apply(v) for k, v in node.items()}
+            case list() | tuple() as seq:
+                apply = [_apply(item) for item in seq]
+                return apply if isinstance(seq, list) else tuple(apply)
+            case set():
+                return {_apply(item) for item in node}
+            case frozenset():
+                return frozenset(_apply(item) for item in node)
+            case _:
+                return node
+
+    return _apply(value)
+
+
 def cast_str_dict(
     mapping: StrAnyMap | None,
 ) -> dict[str, str]:
@@ -372,7 +421,7 @@ def to_number(
 # -- Text Processing -- #
 
 
-def normalized_str(
+def normalize_str(
     value: str | None,
 ) -> str:
     """
@@ -392,6 +441,36 @@ def normalized_str(
     return (value or '').strip().lower()
 
 
+def normalize_choice(
+    value: str | None,
+    *,
+    mapping: Mapping[str, str],
+    default: str,
+    normalize: Callable[[str | None], str] = normalize_str,
+) -> str:
+    """
+    Normalize a string choice using a mapping and fallback.
+
+    Parameters
+    ----------
+    value : str | None
+        Input value to normalize.
+    mapping : Mapping[str, str]
+        Mapping of acceptable normalized inputs to output values.
+    default : str
+        Default return value when input is missing or unrecognized.
+    normalize : Callable[[str | None], str], optional
+        Normalization function applied to *value*. Defaults to
+        :func:`normalize_str`.
+
+    Returns
+    -------
+    str
+        Normalized mapped value or ``default``.
+    """
+    return mapping.get(normalize(value), default)
+
+
 # SECTION: INTERNAL FUNCTIONS =============================================== #
 
 
@@ -425,6 +504,61 @@ def _clamp(
     return value
 
 
+def _prepare_substitutions(
+    vars_map: StrAnyMap | None,
+    env_map: Mapping[str, Any] | None,
+) -> tuple[tuple[str, Any], ...]:
+    """
+    Merge variable and environment maps into an ordered substitutions list.
+
+    Parameters
+    ----------
+    vars_map : StrAnyMap | None
+        Mapping of variable names to replacement values (lower precedence).
+    env_map : Mapping[str, Any] | None
+        Environment-backed values that override entries from ``vars_map``.
+
+    Returns
+    -------
+    tuple[tuple[str, Any], ...]
+        Immutable sequence of ``(name, value)`` pairs suitable for token
+        replacement.
+    """
+    if not vars_map and not env_map:
+        return ()
+    merged: dict[str, Any] = {**(vars_map or {}), **(env_map or {})}
+    return tuple(merged.items())
+
+
+def _replace_tokens(
+    text: str,
+    substitutions: Iterable[tuple[str, Any]],
+) -> str:
+    """
+    Replace ``${VAR}`` tokens in ``text`` using ``substitutions``.
+
+    Parameters
+    ----------
+    text : str
+        Input string that may contain ``${VAR}`` tokens.
+    substitutions : Iterable[tuple[str, Any]]
+        Sequence of ``(name, value)`` pairs used for token replacement.
+
+    Returns
+    -------
+    str
+        Updated text with replacements applied.
+    """
+    if not substitutions:
+        return text
+    out = text
+    for name, replacement in substitutions:
+        token = f'${{{name}}}'
+        if token in out:
+            out = out.replace(token, str(replacement))
+    return out
+
+
 def _coerce_float(
     value: object,
 ) -> float | None:

etlplus/workflow/connector.py

@@ -22,15 +22,15 @@ Notes
 -----
 - TypedDict shapes are editor hints; runtime parsing remains permissive
     (from_obj accepts Mapping[str, Any]).
-- TypedDicts referenced in :mod:`etlplus.config.types` remain editor hints.
+- TypedDicts referenced in :mod:`etlplus.workflow.types` remain editor hints.
     Runtime parsing stays permissive and tolerant.
 
 See Also
 --------
 - TypedDict shapes for editor hints (not enforced at runtime):
-    :mod:`etlplus.config.types.ConnectorApiConfigMap`,
-    :mod:`etlplus.config.types.ConnectorDbConfigMap`,
-    :mod:`etlplus.config.types.ConnectorFileConfigMap`.
+    :mod:`etlplus.workflow.types.ConnectorApiConfigMap`,
+    :mod:`etlplus.workflow.types.ConnectorDbConfigMap`,
+    :mod:`etlplus.workflow.types.ConnectorFileConfigMap`.
 """
 
 from __future__ import annotations
@@ -71,6 +71,40 @@ __all__ = [
 ]
 
 
+# SECTION: INTERNAL FUNCTIONS ============================================== #
+
+
+def _require_name(
+    obj: StrAnyMap,
+    *,
+    kind: str,
+) -> str:
+    """
+    Extract and validate the ``name`` field from connector mappings.
+
+    Parameters
+    ----------
+    obj : StrAnyMap
+        Connector mapping with a ``name`` entry.
+    kind : str
+        Connector kind used in the error message.
+
+    Returns
+    -------
+    str
+        Valid connector name.
+
+    Raises
+    ------
+    TypeError
+        If ``name`` is missing or not a string.
+    """
+    name = obj.get('name')
+    if not isinstance(name, str):
+        raise TypeError(f'Connector{kind} requires a "name" (str)')
+    return name
+
+
 # SECTION: DATA CLASSES ===================================================== #
 
 
@@ -151,15 +185,8 @@ class ConnectorApi:
         -------
         Self
             Parsed connector instance.
-
-        Raises
-        ------
-        TypeError
-            If ``name`` is missing or invalid.
         """
-        name = obj.get('name')
-        if not isinstance(name, str):
-            raise TypeError('ConnectorApi requires a "name" (str)')
+        name = _require_name(obj, kind='Api')
         headers = cast_str_dict(obj.get('headers'))
 
         return cls(
@@ -233,15 +260,8 @@ class ConnectorDb:
         -------
         Self
             Parsed connector instance.
-
-        Raises
-        ------
-        TypeError
-            If ``name`` is missing or invalid.
         """
-        name = obj.get('name')
-        if not isinstance(name, str):
-            raise TypeError('ConnectorDb requires a "name" (str)')
+        name = _require_name(obj, kind='Db')
 
         return cls(
             name=name,
@@ -307,15 +327,8 @@ class ConnectorFile:
         -------
         Self
             Parsed connector instance.
-
-        Raises
-        ------
-        TypeError
-            If ``name`` is missing or invalid.
         """
-        name = obj.get('name')
-        if not isinstance(name, str):
-            raise TypeError('ConnectorFile requires a "name" (str)')
+        name = _require_name(obj, kind='File')
 
         return cls(
             name=name,

etlplus/workflow/jobs.py

@@ -19,6 +19,7 @@ from dataclasses import field
 from typing import Any
 from typing import Self
 
+from ..types import StrAnyMap
 from ..utils import coerce_dict
 from ..utils import maybe_mapping
 
@@ -35,6 +36,75 @@ __all__ = [
 ]
 
 
+# SECTION: INTERNAL FUNCTIONS =============================================== #
+
+
+def _coerce_optional_str(value: Any) -> str | None:
+    """
+    Normalize optional string values, coercing non-strings when needed.
+
+    Parameters
+    ----------
+    value : Any
+        Optional value to normalize.
+
+    Returns
+    -------
+    str | None
+        ``None`` when ``value`` is ``None``; otherwise a string value.
+    """
+    if value is None:
+        return None
+    return value if isinstance(value, str) else str(value)
+
+
+def _parse_depends_on(
+    value: Any,
+) -> list[str]:
+    """
+    Normalize dependency declarations into a string list.
+
+    Parameters
+    ----------
+    value : Any
+        Input dependency specification (string or list of strings).
+
+    Returns
+    -------
+    list[str]
+        Normalized dependency list.
+    """
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list):
+        return [entry for entry in value if isinstance(entry, str)]
+    return []
+
+
+def _require_str(
+    # data: dict[str, Any],
+    data: StrAnyMap,
+    key: str,
+) -> str | None:
+    """
+    Extract a required string field from a mapping.
+
+    Parameters
+    ----------
+    data : StrAnyMap
+        Mapping containing the target field.
+    key : str
+        Field name to extract.
+
+    Returns
+    -------
+    str | None
+        The string value when present and valid; otherwise ``None``.
+    """
+    value = data.get(key)
+    return value if isinstance(value, str) else None
+
+
 # SECTION: DATA CLASSES ===================================================== #
 
 
@@ -79,8 +149,8 @@ class ExtractRef:
         data = maybe_mapping(obj)
         if not data:
             return None
-        source = data.get('source')
-        if not isinstance(source, str):
+        source = _require_str(data, 'source')
+        if source is None:
             return None
         return cls(
             source=source,
@@ -144,22 +214,13 @@ class JobConfig:
         data = maybe_mapping(obj)
         if not data:
             return None
-        name = data.get('name')
-        if not isinstance(name, str):
+        name = _require_str(data, 'name')
+        if name is None:
             return None
 
-        description = data.get('description')
-        if description is not None and not isinstance(description, str):
-            description = str(description)
+        description = _coerce_optional_str(data.get('description'))
 
-        depends_raw = data.get('depends_on')
-        depends_on: list[str] = []
-        if isinstance(depends_raw, str):
-            depends_on = [depends_raw]
-        elif isinstance(depends_raw, list):
-            for entry in depends_raw:
-                if isinstance(entry, str):
-                    depends_on.append(entry)
+        depends_on = _parse_depends_on(data.get('depends_on'))
 
         return cls(
             name=name,
@@ -213,8 +274,8 @@ class LoadRef:
         data = maybe_mapping(obj)
         if not data:
             return None
-        target = data.get('target')
-        if not isinstance(target, str):
+        target = _require_str(data, 'target')
+        if target is None:
             return None
         return cls(
             target=target,
@@ -260,8 +321,8 @@ class TransformRef:
         data = maybe_mapping(obj)
         if not data:
             return None
-        pipeline = data.get('pipeline')
-        if not isinstance(pipeline, str):
+        pipeline = _require_str(data, 'pipeline')
+        if pipeline is None:
             return None
         return cls(pipeline=pipeline)
 
@@ -311,15 +372,11 @@ class ValidationRef:
         data = maybe_mapping(obj)
         if not data:
             return None
-        ruleset = data.get('ruleset')
-        if not isinstance(ruleset, str):
+        ruleset = _require_str(data, 'ruleset')
+        if ruleset is None:
             return None
-        severity = data.get('severity')
-        if severity is not None and not isinstance(severity, str):
-            severity = str(severity)
-        phase = data.get('phase')
-        if phase is not None and not isinstance(phase, str):
-            phase = str(phase)
+        severity = _coerce_optional_str(data.get('severity'))
+        phase = _coerce_optional_str(data.get('phase'))
         return cls(
             ruleset=ruleset,
             severity=severity,