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

etlplus/api/rate_limiting/config.py

@@ -41,7 +41,7 @@ __all__ = [
     # Type Aliases
     'RateLimitOverrides',
     # Typed Dicts
-    'RateLimitConfigMap',
+    'RateLimitConfigDict',
 ]
 
 
@@ -50,9 +50,9 @@ __all__ = [
 
 def _coerce_rate_limit_map(
     rate_limit: StrAnyMap | RateLimitConfig | None,
-) -> RateLimitConfigMap | None:
+) -> RateLimitConfigDict | None:
     """
-    Normalize user inputs into a :class:`RateLimitConfigMap`.
+    Normalize user inputs into a :class:`RateLimitConfigDict`.
 
     This helper is the single entry point for converting loosely-typed
     configuration into the canonical mapping consumed by downstream
@@ -65,7 +65,7 @@ def _coerce_rate_limit_map(
 
     Returns
     -------
-    RateLimitConfigMap | None
+    RateLimitConfigDict | None
         Normalized mapping, or ``None`` if input couldn't be parsed.
     """
     if rate_limit is None:
@@ -84,14 +84,14 @@ def _merge_rate_limit(
     overrides: RateLimitOverrides = None,
 ) -> dict[str, Any]:
     """
-    Merge ``rate_limit`` and ``overrides`` honoring override precedence.
+    Merge *rate_limit* and *overrides* honoring override precedence.
 
     Parameters
     ----------
     rate_limit : StrAnyMap | None
         Base rate-limit configuration.
     overrides : RateLimitOverrides, optional
-        Override configuration with precedence over ``rate_limit``.
+        Override configuration with precedence over *rate_limit*.
 
     Returns
     -------
@@ -133,7 +133,7 @@ def _normalized_rate_values(
 # SECTION: TYPED DICTS ====================================================== #
 
 
-class RateLimitConfigMap(TypedDict, total=False):
+class RateLimitConfigDict(TypedDict, total=False):
     """
     Configuration mapping for HTTP request rate limits.
 
@@ -149,7 +149,7 @@ class RateLimitConfigMap(TypedDict, total=False):
 
     Examples
     --------
-    >>> rl: RateLimitConfigMap = {'max_per_sec': 4}
+    >>> rl: RateLimitConfigDict = {'max_per_sec': 4}
     ... # sleep ~= 0.25s between calls
     """
 
@@ -197,9 +197,9 @@ class RateLimitConfig(BoundsWarningsMixin):
 
     # -- Instance Methods -- #
 
-    def as_mapping(self) -> RateLimitConfigMap:
+    def as_mapping(self) -> RateLimitConfigDict:
         """Return a normalized mapping consumable by rate-limit helpers."""
-        cfg: RateLimitConfigMap = {}
+        cfg: RateLimitConfigDict = {}
         if (sleep := to_float(self.sleep_seconds)) is not None:
             cfg['sleep_seconds'] = sleep
         if (rate := to_float(self.max_per_sec)) is not None:
@@ -274,7 +274,7 @@ class RateLimitConfig(BoundsWarningsMixin):
         rate_limit : StrAnyMap | RateLimitConfig | None, optional
             Base rate-limit configuration to normalize.
         overrides : RateLimitOverrides, optional
-            Override values that take precedence over ``rate_limit``.
+            Override values that take precedence over *rate_limit*.
 
         Returns
         -------
@@ -309,7 +309,7 @@ class RateLimitConfig(BoundsWarningsMixin):
     @overload
     def from_obj(
         cls,
-        obj: RateLimitConfigMap,
+        obj: RateLimitConfigDict,
     ) -> Self: ...
 
     @classmethod
@@ -330,7 +330,7 @@ class RateLimitConfig(BoundsWarningsMixin):
         Returns
         -------
         Self | None
-            Parsed instance, or ``None`` if ``obj`` isn't a mapping.
+            Parsed instance, or ``None`` if *obj* isn't a mapping.
         """
         if obj is None:
             return None
@@ -352,4 +352,4 @@ class RateLimitConfig(BoundsWarningsMixin):
 type RateLimitInput = StrAnyMap | RateLimitConfig | None
 
 # Optional mapping of rate-limit fields to override values.
-type RateLimitOverrides = RateLimitConfigMap | None
+type RateLimitOverrides = RateLimitConfigDict | None

etlplus/api/rate_limiting/rate_limiter.py

@@ -25,7 +25,7 @@ from typing import Self
 from ...utils import to_float
 from ...utils import to_positive_float
 from .config import RateLimitConfig
-from .config import RateLimitConfigMap
+from .config import RateLimitConfigDict
 from .config import RateLimitInput
 from .config import RateLimitOverrides
 
