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

etlplus/__init__.py

@@ -2,17 +2,42 @@
 :mod:`etlplus` package.
 
 Top-level facade for the ETLPlus toolkit.
+
+Importing :mod:`etlplus` exposes the handful of coarse-grained helpers most
+users care about: ``extract``, ``transform``, ``load``, ``validate``, and
+``run``. Each helper delegates to the richer modules under ``etlplus.*`` while
+presenting a compact public API surface.
+
+Examples
+--------
+>>> from etlplus import extract, transform
+>>> raw = extract('file', 'input.json')
+>>> curated = transform(raw, {'select': ['id', 'name']})
+
+See Also
+--------
+- :mod:`etlplus.cli` for the command-line interface
+- :mod:`etlplus.run` for orchestrating pipeline jobs
 """
 
 from .__version__ import __version__
 
 __author__ = 'ETLPlus Team'
 
+from .extract import extract
+from .load import load
+from .run import run
+from .transform import transform
+from .validate import validate
 
 # SECTION: EXPORTS ========================================================== #
 
 
 __all__ = [
-    '__author__',
     '__version__',
+    'extract',
+    'load',
+    'run',
+    'transform',
+    'validate',
 ]

etlplus/api/README.md

@@ -1,7 +1,7 @@
-# `etlplus.api` Subpackage
+# etlplus.api module.
 
-Documentation for the `etlplus.api` subpackage: a lightweight HTTP client and helpers for paginated
-REST endpoints.
+Focused documentation for the `etlplus.api` subpackage: a lightweight HTTP client and helpers for
+paginated REST endpoints.
 
 - Provides a small `EndpointClient` for calling JSON APIs
 - Supports page-, offset-, and cursor-based pagination via `PaginationConfig`
@@ -12,21 +12,6 @@ REST endpoints.
 
 Back to project overview: see the top-level [README](../../README.md).
 
-- [`etlplus.api` Subpackage](#etlplusapi-subpackage)
-  - [Installation](#installation)
-  - [Quickstart](#quickstart)
-    - [Overriding Rate Limits Per Call](#overriding-rate-limits-per-call)
-  - [Choosing `records_path` and `cursor_path`](#choosing-records_path-and-cursor_path)
-  - [Cursor-Based Pagination Example](#cursor-based-pagination-example)
-  - [Offset-based pagination example](#offset-based-pagination-example)
-  - [Authentication](#authentication)
-  - [Errors and Rate Limiting](#errors-and-rate-limiting)
-  - [Types and Transport](#types-and-transport)
-  - [Config Schemas](#config-schemas)
-  - [Supporting Modules](#supporting-modules)
-  - [Minimal Contract](#minimal-contract)
-  - [See also](#see-also)
-
 ## Installation
 
 `etlplus.api` ships as part of the `etlplus` package. Install the package as usual:
@@ -226,36 +211,6 @@ providers can fall back to their own defaults. If you already possess a static t
   `etlplus/api/request_manager.py` wraps `requests` sessions plus retry orchestration. Advanced
   users may consult those modules to adapt behavior.
 
-## Config Schemas
-
-`etlplus.api.types` defines TypedDict-based configuration shapes for API profiles and endpoints.
-Runtime parsing remains permissive in `etlplus.api.config`, but these types improve IDE
-autocomplete and static analysis.
-
-Exported types:
-
-- `ApiConfigMap`: top-level API config shape
-- `ApiProfileConfigMap`: per-profile API config shape
-- `ApiProfileDefaultsMap`: defaults block within a profile
-- `EndpointMap`: endpoint config shape
-
-Example:
-
-```python
-from etlplus.api import ApiConfigMap
-
-api_cfg: ApiConfigMap = {
-    "base_url": "https://example.test",
-    "headers": {"Authorization": "Bearer token"},
-    "endpoints": {
-        "users": {
-            "path": "/users",
-            "method": "GET",
-        },
-    },
-}
-```
-
 ## Supporting Modules
 
 - `etlplus.api.types` collects friendly aliases such as `Headers`, `Params`, `Url`, and
@@ -278,6 +233,3 @@ api_cfg: ApiConfigMap = {
 ## See also
 
 - Top-level CLI and library usage in the main [README](../../README.md)
-
-
-[def]: #installation

etlplus/api/__init__.py

@@ -78,7 +78,6 @@ from .config import ApiConfig
 from .config import ApiProfileConfig
 from .config import EndpointConfig
 from .endpoint_client import EndpointClient
-from .enums import HttpMethod
 from .pagination import CursorPaginationConfigMap
 from .pagination import PagePaginationConfigMap
 from .pagination import PaginationClient
@@ -99,10 +98,6 @@ from .types import Headers
 from .types import Params
 from .types import RequestOptions
 from .types import Url
-from .utils import compose_api_request_env
-from .utils import compose_api_target_env
-from .utils import paginate_with_client
-from .utils import resolve_request
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -124,14 +119,9 @@ __all__ = [
     'RequestOptions',
     'RetryStrategy',
     # Enums
-    'HttpMethod',
     'PaginationType',
     # Functions
     'build_http_adapter',
-    'compose_api_request_env',
-    'compose_api_target_env',
-    'paginate_with_client',
-    'resolve_request',
     # Type Aliases
     'CursorPaginationConfigMap',
     'Headers',

etlplus/api/config.py

@@ -3,6 +3,11 @@
 
 Configuration dataclasses for REST API services, profiles, and endpoints.
 
+These models used to live under :mod:`etlplus.config`, but they belong in the
+API layer because they compose runtime types such as
+:class:`etlplus.api.EndpointClient`, :class:`etlplus.api.PaginationConfig`, and
+:class:`etlplus.api.RateLimitConfig`.
+
 Notes
 -----
 - TypedDict references remain editor hints only; :meth:`from_obj` accepts
@@ -13,7 +18,6 @@ Notes
 
 from __future__ import annotations
 
-from collections.abc import Callable
 from collections.abc import Mapping
 from dataclasses import dataclass
 from dataclasses import field
@@ -25,20 +29,20 @@ from typing import overload
 from urllib.parse import urlsplit
 from urllib.parse import urlunsplit
 
+from ..enums import HttpMethod
 from ..types import StrAnyMap
 from ..types import StrStrMap
 from ..utils import cast_str_dict
 from ..utils import coerce_dict
 from ..utils import maybe_mapping
 from .endpoint_client import EndpointClient
-from .enums import HttpMethod
 from .pagination import PaginationConfig
 from .rate_limiting import RateLimitConfig
 
 if TYPE_CHECKING:
-    from .types import ApiConfigMap
-    from .types import ApiProfileConfigMap
-    from .types import EndpointMap
+    from ..config.types import ApiConfigMap
+    from ..config.types import ApiProfileConfigMap
+    from ..config.types import EndpointMap
 
 
 # SECTION: EXPORTS ========================================================== #
@@ -102,33 +106,6 @@ def _effective_service_defaults(
     return fallback_base, fallback_headers
 
 
-def _freeze_mapping(
-    mapping: Mapping[Any, Any],
-    *,
-    key_cast: Callable[[Any], Any] | None = None,
-) -> MappingProxyType:
-    """
-    Return an immutable copy of a mapping, optionally normalizing keys.
-
-    Parameters
-    ----------
-    mapping : Mapping[Any, Any]
-        Source mapping to freeze.
-    key_cast : Callable[[Any], Any] | None, optional
-        Optional key coercion applied to each key.
-
-    Returns
-    -------
-    MappingProxyType
-        Read-only mapping proxy with normalized keys.
-    """
-    if key_cast is None:
-        data = dict(mapping)
-    else:
-        data = {key_cast(key): value for key, value in mapping.items()}
-    return MappingProxyType(data)
-
-
 def _normalize_method(
     value: Any,
 ) -> Any | None:
@@ -255,8 +232,16 @@ class ApiProfileConfig:
     # -- Magic Methods (Object Lifecycle) -- #
 
     def __post_init__(self) -> None:
-        object.__setattr__(self, 'headers', _freeze_mapping(self.headers))
-        object.__setattr__(self, 'auth', _freeze_mapping(self.auth))
+        object.__setattr__(
+            self,
+            'headers',
+            MappingProxyType(dict(self.headers)),
+        )
+        object.__setattr__(
+            self,
+            'auth',
+            MappingProxyType(dict(self.auth)),
+        )
 
     # -- Class Methods -- #
 
@@ -355,16 +340,20 @@ class ApiConfig:
     # -- Magic Methods (Object Lifecycle) -- #
 
     def __post_init__(self) -> None:
-        object.__setattr__(self, 'headers', _freeze_mapping(self.headers))
+        object.__setattr__(
+            self,
+            'headers',
+            MappingProxyType(dict(self.headers)),
+        )
         object.__setattr__(
             self,
             'endpoints',
-            _freeze_mapping(self.endpoints, key_cast=str),
+            MappingProxyType({str(k): v for k, v in self.endpoints.items()}),
         )
         object.__setattr__(
             self,
             'profiles',
-            _freeze_mapping(self.profiles, key_cast=str),
+            MappingProxyType({str(k): v for k, v in self.profiles.items()}),
         )
 
     # -- Internal Instance Methods -- #
@@ -556,12 +545,12 @@ class EndpointConfig:
         object.__setattr__(
             self,
             'path_params',
-            _freeze_mapping(self.path_params),
+            MappingProxyType(dict(self.path_params)),
         )
         object.__setattr__(
             self,
             'query_params',
-            _freeze_mapping(self.query_params),
+            MappingProxyType(dict(self.query_params)),
         )
 
     # -- Class Methods -- #

etlplus/api/endpoint_client.py

@@ -455,7 +455,7 @@ class EndpointClient:
         -------
         JSONData
             Parsed JSON payload or fallback structure matching
-            :func:`etlplus.ops.extract.extract_from_api` semantics.
+            :func:`etlplus.extract.extract_from_api` semantics.
         """
         return self._request_manager.get(url, **kwargs)
 
