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

etlplus/api/types.py

@@ -20,8 +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
@@ -39,6 +42,11 @@ __all__ = [
     'Headers',
     'Params',
     'Url',
+    # Typed Dicts
+    'ApiConfigMap',
+    'ApiProfileConfigMap',
+    'ApiProfileDefaultsMap',
+    'EndpointMap',
 ]
 
 
@@ -48,6 +56,88 @@ __all__ = [
 _UNSET = object()
 
 
+# SECTION: TYPED DICTS ====================================================== #
+
+
+class ApiConfigMap(TypedDict, total=False):
+    """
+    Top-level API config shape parsed by ApiConfig.from_obj.
+
+    Either provide a ``base_url`` with optional ``headers`` and ``endpoints``,
+    or provide ``profiles`` with at least one profile having a ``base_url``.
+
+    See Also
+    --------
+    - :class:`etlplus.api.config.ApiConfig`
+    """
+
+    base_url: str
+    headers: StrAnyMap
+    endpoints: Mapping[str, EndpointMap | str]
+    profiles: Mapping[str, ApiProfileConfigMap]
+
+
+class ApiProfileConfigMap(TypedDict, total=False):
+    """
+    Shape accepted for a profile entry under ApiConfigMap.profiles.
+
+    Notes
+    -----
+    ``base_url`` is required at runtime when profiles are provided.
+
+    See Also
+    --------
+    - :class:`etlplus.api.config.ApiProfileConfig`
+    """
+
+    base_url: str
+    headers: StrAnyMap
+    base_path: str
+    auth: StrAnyMap
+    defaults: ApiProfileDefaultsMap
+
+
+class ApiProfileDefaultsMap(TypedDict, total=False):
+    """
+    Defaults block available under a profile (all keys optional).
+
+    Notes
+    -----
+    Runtime expects header values to be str; typing remains permissive.
+
+    See Also
+    --------
+    - :class:`etlplus.api.config.ApiProfileConfig`
+    - :class:`etlplus.api.pagination.PaginationConfig`
+    - :class:`etlplus.api.rate_limiting.RateLimitConfig`
+    """
+
+    headers: StrAnyMap
+    pagination: Any
+    rate_limit: Any
+
+
+class EndpointMap(TypedDict, total=False):
+    """
+    Shape accepted by EndpointConfig.from_obj.
+
+    One of ``path`` or ``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: Any
+    rate_limit: Any
+
+
 # SECTION: DATA CLASSES ===================================================== #
 
 
@@ -75,9 +165,9 @@ class RequestOptions:
     # -- Magic Methods (Object Lifecycle) -- #
 
     def __post_init__(self) -> None:
-        if self.params:
+        if self.params is not None:
             object.__setattr__(self, 'params', dict(self.params))
-        if self.headers:
+        if self.headers is not None:
             object.__setattr__(self, 'headers', dict(self.headers))
 
     # -- Instance Methods -- #
@@ -92,9 +182,9 @@ class RequestOptions:
             Keyword arguments for ``requests`` methods.
         """
         kw: dict[str, Any] = {}
-        if self.params:
+        if self.params is not None:
             kw['params'] = dict(self.params)
-        if self.headers:
+        if self.headers is not None:
             kw['headers'] = dict(self.headers)
         if self.timeout is not None:
             kw['timeout'] = self.timeout
@@ -106,7 +196,7 @@ class RequestOptions:
         params: Params | None | object = _UNSET,
         headers: Headers | None | object = _UNSET,
         timeout: float | None | object = _UNSET,
-    ) -> RequestOptions:
+    ) -> Self:
         """
         Return a copy with the provided fields replaced.
 
@@ -146,7 +236,7 @@ class RequestOptions:
         else:
             next_timeout = cast(float | None, timeout)
 
-        return RequestOptions(
+        return self.__class__(
             params=next_params,
             headers=next_headers,
             timeout=next_timeout,