@@ -38,7 +38,7 @@ __all__ = [
     # Data Classes
     'RateLimitConfig',
     # Typed Dicts
-    'RateLimitConfigMap',
+    'RateLimitConfigDict',
 ]
 
 
@@ -235,7 +235,7 @@ class RateLimiter:
             Base rate-limit configuration. May contain ``"sleep_seconds"`` or
             ``"max_per_sec"``.
         overrides : RateLimitOverrides, optional
-            Optional overrides with the same keys as ``rate_limit``.
+            Optional overrides with the same keys as *rate_limit*.
 
         Returns
         -------

etlplus/api/request_manager.py

@@ -28,7 +28,7 @@ from .errors import ApiAuthError
 from .errors import ApiRequestError
 from .retry_manager import RetryInput
 from .retry_manager import RetryManager
-from .transport import HTTPAdapterMountConfig
+from .transport import HTTPAdapterMountConfigDict
 from .transport import build_session_with_adapters
 
 # SECTION: TYPE ALIASES ==================================================== #
@@ -68,7 +68,7 @@ class RequestManager:
         ``None``.
     retry_cap : float, optional
         Maximum backoff cap in seconds. Default is 30.0.
-    session_adapters : Sequence[HTTPAdapterMountConfig] | None, optional
+    session_adapters : Sequence[HTTPAdapterMountConfigDict] | None, optional
         Adapter mount configurations used when lazily building a session via
         :func:`etlplus.api.transport.build_session_with_adapters`.
 
@@ -86,7 +86,7 @@ class RequestManager:
         Optional factory for creating sessions.
     retry_cap : float
         Maximum backoff cap in seconds for :class:`RetryManager` sleeps.
-    session_adapters : Sequence[HTTPAdapterMountConfig] | None
+    session_adapters : Sequence[HTTPAdapterMountConfigDict] | None
         Adapter mount configurations used when lazily building a session.
     """
 
@@ -98,7 +98,7 @@ class RequestManager:
     session: requests.Session | None = None
     session_factory: Callable[[], requests.Session] | None = None
     retry_cap: float = 30.0
-    session_adapters: Sequence[HTTPAdapterMountConfig] | None = None
+    session_adapters: Sequence[HTTPAdapterMountConfigDict] | None = None
 
     def __post_init__(self) -> None:
         if self.session_adapters:

etlplus/api/retry_manager.py

@@ -47,7 +47,7 @@ __all__ = [
     'RetryStrategy',
     'RetryManager',
     # Typed Dicts
-    'RetryPolicy',
+    'RetryPolicyDict',
     # Type Aliases
     'RetryInput',
 ]
@@ -69,7 +69,7 @@ DEFAULT_RETRY_STATUS_CODES: Final[frozenset[int]] = frozenset(
 # SECTION: TYPED DICTS ====================================================== #
 
 
-class RetryPolicy(TypedDict, total=False):
+class RetryPolicyDict(TypedDict, total=False):
     """
     Optional retry policy for HTTP requests.
 
@@ -100,7 +100,7 @@ class RetryPolicy(TypedDict, total=False):
 # SECTION: TYPE ALIASES ===================================================== #
 
 
-type RetryInput = RetryPolicy | None
+type RetryInput = RetryPolicyDict | None
 
 
 # SECTION: DATA CLASSES ===================================================== #
@@ -108,7 +108,7 @@ type RetryInput = RetryPolicy | None
 
 @dataclass(frozen=True, slots=True)
 class RetryStrategy:
-    """Normalized retry settings derived from a :class:`RetryPolicy`."""
+    """Normalized retry settings derived from a :class:`RetryPolicyDict`."""
 
     # -- Attributes -- #
 
@@ -171,7 +171,7 @@ class RetryManager:
         Default HTTP status codes considered retryable.
     DEFAULT_CAP : ClassVar[float]
         Default maximum sleep seconds for jittered backoff.
-    policy : RetryPolicy
+    policy : RetryPolicyDict
         Retry policy configuration.
     retry_network_errors : bool
         Whether to retry on network errors (timeouts, connection errors).
@@ -191,7 +191,7 @@ class RetryManager:
 
     # -- Instance Attributes-- #
 
-    policy: RetryPolicy
+    policy: RetryPolicyDict
     retry_network_errors: bool = False
     cap: float = DEFAULT_CAP
     sleeper: Sleeper = time.sleep