@@ -479,7 +479,7 @@ class EndpointClient:
         -------
         JSONData
             Parsed JSON payload or fallback structure matching
-            :func:`etlplus.ops.extract.extract_from_api` semantics.
+            :func:`etlplus.extract.extract_from_api` semantics.
         """
         return self._request_manager.post(url, **kwargs)
 
@@ -506,7 +506,7 @@ class EndpointClient:
         -------
         JSONData
             Parsed JSON payload or fallback structure matching
-            :func:`etlplus.ops.extract.extract_from_api` semantics.
+            :func:`etlplus.extract.extract_from_api` semantics.
         """
         return self._request_manager.request(method, url, **kwargs)
 

etlplus/api/pagination/client.py

@@ -1,5 +1,5 @@
 """
-:mod:`etlplus.api.pagination.client` module.
+:mod:`etlplus.api.client` module.
 
 Client-facing pagination driver for REST API responses.
 

etlplus/api/rate_limiting/config.py

@@ -1,5 +1,5 @@
 """
-:mod:`etlplus.api.rate_limiting.config` module.
+:mod:`etlplus.api.rate_limiting.rate_limiter` module.
 
 Rate limiting configuration primitives.
 
@@ -268,18 +268,6 @@ class RateLimitConfig(BoundsWarningsMixin):
     ) -> Self:
         """
         Normalize rate-limit config and overrides into a single instance.
-
-        Parameters
-        ----------
-        rate_limit : StrAnyMap | RateLimitConfig | None, optional
-            Base rate-limit configuration to normalize.
-        overrides : RateLimitOverrides, optional
-            Override values that take precedence over ``rate_limit``.
-
-        Returns
-        -------
-        Self
-            Normalized rate-limit configuration.
         """
         normalized = _coerce_rate_limit_map(rate_limit)
         cfg = _merge_rate_limit(normalized, overrides)

