etlplus 0.9.2__py3-none-any.whl → 0.10.1__py3-none-any.whl

etlplus/{api/utils.py → run_helpers.py}

@@ -1,13 +1,30 @@
 """
-:mod:`etlplus.api.utils` module.
-
-Shared HTTP helpers for API clients that communicate with REST endpoints.
+:mod:`etlplus.run_helpers` module.
+
+Helper functions and small utilities used by ``etlplus.run`` to compose API
+request/load environments, pagination configs, session objects, and endpoint
+clients. Extracted to keep ``run.py`` focused on orchestration while enabling
+reuse and testability.
+
+Public (re-export safe) helpers:
+- build_pagination_cfg(pagination, overrides)
+- build_session(cfg)
+- compose_api_request_env(cfg, source_obj, extract_opts)
+- compose_api_target_env(cfg, target_obj, overrides)
+- build_endpoint_client(base_url, base_path, endpoints, env)
+- compute_rl_sleep_seconds(rate_limit, overrides)
+- paginate_with_client(client, endpoint_key, params, headers,
+    timeout, pagination, sleep_seconds)
+
+Notes
+-----
+These helpers intentionally accept permissive ``Any``/``Mapping`` inputs to
+avoid tight coupling with config dataclasses while keeping runtime flexible.
 """
 
 from __future__ import annotations
 
 import inspect
-from collections.abc import Callable
 from collections.abc import Mapping
 from typing import Any
 from typing import TypedDict
@@ -15,34 +32,24 @@ from typing import cast
 
 import requests  # type: ignore[import]
 
