etlplus 0.16.4__py3-none-any.whl → 0.16.5__py3-none-any.whl

etlplus/api/types.py

@@ -43,10 +43,10 @@ __all__ = [
     'Params',
     'Url',
     # Typed Dicts
-    'ApiConfigMap',
-    'ApiProfileConfigMap',
-    'ApiProfileDefaultsMap',
-    'EndpointMap',
+    'ApiConfigDict',
+    'ApiProfileConfigDict',
+    'ApiProfileDefaultsDict',
+    'EndpointConfigDict',
 ]
 
 
@@ -83,7 +83,7 @@ def _to_dict(
 # SECTION: TYPED DICTS ====================================================== #
 
 
-class ApiConfigMap(TypedDict, total=False):
+class ApiConfigDict(TypedDict, total=False):
     """
     Top-level API config shape parsed by
     :meth:`etlplus.api.config.ApiConfig.from_obj`.
@@ -99,11 +99,11 @@ class ApiConfigMap(TypedDict, total=False):
 
     base_url: str
     headers: StrAnyMap
-    endpoints: Mapping[str, EndpointMap | str]
-    profiles: Mapping[str, ApiProfileConfigMap]
+    endpoints: Mapping[str, EndpointConfigDict | str]
+    profiles: Mapping[str, ApiProfileConfigDict]
 
 
-class ApiProfileConfigMap(TypedDict, total=False):
+class ApiProfileConfigDict(TypedDict, total=False):
     """
     Shape accepted for a profile entry under
     :meth:`etlplus.api.config.ApiConfig.from_obj`.
@@ -123,10 +123,10 @@ class ApiProfileConfigMap(TypedDict, total=False):
     headers: StrAnyMap
     base_path: str
     auth: StrAnyMap
-    defaults: ApiProfileDefaultsMap
+    defaults: ApiProfileDefaultsDict
 
 
-class ApiProfileDefaultsMap(TypedDict, total=False):
+class ApiProfileDefaultsDict(TypedDict, total=False):
     """
     Defaults block available under a profile (all keys optional).
 
@@ -147,11 +147,11 @@ class ApiProfileDefaultsMap(TypedDict, total=False):
     """
 
     headers: StrAnyMap
-    pagination: StrAnyMap  # PaginationConfigMap | StrAnyMap
-    rate_limit: StrAnyMap  # RateLimitConfigMap | StrAnyMap
+    pagination: StrAnyMap  # PaginationConfigDict | StrAnyMap
+    rate_limit: StrAnyMap  # RateLimitConfigDict | StrAnyMap
 
 
-class EndpointMap(TypedDict, total=False):
+class EndpointConfigDict(TypedDict, total=False):
     """
     Shape accepted by :meth:`etlplus.api.config.EndpointConfig.from_obj`.
 
@@ -168,8 +168,8 @@ class EndpointMap(TypedDict, total=False):
     path_params: StrAnyMap
     query_params: StrAnyMap
     body: Any
-    pagination: StrAnyMap  # PaginationConfigMap | StrAnyMap
-    rate_limit: StrAnyMap  # RateLimitConfigMap | StrAnyMap
+    pagination: StrAnyMap  # PaginationConfigDict | StrAnyMap
+    rate_limit: StrAnyMap  # RateLimitConfigDict | StrAnyMap
 
 
 # SECTION: DATA CLASSES ===================================================== #

etlplus/api/utils.py

@@ -22,11 +22,11 @@ from .config import EndpointConfig
 from .endpoint_client import EndpointClient
 from .enums import HttpMethod
 from .pagination import PaginationConfig
-from .pagination import PaginationConfigMap
+from .pagination import PaginationConfigDict
 from .rate_limiting import RateLimitConfig
-from .rate_limiting import RateLimitConfigMap
+from .rate_limiting import RateLimitConfigDict
 from .rate_limiting import RateLimiter
-from .retry_manager import RetryPolicy
+from .retry_manager import RetryPolicyDict
 from .types import Headers
 from .types import Params
 from .types import Url
@@ -53,16 +53,16 @@ __all__ = [
     'paginate_with_client',
     'resolve_request',
     # Typed Dicts
-    'ApiRequestEnv',
-    'ApiTargetEnv',
-    'SessionConfig',
+    'ApiRequestEnvDict',
+    'ApiTargetEnvDict',
+    'SessionConfigDict',
 ]
 
 
 # SECTION: TYPED DICTS ====================================================== #
 
 
-class BaseApiHttpEnv(TypedDict, total=False):
+class BaseApiHttpEnvDict(TypedDict, total=False):
     """
     Common HTTP request environment for API interactions.
 
@@ -78,7 +78,7 @@ class BaseApiHttpEnv(TypedDict, total=False):
     session: requests.Session | None
 
 
-class ApiRequestEnv(BaseApiHttpEnv, total=False):
+class ApiRequestEnvDict(BaseApiHttpEnvDict, total=False):
     """
     Composed HTTP request environment configuration for REST API sources.
 
@@ -96,15 +96,15 @@ class ApiRequestEnv(BaseApiHttpEnv, total=False):
 
     # Request
     params: dict[str, Any]
-    pagination: PaginationConfigMap | None
+    pagination: PaginationConfigDict | None
     sleep_seconds: float
 
     # Reliability
-    retry: RetryPolicy | None
+    retry: RetryPolicyDict | None
     retry_network_errors: bool
 
 
-class ApiTargetEnv(BaseApiHttpEnv, total=False):
+class ApiTargetEnvDict(BaseApiHttpEnvDict, total=False):
     """
     Composed HTTP request environment configuration for REST API targets.
 
@@ -126,7 +126,7 @@ class ApiTargetEnv(BaseApiHttpEnv, total=False):
     method: str | None
 
 
-class SessionConfig(TypedDict, total=False):
+class SessionConfigDict(TypedDict, total=False):
     """
     Minimal session configuration schema accepted by the
     :class:`requests.Session` runner.
@@ -148,14 +148,14 @@ class SessionConfig(TypedDict, total=False):
 
 
 def _build_session_optional(
-    cfg: SessionConfig | None,
+    cfg: SessionConfigDict | None,
 ) -> requests.Session | None:
     """
     Return a configured session when *cfg* is a mapping.
 
     Parameters
     ----------
-    cfg : SessionConfig | None
+    cfg : SessionConfigDict | None
         Session configuration mapping.
 
     Returns
@@ -164,7 +164,7 @@ def _build_session_optional(
         Configured session or ``None``.
     """
     if isinstance(cfg, Mapping):
-        return build_session(cast(SessionConfig, cfg))
+        return build_session(cast(SessionConfigDict, cfg))
     return None
 
 
@@ -233,9 +233,9 @@ def _inherit_http_from_api_endpoint(
     ep: EndpointConfig,
     url: Url | None,
     headers: dict[str, str],
-    session_cfg: SessionConfig | None,
+    session_cfg: SessionConfigDict | None,
     force_url: bool = False,
-) -> tuple[Url | None, dict[str, str], SessionConfig | None]:
+) -> tuple[Url | None, dict[str, str], SessionConfigDict | None]:
     """
     Return HTTP settings inherited from API + endpoint definitions.
 
@@ -249,14 +249,14 @@ def _inherit_http_from_api_endpoint(
         Existing URL to use when not forcing endpoint URL.
     headers : dict[str, str]
         Existing headers to augment.
-    session_cfg : SessionConfig | None
+    session_cfg : SessionConfigDict | None
         Existing session configuration to augment.
     force_url : bool, optional
         Whether to always use the endpoint URL.
 
     Returns
     -------
-    tuple[Url | None, dict[str, str], SessionConfig | None]
+    tuple[Url | None, dict[str, str], SessionConfigDict | None]
         Resolved URL, headers, and session configuration.
     """
     if force_url or not url:
@@ -269,8 +269,8 @@ def _inherit_http_from_api_endpoint(
 def _merge_session_cfg_three(
     api_cfg: ApiConfig,
     ep: EndpointConfig,
-    source_session_cfg: SessionConfig | None,
-) -> SessionConfig | None:
+    source_session_cfg: SessionConfigDict | None,
+) -> SessionConfigDict | None:
     """
     Merge session configurations from API, endpoint, and source.
 
@@ -280,12 +280,12 @@ def _merge_session_cfg_three(
         API configuration.
     ep : EndpointConfig
         Endpoint configuration.
-    source_session_cfg : SessionConfig | None
+    source_session_cfg : SessionConfigDict | None
         Source session configuration.
 
     Returns
     -------
-    SessionConfig | None
+    SessionConfigDict | None
         Merged session configuration.
     """
     api_sess = getattr(api_cfg, 'session', None)
@@ -297,7 +297,7 @@ def _merge_session_cfg_three(
         merged.update(ep_sess)
     if isinstance(source_session_cfg, Mapping):
         merged.update(source_session_cfg)
-    return cast(SessionConfig | None, (merged or None))
+    return cast(SessionConfigDict | None, (merged or None))
 
 
 def _update_mapping(
@@ -361,7 +361,7 @@ def compose_api_request_env(
     cfg: Any,
     source_obj: Any,
     ex_opts: Mapping[str, Any] | None,
-) -> ApiRequestEnv:
+) -> ApiRequestEnvDict:
     """
     Compose the API request environment.
 
@@ -376,7 +376,7 @@ def compose_api_request_env(
 
     Returns
     -------
-    ApiRequestEnv
+    ApiRequestEnvDict
         The composed API request environment.
     """
     ex_opts = ex_opts or {}
@@ -393,13 +393,13 @@ def compose_api_request_env(
     headers: dict[str, str] = cast(dict[str, str], coerce_dict(source_headers))
     pagination = getattr(source_obj, 'pagination', None)
     rate_limit = getattr(source_obj, 'rate_limit', None)
-    retry: RetryPolicy | None = cast(
-        RetryPolicy | None,
+    retry: RetryPolicyDict | None = cast(
+        RetryPolicyDict | None,
         getattr(source_obj, 'retry', None),
     )
     retry_network_errors = getattr(source_obj, 'retry_network_errors', None)
     session_cfg = cast(
-        SessionConfig | None,
+        SessionConfigDict | None,
         getattr(source_obj, 'session', None),
     )
     api_name = getattr(source_obj, 'api', None)
@@ -435,7 +435,7 @@ def compose_api_request_env(
             api_cfg.effective_rate_limit_defaults(),
         )
         retry = cast(
-            RetryPolicy | None,
+            RetryPolicyDict | None,
             _coalesce(
                 retry,
                 getattr(ep, 'retry', None),
@@ -465,8 +465,8 @@ def compose_api_request_env(
     timeout: Timeout = ex_opts.get('timeout')
     pag_ov = ex_opts.get('pagination', {})
     rl_ov = ex_opts.get('rate_limit', {})
-    rty_ov: RetryPolicy | None = cast(
-        RetryPolicy | None,
+    rty_ov: RetryPolicyDict | None = cast(
+        RetryPolicyDict | None,
         (ex_opts.get('retry') if 'retry' in ex_opts else None),
     )
     rne_ov = (
@@ -474,7 +474,7 @@ def compose_api_request_env(
         if 'retry_network_errors' in ex_opts
         else None
     )
-    sess_ov = cast(SessionConfig | None, ex_opts.get('session'))
+    sess_ov = cast(SessionConfigDict | None, ex_opts.get('session'))
     sleep_s = compute_rl_sleep_seconds(rate_limit, rl_ov) or 0.0
     if rty_ov is not None:
         retry = rty_ov
@@ -485,8 +485,8 @@ def compose_api_request_env(
             cast(Mapping[str, Any], session_cfg or {}),
         )
         base_cfg.update(sess_ov)
-        session_cfg = cast(SessionConfig, base_cfg)
-    pag_cfg: PaginationConfigMap | None = build_pagination_cfg(
+        session_cfg = cast(SessionConfigDict, base_cfg)
+    pag_cfg: PaginationConfigDict | None = build_pagination_cfg(
         pagination,
         pag_ov,
     )
@@ -513,7 +513,7 @@ def compose_api_target_env(
     cfg: Any,
     target_obj: Any,
     overrides: Mapping[str, Any] | None,
-) -> ApiTargetEnv:
+) -> ApiTargetEnvDict:
     """
     Compose the API target environment.
 
@@ -528,7 +528,7 @@ def compose_api_target_env(
 
     Returns
     -------
-    ApiTargetEnv
+    ApiTargetEnvDict
         Composed API target environment.
     """
     ov = overrides or {}
@@ -553,8 +553,8 @@ def compose_api_target_env(
     timeout: Timeout = (
         cast(Timeout, ov.get('timeout')) if 'timeout' in ov else None
     )
-    sess_cfg: SessionConfig | None = cast(
-        SessionConfig | None,
+    sess_cfg: SessionConfigDict | None = cast(
+        SessionConfigDict | None,
         ov.get('session'),
     )
     api_name = getattr(target_obj, 'api', None)
@@ -583,7 +583,7 @@ def compose_api_target_env(
 def build_pagination_cfg(
     pagination: PaginationConfig | None,
     overrides: Mapping[str, Any] | None,
-) -> PaginationConfigMap | None:
+) -> PaginationConfigDict | None:
     """
     Build pagination configuration.
 
@@ -596,7 +596,7 @@ def build_pagination_cfg(
 
     Returns
     -------
-    PaginationConfigMap | None
+    PaginationConfigDict | None
         Pagination configuration.
     """
     ptype: str | None = None
@@ -683,7 +683,7 @@ def build_pagination_cfg(
         case _:
             pass
 
-    return cast(PaginationConfigMap, cfg)
+    return cast(PaginationConfigDict, cfg)
 
 
 def paginate_with_client(
@@ -692,7 +692,7 @@ def paginate_with_client(
     params: Params | None,
     headers: Headers | None,
     timeout: Timeout,
-    pagination: PaginationConfigMap | None,
+    pagination: PaginationConfigDict | None,
     sleep_seconds: float | None,
 ) -> Any:
     """
@@ -710,7 +710,7 @@ def paginate_with_client(
         Headers to include in the API request.
     timeout : Timeout
         Timeout configuration for the API request.
-    pagination : PaginationConfigMap | None
+    pagination : PaginationConfigDict | None
         Pagination configuration for the API request.
     sleep_seconds : float | None
         Sleep duration between API requests.
@@ -771,9 +771,9 @@ def compute_rl_sleep_seconds(
     else:
         rl_map = cast(Mapping[str, Any] | None, rate_limit)
 
-    rl_mapping = cast(RateLimitConfigMap | None, rl_map)
+    rl_mapping = cast(RateLimitConfigDict | None, rl_map)
 
-    typed_override: RateLimitConfigMap | None = None
+    typed_override: RateLimitConfigDict | None = None
     if overrides:
         filtered: dict[str, float | None] = {}
         if 'sleep_seconds' in overrides:
@@ -787,7 +787,7 @@ def compute_rl_sleep_seconds(
                 overrides.get('max_per_sec'),
             )
         if filtered:
-            typed_override = cast(RateLimitConfigMap, filtered)
+            typed_override = cast(RateLimitConfigDict, filtered)
 
     return RateLimiter.resolve_sleep_seconds(
         rate_limit=rl_mapping,
@@ -796,14 +796,14 @@ def compute_rl_sleep_seconds(
 
 
 def build_session(
-    cfg: SessionConfig | None,
+    cfg: SessionConfigDict | None,
 ) -> requests.Session:
     """
     Build a requests.Session object with the given configuration.
 
     Parameters
     ----------
-    cfg : SessionConfig | None
+    cfg : SessionConfigDict | None
         Session configuration.
 
     Returns

etlplus/cli/handlers.py

@@ -24,7 +24,7 @@ from ..ops import load
 from ..ops import run
 from ..ops import transform
 from ..ops import validate
-from ..ops.validate import FieldRules
+from ..ops.validate import FieldRulesDict
 from ..types import JSONData
 from ..types import TemplateKey
 from . import io as cli_io
@@ -661,7 +661,7 @@ def validate_handler(
     if not isinstance(rules_payload, dict):
         raise ValueError('rules must resolve to a mapping of field rules')
 
-    field_rules = cast(Mapping[str, FieldRules], rules_payload)
+    field_rules = cast(Mapping[str, FieldRulesDict], rules_payload)
     result = validate(payload, field_rules)
 
     if target and target != '-':
@@ -670,11 +670,11 @@ def validate_handler(
             cli_io.write_json_output(
                 validated_data,
                 target,
-                success_message='Validation result saved to',
+                success_message='ValidationDict result saved to',
             )
         else:
             print(
-                f'Validation failed, no data to save for {target}',
+                f'ValidationDict failed, no data to save for {target}',
                 file=sys.stderr,
             )
     else:

etlplus/connector/__init__.py

@@ -7,15 +7,15 @@ Connector configuration types and enums.
 from __future__ import annotations
 
 from .api import ConnectorApi
-from .api import ConnectorApiConfigMap
+from .api import ConnectorApiConfigDict
 from .connector import Connector
 from .core import ConnectorBase
 from .core import ConnectorProtocol
 from .database import ConnectorDb
-from .database import ConnectorDbConfigMap
+from .database import ConnectorDbConfigDict
 from .enums import DataConnectorType
 from .file import ConnectorFile
-from .file import ConnectorFileConfigMap
+from .file import ConnectorFileConfigDict
 from .types import ConnectorType
 from .utils import parse_connector
 
@@ -37,7 +37,7 @@ __all__ = [
     'ConnectorProtocol',
     'ConnectorType',
     # Typed Dicts
-    'ConnectorApiConfigMap',
-    'ConnectorDbConfigMap',
-    'ConnectorFileConfigMap',
+    'ConnectorApiConfigDict',
+    'ConnectorDbConfigDict',
+    'ConnectorFileConfigDict',
 ]

etlplus/connector/api.py

@@ -22,9 +22,9 @@ from typing import TypedDict
 from typing import overload
 
 from ..api import PaginationConfig
-from ..api import PaginationConfigMap
+from ..api import PaginationConfigDict
 from ..api import RateLimitConfig
-from ..api import RateLimitConfigMap
+from ..api import RateLimitConfigDict
 from ..types import StrAnyMap
 from ..types import StrStrMap
 from ..utils import cast_str_dict
@@ -39,14 +39,14 @@ from .types import ConnectorType
 
 __all__ = [
     'ConnectorApi',
-    'ConnectorApiConfigMap',
+    'ConnectorApiConfigDict',
 ]
 
 
 # SECTION: TYPED DICTS ====================================================== #
 
 
-class ConnectorApiConfigMap(TypedDict, total=False):
+class ConnectorApiConfigDict(TypedDict, total=False):
     """
     Shape accepted by :meth:`ConnectorApi.from_obj` (all keys optional).
 
@@ -61,8 +61,8 @@ class ConnectorApiConfigMap(TypedDict, total=False):
     method: str
     headers: StrStrMap
     query_params: StrAnyMap
-    pagination: PaginationConfigMap
-    rate_limit: RateLimitConfigMap
+    pagination: PaginationConfigDict
+    rate_limit: RateLimitConfigDict
     api: str
     endpoint: str
 
@@ -121,7 +121,7 @@ class ConnectorApi(ConnectorBase):
 
     @classmethod
     @overload
-    def from_obj(cls, obj: ConnectorApiConfigMap) -> Self: ...
+    def from_obj(cls, obj: ConnectorApiConfigDict) -> Self: ...
 
     @classmethod
     @overload

etlplus/connector/database.py

@@ -29,14 +29,14 @@ from .types import ConnectorType
 
 __all__ = [
     'ConnectorDb',
-    'ConnectorDbConfigMap',
+    'ConnectorDbConfigDict',
 ]
 
 
 # SECTION: TYPED DICTS ====================================================== #
 
 
-class ConnectorDbConfigMap(TypedDict, total=False):
+class ConnectorDbConfigDict(TypedDict, total=False):
     """
     Shape accepted by :meth:`ConnectorDb.from_obj` (all keys optional).
 
@@ -87,7 +87,7 @@ class ConnectorDb(ConnectorBase):
 
     @classmethod
     @overload
-    def from_obj(cls, obj: ConnectorDbConfigMap) -> Self: ...
+    def from_obj(cls, obj: ConnectorDbConfigDict) -> Self: ...
 
     @classmethod
     @overload

etlplus/connector/file.py

@@ -32,14 +32,14 @@ from .types import ConnectorType
 
 __all__ = [
     'ConnectorFile',
-    'ConnectorFileConfigMap',
+    'ConnectorFileConfigDict',
 ]
 
 
 # SECTION: TYPED DICTS ====================================================== #
 
 
-class ConnectorFileConfigMap(TypedDict, total=False):
+class ConnectorFileConfigDict(TypedDict, total=False):
     """
     Shape accepted by :meth:`ConnectorFile.from_obj` (all keys optional).
 
@@ -86,7 +86,7 @@ class ConnectorFile(ConnectorBase):
 
     @classmethod
     @overload
-    def from_obj(cls, obj: ConnectorFileConfigMap) -> Self: ...
+    def from_obj(cls, obj: ConnectorFileConfigDict) -> Self: ...
 
     @classmethod
     @overload

etlplus/connector/types.py

@@ -14,8 +14,8 @@ Examples
 >>>     "type": "database",
 >>>     "connection_string": "postgresql://user:pass@localhost/db",
 >>> }
->>> from etlplus.api import RetryPolicy
->>> rp: RetryPolicy = {"max_attempts": 3, "backoff": 0.5}
+>>> from etlplus.api import RetryPolicyDict
+>>> rp: RetryPolicyDict = {"max_attempts": 3, "backoff": 0.5}
 """
 
 from __future__ import annotations

etlplus/ops/extract.py

@@ -15,7 +15,7 @@ from urllib.parse import urlunsplit
 
 from ..api import EndpointClient
 from ..api import HttpMethod
-from ..api import PaginationConfigMap
+from ..api import PaginationConfigDict
 from ..api import RequestOptions
 from ..api import compose_api_request_env
 from ..api import paginate_with_client
@@ -160,7 +160,7 @@ def _extract_from_api_env(
 
         return client.paginate_url(
             cast(str, url),
-            cast(PaginationConfigMap | None, env.get('pagination')),
+            cast(PaginationConfigDict | None, env.get('pagination')),
             request=request_options,
             sleep_seconds=cast(float, env.get('sleep_seconds', 0.0)),
         )

etlplus/ops/utils.py

@@ -26,7 +26,7 @@ from ..utils import normalize_choice
 # SECTION: TYPED DICTIONARIES =============================================== #
 
 
-class ValidationResult(TypedDict, total=False):
+class ValidationResultDict(TypedDict, total=False):
     """Shape returned by ``validate_fn`` callables."""
 
     valid: bool
@@ -44,7 +44,7 @@ type ValidationPhase = Literal['before_transform', 'after_transform']
 type ValidationWindow = Literal['before_transform', 'after_transform', 'both']
 type ValidationSeverity = Literal['warn', 'error']
 
-type ValidateFn = Callable[[Any, Ruleset], ValidationResult]
+type ValidateFn = Callable[[Any, Ruleset], ValidationResultDict]
 type PrintFn = Callable[[Any], None]
 
 
@@ -198,7 +198,7 @@ def maybe_validate(
         Failure severity (``"warn"`` or ``"error"``).
     validate_fn : ValidateFn
         Engine that performs validation and returns a
-        :class:`ValidationResult` instance.
+        :class:`ValidationResultDict` instance.
     print_json_fn : PrintFn
         Structured logger invoked when validation fails.
 
@@ -270,7 +270,7 @@ def _log_failure(
     phase: ValidationPhase,
     window: ValidationWindow,
     ruleset_name: str | None,
-    result: ValidationResult,
+    result: ValidationResultDict,
 ) -> None:
     """
     Emit a structured message describing the failed validation.
@@ -285,7 +285,7 @@ def _log_failure(
         Configured validation window.
     ruleset_name : str | None
         Name of the validation ruleset.
-    result : ValidationResult
+    result : ValidationResultDict
         Result of the failed validation.
     """
     printer(