etlplus/api/rate_limiting/rate_limiter.py

@@ -20,7 +20,6 @@ from __future__ import annotations
 
 import time
 from dataclasses import dataclass
-from typing import Self
 
 from ...utils import to_float
 from ...utils import to_positive_float
@@ -144,13 +143,13 @@ class RateLimiter:
     # -- Class Methods -- #
 
     @classmethod
-    def disabled(cls) -> Self:
+    def disabled(cls) -> RateLimiter:
         """
         Create a limiter that never sleeps.
 
         Returns
         -------
-        Self
+        RateLimiter
             Instance with rate limiting disabled.
         """
         return cls(sleep_seconds=0.0)
@@ -159,7 +158,7 @@ class RateLimiter:
     def fixed(
         cls,
         seconds: float,
-    ) -> Self:
+    ) -> RateLimiter:
         """
         Create a limiter with a fixed non-negative delay.
 
@@ -171,7 +170,7 @@ class RateLimiter:
 
         Returns
         -------
-        Self
+        RateLimiter
             Instance with the specified delay.
         """
         value = to_float(seconds, 0.0, minimum=0.0) or 0.0
@@ -182,7 +181,7 @@ class RateLimiter:
     def from_config(
         cls,
         cfg: RateLimitInput,
-    ) -> Self:
+    ) -> RateLimiter:
         """
         Build a :class:`RateLimiter` from a configuration mapping.
 
@@ -202,10 +201,12 @@ class RateLimiter:
 
         Returns
         -------
-        Self
+        RateLimiter
             Instance with normalized ``sleep_seconds`` and ``max_per_sec``.
         """
         config = RateLimitConfig.from_inputs(rate_limit=cfg)
+        if config is None:
+            return cls.disabled()
 
         # RateLimiter.__post_init__ will normalize and enforce invariants.
         return cls(**config.as_mapping())
@@ -260,4 +261,6 @@ class RateLimiter:
             rate_limit=rate_limit,
             overrides=overrides,
         )