@@ -278,7 +278,7 @@ class RetryManager:
         **kwargs: Any,
     ) -> JSONData:
         """
-        Execute ``func`` with exponential-backoff retries.
+        Execute *func* with exponential-backoff retries.
 
         Parameters
         ----------
@@ -287,7 +287,7 @@ class RetryManager:
         url : str
             URL for the API request.
         **kwargs : Any
-            Additional keyword arguments to pass to ``func``
+            Additional keyword arguments to pass to *func*
 
         Returns
         -------

etlplus/api/transport.py

@@ -41,8 +41,8 @@ from ..utils import to_positive_int
 
 __all__ = [
     # Classes
-    'HTTPAdapterMountConfig',
-    'HTTPAdapterRetryConfig',
+    'HTTPAdapterMountConfigDict',
+    'HTTPAdapterRetryConfigDict',
     # Functions
     'build_http_adapter',
     'build_session_with_adapters',
@@ -52,7 +52,7 @@ __all__ = [
 # SECTION: TYPED DICTS ====================================================== #
 
 
-class HTTPAdapterRetryConfig(TypedDict, total=False):
+class HTTPAdapterRetryConfigDict(TypedDict, total=False):
     """
     Retry configuration for urllib3 ``Retry``.
 
@@ -89,7 +89,7 @@ class HTTPAdapterRetryConfig(TypedDict, total=False):
 
     Examples
     --------