-from ..types import Timeout
-from ..utils import coerce_dict
-from .config import ApiConfig
-from .config import EndpointConfig
-from .endpoint_client import EndpointClient
-from .enums import HttpMethod
-from .pagination import PaginationConfig
-from .pagination import PaginationConfigMap
-from .rate_limiting import RateLimitConfig
-from .rate_limiting import RateLimitConfigMap
-from .rate_limiting import RateLimiter
-from .retry_manager import RetryPolicy
-from .types import Headers
-from .types import Params
-from .types import Url
-
-# SECTION: CONSTANTS ======================================================== #
-
-
-DEFAULT_TIMEOUT: float = 10.0
-
+from .api import ApiConfig
+from .api import EndpointClient
+from .api import EndpointConfig
+from .api import Headers
+from .api import PaginationConfig
+from .api import PaginationConfigMap
+from .api import Params
+from .api import RateLimitConfig
+from .api import RateLimitConfigMap
+from .api import RateLimiter
+from .api import RetryPolicy
+from .api import Url
+from .types import Timeout
 
 # SECTION: EXPORTS ========================================================== #
 
 
 __all__ = [
-    # Constants
-    'DEFAULT_TIMEOUT',
     # Functions
     'build_endpoint_client',
     'build_pagination_cfg',
@@ -51,7 +58,6 @@ __all__ = [
     'compose_api_target_env',
     'compute_rl_sleep_seconds',
     'paginate_with_client',
-    'resolve_request',
     # Typed Dicts
     'ApiRequestEnv',
     'ApiTargetEnv',
@@ -62,83 +68,43 @@ __all__ = [
 # SECTION: TYPED DICTS ====================================================== #
 
 
-class BaseApiHttpEnv(TypedDict, total=False):
-    """
-    Common HTTP request environment for API interactions.
-
-    Fields shared by both source-side and target-side API operations.
-    """
+class ApiRequestEnv(TypedDict, total=False):
+    """API request environment configuration."""
 
-    # Request details
     url: Url | None
     headers: dict[str, str]
     timeout: Timeout
-
-    # Session
     session: requests.Session | None
-
-
-class ApiRequestEnv(BaseApiHttpEnv, total=False):
-    """
-    Composed HTTP request environment configuration for REST API sources.
-
-    Returned by :func:`compose_api_request_env` and consumed by the API extract
-    branch. Values are fully merged with endpoint/API defaults and job-level
-    overrides, preserving the original precedence and behavior.
-    """
-
-    # Client
     use_endpoints: bool
     base_url: str | None
     base_path: str | None
     endpoints_map: dict[str, str] | None
     endpoint_key: str | None
-
-    # Request
     params: dict[str, Any]
     pagination: PaginationConfigMap | None
     sleep_seconds: float
-
-    # Reliability
     retry: RetryPolicy | None
     retry_network_errors: bool
 
 
-class ApiTargetEnv(BaseApiHttpEnv, total=False):
-    """
-    Composed HTTP request environment configuration for REST API targets.
-
-    Returned by :func:`compose_api_target_env` and consumed by the API load
-    branch. Values are merged from the target object, optional API/endpoint
-    reference, and job-level overrides, preserving original precedence and
-    behavior.
-
-    Notes
-    -----
-    - Precedence for inherited values matches original logic:
-        overrides -> target -> API profile defaults.
-    - Target composition does not include pagination/rate-limit/retry since
-        loads are single-request operations; only headers/timeout/session
-        apply.
-    """
+class ApiTargetEnv(TypedDict, total=False):
+    """API target environment configuration."""
 
-    # Request
+    url: Url | None
+    headers: dict[str, str]
+    timeout: Timeout
+    session: requests.Session | None
     method: str | None
 
 
 class SessionConfig(TypedDict, total=False):
-    """
-    Minimal session configuration schema accepted by the
-    :class:`requests.Session` runner.
-
-    Keys mirror common :class:`requests.Session` options; all are optional.
-    """
+    """Configuration for requests.Session."""
 
     headers: Mapping[str, Any]
     params: Mapping[str, Any]
-    auth: Any  # (user, pass) tuple or requests-compatible auth object
+    auth: Any
     verify: bool | str
-    cert: Any  # str or (cert, key)
+    cert: Any
     proxies: Mapping[str, Any]
     cookies: Mapping[str, Any]
     trust_env: bool
@@ -147,47 +113,7 @@ class SessionConfig(TypedDict, total=False):
 # SECTION: INTERNAL FUNCTIONS ============================================== #
 
 
-def _build_session_optional(
-    cfg: SessionConfig | None,
-) -> requests.Session | None:
-    """
-    Return a configured session when *cfg* is a mapping.
-
-    Parameters
-    ----------
-    cfg : SessionConfig | None
-        Session configuration mapping.
-
-    Returns
-    -------
-    requests.Session | None
-        Configured session or ``None``.
-    """
-    if isinstance(cfg, Mapping):
-        return build_session(cast(SessionConfig, cfg))
-    return None
-
-
-def _coalesce(
-    *args: Any,
-) -> Any | None:
-    """
-    Return the first non-``None`` value from ``args``.
-
-    Parameters
-    ----------
-    *args : Any
-        Candidate values in descending precedence order.
-
-    Returns
-    -------
-    Any | None
-        The first non-``None`` value, or ``None`` if all are ``None``.
-    """
-    for arg in args:
-        if arg is not None:
-            return arg
-    return None
+# -- API Environment Composition -- #
 
 
 def _get_api_cfg_and_endpoint(
@@ -291,15 +217,37 @@ def _merge_session_cfg_three(
     api_sess = getattr(api_cfg, 'session', None)
     ep_sess = getattr(ep, 'session', None)
     merged: dict[str, Any] = {}
-    if isinstance(api_sess, Mapping):
+    if isinstance(api_sess, dict):
         merged.update(api_sess)
-    if isinstance(ep_sess, Mapping):
+    if isinstance(ep_sess, dict):
         merged.update(ep_sess)
-    if isinstance(source_session_cfg, Mapping):
+    if isinstance(source_session_cfg, dict):
         merged.update(source_session_cfg)
     return cast(SessionConfig | None, (merged or None))
 
 
+# -- Mapping Helpers -- #
+
+
+def _copy_mapping(
+    mapping: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    """
+    Return a shallow copy of *mapping* or an empty dict.
+
+    Parameters
+    ----------
+    mapping : Mapping[str, Any] | None
+        The mapping to copy.
+
+    Returns
+    -------
+    dict[str, Any]
+        A shallow copy of the mapping or an empty dict.
+    """
+    return dict(mapping) if isinstance(mapping, Mapping) else {}
+
+
 def _update_mapping(
     target: dict[str, Any],
     extra: Mapping[str, Any] | None,
@@ -318,9 +266,37 @@ def _update_mapping(
         target.update(extra)
 
 
+# -- Session -- #
+
+
+def _build_session_optional(
+    cfg: SessionConfig | None,
+) -> requests.Session | None:
+    """
+    Return a configured session when *cfg* is a mapping.
+
+    Parameters
+    ----------
+    cfg : SessionConfig | None
+        Session configuration mapping.
+
+    Returns
+    -------
+    requests.Session | None
+        Configured session or ``None``.
+    """
+
+    if isinstance(cfg, dict):
+        return build_session(cfg)
+    return None
+
+
 # SECTION: FUNCTIONS ======================================================== #
 
 
+# -- API Environment Composition -- #
+
+
 def build_endpoint_client(
     *,
     base_url: str,
@@ -347,7 +323,15 @@ def build_endpoint_client(
     EndpointClient
         The constructed endpoint client.
     """
-    return EndpointClient(
+    # Allow tests to monkeypatch etlplus.run.EndpointClient and have it
+    # propagate here by preferring the class on the run module if present.
+    try:
+        from . import run as run_mod  # local import to avoid cycles
+
+        ClientClass = getattr(run_mod, 'EndpointClient', EndpointClient)
+    except (ImportError, AttributeError):  # pragma: no cover - fallback path
+        ClientClass = EndpointClient
+    return ClientClass(
         base_url=base_url,
         base_path=base_path,
         endpoints=endpoints,
@@ -385,19 +369,21 @@ def compose_api_request_env(
         Mapping[str, Any] | None,
         getattr(source_obj, 'query_params', None),
     )
-    params: dict[str, Any] = coerce_dict(source_params)
+    params: dict[str, Any] = _copy_mapping(source_params)
     source_headers = cast(
         Mapping[str, str] | None,
         getattr(source_obj, 'headers', None),
     )
-    headers: dict[str, str] = cast(dict[str, str], coerce_dict(source_headers))
+    headers: dict[str, str] = _copy_mapping(source_headers)
     pagination = getattr(source_obj, 'pagination', None)
     rate_limit = getattr(source_obj, 'rate_limit', None)
     retry: RetryPolicy | None = cast(
         RetryPolicy | None,
         getattr(source_obj, 'retry', None),
     )
-    retry_network_errors = getattr(source_obj, 'retry_network_errors', None)
+    retry_network_errors = bool(
+        getattr(source_obj, 'retry_network_errors', False),
+    )
     session_cfg = cast(
         SessionConfig | None,
         getattr(source_obj, 'session', None),
@@ -419,33 +405,33 @@ def compose_api_request_env(
             session_cfg,
             force_url=True,
         )
-        ep_params: dict[str, Any] = coerce_dict(
+        ep_params: dict[str, Any] = _copy_mapping(
             cast(Mapping[str, Any] | None, getattr(ep, 'query_params', None)),
         )
         _update_mapping(ep_params, params)
         params = ep_params
-        pagination = _coalesce(
-            pagination,
-            ep.pagination,
-            api_cfg.effective_pagination_defaults(),
+        pagination = (
+            pagination
+            or ep.pagination
+            or api_cfg.effective_pagination_defaults()
         )
-        rate_limit = _coalesce(
-            rate_limit,
-            ep.rate_limit,
-            api_cfg.effective_rate_limit_defaults(),
+        rate_limit = (
+            rate_limit
+            or ep.rate_limit
+            or api_cfg.effective_rate_limit_defaults()
         )
         retry = cast(
             RetryPolicy | None,
-            _coalesce(
-                retry,
-                getattr(ep, 'retry', None),
-                getattr(api_cfg, 'retry', None),
+            (
+                retry
+                or getattr(ep, 'retry', None)
+                or getattr(api_cfg, 'retry', None)
             ),
         )
-        retry_network_errors = _coalesce(
-            retry_network_errors,
-            getattr(ep, 'retry_network_errors', None),
-            getattr(api_cfg, 'retry_network_errors', None),
+        retry_network_errors = (
+            retry_network_errors
+            or bool(getattr(ep, 'retry_network_errors', False))
+            or bool(getattr(api_cfg, 'retry_network_errors', False))
         )
         use_client_endpoints = True
         client_base_url = api_cfg.base_url
@@ -480,10 +466,8 @@ def compose_api_request_env(
         retry = rty_ov
     if rne_ov is not None:
         retry_network_errors = bool(rne_ov)
-    if isinstance(sess_ov, Mapping):
-        base_cfg: dict[str, Any] = dict(
-            cast(Mapping[str, Any], session_cfg or {}),
-        )
+    if isinstance(sess_ov, dict):
+        base_cfg: dict[str, Any] = dict(cast(dict, session_cfg or {}))
         base_cfg.update(sess_ov)
         session_cfg = cast(SessionConfig, base_cfg)
     pag_cfg: PaginationConfigMap | None = build_pagination_cfg(
@@ -504,7 +488,7 @@ def compose_api_request_env(
         'pagination': pag_cfg,
         'sleep_seconds': sleep_s,
         'retry': retry,
-        'retry_network_errors': bool(retry_network_errors),
+        'retry_network_errors': retry_network_errors,
         'session': sess_obj,
     }
 
@@ -540,14 +524,8 @@ def compose_api_target_env(
         str | None,
         ov.get('method') or getattr(target_obj, 'method', 'post'),
     )
-    headers = cast(
-        dict[str, str],
-        coerce_dict(
-            cast(
-                Mapping[str, str] | None,
-                getattr(target_obj, 'headers', None),
-            ),
-        ),
+    headers = _copy_mapping(
+        cast(Mapping[str, str] | None, getattr(target_obj, 'headers', None)),
     )
     _update_mapping(headers, cast(Mapping[str, str] | None, ov.get('headers')))
     timeout: Timeout = (
@@ -580,6 +558,9 @@ def compose_api_target_env(
     }
 
 
+# -- Pagination -- #
+
+
 def build_pagination_cfg(
     pagination: PaginationConfig | None,
     overrides: Mapping[str, Any] | None,
@@ -686,6 +667,9 @@ def build_pagination_cfg(
     return cast(PaginationConfigMap, cfg)
 
 
+# -- Pagination Invocation -- #
+
+
 def paginate_with_client(
     client: Any,
     endpoint_key: str,
@@ -743,6 +727,9 @@ def paginate_with_client(
     return client.paginate(endpoint_key, **kw_pag)
 
 
+# -- Rate Limit -- #
+
+
 def compute_rl_sleep_seconds(
     rate_limit: RateLimitConfig | Mapping[str, Any] | None,
     overrides: Mapping[str, Any] | None,
@@ -795,6 +782,9 @@ def compute_rl_sleep_seconds(
     )
 
 
+# -- Session -- #
+
+
 def build_session(
     cfg: SessionConfig | None,
 ) -> requests.Session:
@@ -815,12 +805,12 @@ def build_session(
     if not cfg:
         return s
     headers = cfg.get('headers')
-    if isinstance(headers, Mapping):
+    if isinstance(headers, dict):
         s.headers.update(headers)
     params = cfg.get('params')
-    if isinstance(params, Mapping):
+    if isinstance(params, dict):
         try:
-            s.params = dict(params)
+            s.params = params
         except (AttributeError, TypeError):
             pass
     auth = cfg.get('auth')
@@ -835,12 +825,12 @@ def build_session(
     if cert is not None:
         s.cert = cert  # type: ignore[assignment]
     proxies = cfg.get('proxies')
-    if isinstance(proxies, Mapping):
+    if isinstance(proxies, dict):
         s.proxies.update(proxies)
     cookies = cfg.get('cookies')
-    if isinstance(cookies, Mapping):
+    if isinstance(cookies, dict):
         try:
-            s.cookies.update(cast(Mapping[str, Any], cookies))
+            s.cookies.update(cookies)
         except (TypeError, ValueError):
             pass
     if 'trust_env' in cfg:
@@ -851,49 +841,3 @@ def build_session(
             pass
 
     return s
-
-
-def resolve_request(
-    method: HttpMethod | str,
-    *,
-    session: Any | None = None,
-    timeout: Timeout = None,
-) -> tuple[Callable[..., requests.Response], float, HttpMethod]:
-    """
-    Resolve a request callable and effective timeout for an HTTP method.
-
-    Parameters
-    ----------
-    method : HttpMethod | str
-        HTTP method to execute.
-    session : Any | None, optional
-        Requests-compatible session object. Defaults to module-level
-        ``requests``.
-    timeout : Timeout, optional
-        Timeout in seconds for the request. Uses ``DEFAULT_TIMEOUT`` when
-        omitted.
-
-    Returns
-    -------
-    tuple[Callable[..., requests.Response], float, HttpMethod]
-        Tuple of (callable, timeout_seconds, resolved_method).
-
-    Raises
-    ------
-    TypeError
-        If the session object does not expose the requested HTTP method.
-    """
-    http_method = HttpMethod.coerce(method)
-    request_timeout = DEFAULT_TIMEOUT if timeout is None else timeout
-    requester = session or requests
-    request_callable = getattr(requester, http_method.value, None)
-    if not callable(request_callable):
-        raise TypeError(
-            'Session object must supply a callable '
-            f'"{http_method.value}" method',
-        )
-    typed_request_callable = cast(
-        Callable[..., requests.Response],
-        request_callable,
-    )
-    return typed_request_callable, request_timeout, http_method