-        return float(config.sleep_seconds) if config.sleep_seconds else 0.0
+        if config is None or not config.sleep_seconds:
+            return 0.0
+        return float(config.sleep_seconds)

etlplus/api/request_manager.py

@@ -14,7 +14,6 @@ from collections.abc import Sequence
 from dataclasses import dataclass
 from dataclasses import field
 from functools import partial
-from types import TracebackType
 from typing import Any
 from typing import cast
 
@@ -138,7 +137,7 @@ class RequestManager:
         self,
         exc_type: type[BaseException] | None,
         exc: BaseException | None,
-        tb: TracebackType | None,
+        tb: Any,
     ) -> None:
         """
         Exit the runtime context and close owned sessions.
@@ -149,7 +148,7 @@ class RequestManager:
             Exception type if raised, else ``None``.
         exc : BaseException | None
             Exception instance if raised, else ``None``.
-        tb : TracebackType | None
+        tb : Any
             Traceback if an exception was raised, else ``None``.
         """
         if self._ctx_session is None:
@@ -276,7 +275,7 @@ class RequestManager:
 
         try:
             policy = self.retry
-            if policy is None:
+            if not policy:
                 try:
                     return fetch(url, **call_kwargs)
                 except requests.RequestException as exc:  # pragma: no cover
@@ -439,13 +438,9 @@ class RequestManager:
             if isinstance(payload, dict):
                 return cast(JSONDict, payload)
             if isinstance(payload, list):
-                out: list[JSONDict] = []
-                for item in payload:
-                    if isinstance(item, dict):
-                        out.append(cast(JSONDict, item))
-                    else:
-                        out.append({'value': item})
-                return cast(JSONData, out)
+                if all(isinstance(item, dict) for item in payload):
+                    return cast(JSONData, payload)
+                return [{'value': item} for item in payload]
             return {'value': payload}
         return {
             'content': response.text,

etlplus/api/transport.py

@@ -191,19 +191,7 @@ def _build_retry_value(
 def _normalize_retry_kwargs(
     retries_cfg: Mapping[str, Any],
 ) -> dict[str, Any]:
-    """
-    Filter and normalize urllib3 ``Retry`` kwargs from a mapping.
-
-    Parameters
-    ----------
-    retries_cfg : Mapping[str, Any]
-        Raw retry configuration mapping.
-
-    Returns
-    -------
-    dict[str, Any]
-        Filtered and normalized keyword arguments for ``Retry``.
-    """
+    """Filter and normalize urllib3 ``Retry`` kwargs from a mapping."""
     allowed_keys = {
         'total',
         'connect',
@@ -251,7 +239,7 @@ def _resolve_max_retries(
     """
     match retries_cfg:
         case int():
-            return to_maximum_int(retries_cfg, 0)
+            return retries_cfg
         case Mapping():
             try:
                 return _build_retry_value(retries_cfg)

etlplus/api/types.py

@@ -20,11 +20,8 @@ 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
@@ -42,11 +39,6 @@ __all__ = [
     'Headers',
     'Params',
     'Url',
-    # Typed Dicts
-    'ApiConfigMap',
-    'ApiProfileConfigMap',
-    'ApiProfileDefaultsMap',
-    'EndpointMap',
 ]
 
 
@@ -56,88 +48,6 @@ __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 ===================================================== #
 
 
@@ -165,9 +75,9 @@ class RequestOptions:
     # -- Magic Methods (Object Lifecycle) -- #
 
     def __post_init__(self) -> None:
-        if self.params is not None:
+        if self.params:
             object.__setattr__(self, 'params', dict(self.params))
-        if self.headers is not None:
+        if self.headers:
             object.__setattr__(self, 'headers', dict(self.headers))
 
     # -- Instance Methods -- #
@@ -182,9 +92,9 @@ class RequestOptions:
             Keyword arguments for ``requests`` methods.
         """
         kw: dict[str, Any] = {}
-        if self.params is not None:
+        if self.params:
             kw['params'] = dict(self.params)
-        if self.headers is not None:
+        if self.headers:
             kw['headers'] = dict(self.headers)
         if self.timeout is not None:
             kw['timeout'] = self.timeout
@@ -196,7 +106,7 @@ class RequestOptions:
         params: Params | None | object = _UNSET,
         headers: Headers | None | object = _UNSET,
         timeout: float | None | object = _UNSET,
-    ) -> Self:
+    ) -> RequestOptions:
         """
         Return a copy with the provided fields replaced.
 
@@ -236,7 +146,7 @@ class RequestOptions:
         else:
             next_timeout = cast(float | None, timeout)
 
-        return self.__class__(
+        return RequestOptions(
             params=next_params,
             headers=next_headers,
             timeout=next_timeout,