-    >>> retry_cfg: HTTPAdapterRetryConfig = {
+    >>> retry_cfg: HTTPAdapterRetryConfigDict = {
     ...     'total': 5,
     ...     'backoff_factor': 0.5,
     ...     'status_forcelist': [429, 503],
@@ -111,7 +111,7 @@ class HTTPAdapterRetryConfig(TypedDict, total=False):
     respect_retry_after_header: bool
 
 
-class HTTPAdapterMountConfig(TypedDict, total=False):
+class HTTPAdapterMountConfigDict(TypedDict, total=False):
     """
     Configuration mapping for mounting an ``HTTPAdapter`` on a ``Session``.
 
@@ -132,13 +132,13 @@ class HTTPAdapterMountConfig(TypedDict, total=False):
     pool_block : bool
         Whether the pool should block for connections instead of creating new
         ones.
-    max_retries : int | HTTPAdapterRetryConfig
+    max_retries : int | HTTPAdapterRetryConfigDict
         Retry configuration passed to ``HTTPAdapter`` (int) or converted to
         ``Retry``.
 
     Examples
     --------
-    >>> adapter_cfg: HTTPAdapterMountConfig = {
+    >>> adapter_cfg: HTTPAdapterMountConfigDict = {
     ...     'prefix': 'https://',
     ...     'pool_connections': 10,
     ...     'pool_maxsize': 10,
@@ -156,7 +156,7 @@ class HTTPAdapterMountConfig(TypedDict, total=False):
     pool_connections: int
     pool_maxsize: int
     pool_block: bool
-    max_retries: int | HTTPAdapterRetryConfig
+    max_retries: int | HTTPAdapterRetryConfigDict
 
 
 # SECTION: INTERNAL FUNCTIONS ============================================== #
@@ -306,17 +306,17 @@ def build_http_adapter(
 
 
 def build_session_with_adapters(
-    adapters_cfg: Sequence[HTTPAdapterMountConfig],
+    adapters_cfg: Sequence[HTTPAdapterMountConfigDict],
 ) -> requests.Session:
     """
-    Mount adapters described by ``adapters_cfg`` onto a new session.
+    Mount adapters described by *adapters_cfg* onto a new session.
 
     Ignores invalid adapter configurations so that a usable session is always
     returned.
 
     Parameters
     ----------
-    adapters_cfg : Sequence[HTTPAdapterMountConfig]
+    adapters_cfg : Sequence[HTTPAdapterMountConfigDict]
         Configuration mappings describing the adapter prefix, pooling
         values, and retry policy for each mounted adapter.
 

etlplus/api/types.py

@@ -20,9 +20,11 @@ Examples
 from __future__ import annotations
 
 from collections.abc import Callable
+from collections.abc import Mapping
 from dataclasses import dataclass
 from typing import Any
 from typing import Self
+from typing import TypedDict
 from typing import cast
 
 from ..types import JSONData
@@ -40,13 +42,134 @@ __all__ = [
     'Headers',
     'Params',
     'Url',
+    # Typed Dicts
+    'ApiConfigDict',
+    'ApiProfileConfigDict',
+    'ApiProfileDefaultsDict',
+    'EndpointConfigDict',
 ]
 
 
 # SECTION: CONSTANTS ======================================================== #
 
 
-_UNSET = object()
+_UNSET: object = object()
+
+
+# SECTION: INTERNAL FUNCTIONS =============================================== #
+
+
+def _to_dict(
+    value: Mapping[str, Any] | object | None,
+) -> dict[str, Any] | None:
+    """
+    Return a defensive ``dict`` copy for mapping inputs.
+
+    Parameters
+    ----------
+    value : Mapping[str, Any] | object | None
+        Mapping to copy, or ``None``.
+
+    Returns
+    -------
+    dict[str, Any] | None
+        New ``dict`` instance or ``None`` when the input is ``None``.
+    """
+    if value is None:
+        return None
+    return cast(dict[str, Any], value)
+
+
+# SECTION: TYPED DICTS ====================================================== #
+
+
+class ApiConfigDict(TypedDict, total=False):
+    """
+    Top-level API config shape parsed by
+    :meth:`etlplus.api.config.ApiConfig.from_obj`.
+
+    Either provide a :attr:`base_url` with optional :attr:`headers` and
+    :attr:`endpoints`, or provide :attr:`profiles` with at least one profile
+    having a :attr:`base_url`.
+
+    See Also
+    --------
+    - :class:`etlplus.api.config.ApiConfig`
+    """
+
+    base_url: str
+    headers: StrAnyMap
+    endpoints: Mapping[str, EndpointConfigDict | str]
+    profiles: Mapping[str, ApiProfileConfigDict]
+
+
+class ApiProfileConfigDict(TypedDict, total=False):
+    """
+    Shape accepted for a profile entry under
+    :meth:`etlplus.api.config.ApiConfig.from_obj`.
+
+    Notes
+    -----
+    - :attr:`base_url` is required at runtime when :attr:`profiles` key/value
+        pairs are provided.
+    - :meth:`etlplus.api.config.ApiProfileConfig.from_obj` parses this mapping.
+
+    See Also
+    --------
+    - :class:`etlplus.api.config.ApiProfileConfig`
+    """
+
+    base_url: str
+    headers: StrAnyMap
+    base_path: str
+    auth: StrAnyMap
+    defaults: ApiProfileDefaultsDict
+
+
+class ApiProfileDefaultsDict(TypedDict, total=False):
+    """
+    Defaults block available under a profile (all keys optional).
+
+    Notes
+    -----
+    - Runtime expects header values to be ``str``; typing remains permissive.
+    - :meth:`etlplus.api.config.ApiProfileConfig.from_obj` consumes this block.
+    - :meth:`etlplus.api.pagination.PaginationConfig.from_obj` parses
+        :attr:`pagination`.
+    - :meth:`etlplus.api.rate_limiting.RateLimitConfig.from_obj` parses
+        :attr:`rate_limit`.
+
+    See Also
+    --------
+    - :class:`etlplus.api.config.ApiProfileConfig`
+    - :class:`etlplus.api.pagination.PaginationConfig`
+    - :class:`etlplus.api.rate_limiting.RateLimitConfig`
+    """
+
+    headers: StrAnyMap
+    pagination: StrAnyMap  # PaginationConfigDict | StrAnyMap
+    rate_limit: StrAnyMap  # RateLimitConfigDict | StrAnyMap
+
+
+class EndpointConfigDict(TypedDict, total=False):
+    """
+    Shape accepted by :meth:`etlplus.api.config.EndpointConfig.from_obj`.
+
+    One of :attr:`path` or :attr:`url` should be provided.
+
+    See Also
+    --------
+    - :class:`etlplus.api.config.EndpointConfig`
+    """
+
+    path: str
+    url: str
+    method: str
+    path_params: StrAnyMap
+    query_params: StrAnyMap
+    body: Any
+    pagination: StrAnyMap  # PaginationConfigDict | StrAnyMap
+    rate_limit: StrAnyMap  # RateLimitConfigDict | StrAnyMap
 
 
 # SECTION: DATA CLASSES ===================================================== #
@@ -77,9 +200,9 @@ class RequestOptions:
 
     def __post_init__(self) -> None:
         if self.params is not None:
-            object.__setattr__(self, 'params', dict(self.params))
+            object.__setattr__(self, 'params', _to_dict(self.params))
         if self.headers is not None:
-            object.__setattr__(self, 'headers', dict(self.headers))
+            object.__setattr__(self, 'headers', _to_dict(self.headers))
 
     # -- Instance Methods -- #
 
@@ -125,23 +248,20 @@ class RequestOptions:
 
         Returns
         -------
-        RequestOptions
+        Self
             New snapshot reflecting the provided overrides.
         """
         if params is _UNSET:
             next_params = self.params
-        elif params is None:
-            next_params = None
         else:
-            next_params = cast(dict, params)
+            # next_params = _to_dict(params) if params is not None else None
+            next_params = _to_dict(params)
 
         if headers is _UNSET:
             next_headers = self.headers
-        elif headers is None:
-            next_headers = None
         else:
-            next_headers = cast(dict, headers)
-
+            # next_headers = _to_dict(headers) if headers is not None else None
+            next_headers = _to_dict(headers)
         if timeout is _UNSET:
             next_timeout = self.timeout
         else: