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

etlplus/{extract.py → ops/extract.py}

@@ -1,5 +1,5 @@
 """
-:mod:`etlplus.extract` module.
+:mod:`etlplus.ops.extract` module.
 
 Helpers to extract data from files, databases, and REST APIs.
 """
@@ -10,58 +10,81 @@ from pathlib import Path
 from typing import Any
 from typing import cast
 
-import requests  # type: ignore[import]
-
-from .enums import DataConnectorType
-from .enums import FileFormat
-from .enums import HttpMethod
-from .enums import coerce_data_connector_type
-from .enums import coerce_file_format
-from .file import File
-from .types import JSONData
-from .types import JSONDict
-from .types import JSONList
-from .types import StrPath
+from ..api import HttpMethod
+from ..api.utils import resolve_request
+from ..enums import DataConnectorType
+from ..file import File
+from ..file import FileFormat
+from ..types import JSONData
+from ..types import JSONDict
+from ..types import JSONList
+from ..types import StrPath
 
 # SECTION: FUNCTIONS ======================================================== #
 
 
-# -- File Extraction -- #
-
-
-def extract_from_file(
-    file_path: StrPath,
-    file_format: FileFormat | str | None = FileFormat.JSON,
+def extract_from_api(
+    url: str,
+    method: HttpMethod | str = HttpMethod.GET,
+    **kwargs: Any,
 ) -> JSONData:
     """
-    Extract (semi-)structured data from a local file.
+    Extract data from a REST API.
 
     Parameters
     ----------
-    file_path : StrPath
-        Source file path.
-    file_format : FileFormat | str | None, optional
-        File format to parse. If ``None``, infer from the filename
-        extension. Defaults to `'json'` for backward compatibility when
-        explicitly provided.
+    url : str
+        API endpoint URL.
+    method : HttpMethod | str, optional
+        HTTP method to use. Defaults to ``GET``.
+    **kwargs : Any
+        Extra arguments forwarded to the underlying ``requests`` call
+        (for example, ``timeout``). To use a pre-configured
+        :class:`requests.Session`, provide it via ``session``.
+        When omitted, ``timeout`` defaults to 10 seconds.
 
     Returns
     -------
     JSONData
-        Parsed data as a mapping or a list of mappings.
-    """
-    path = Path(file_path)
-
-    # If no explicit format is provided, let File infer from extension.
-    if file_format is None:
-        return File(path, None).read()
-    fmt = coerce_file_format(file_format)
+        Parsed JSON payload, or a fallback object with raw text.
 
-    # Let file module perform existence and format validation.
-    return File(path, fmt).read()
+    Raises
+    ------
+    TypeError
+        If a provided ``session`` does not expose the required HTTP
+        method (for example, ``get``).
+    """
+    timeout = kwargs.pop('timeout', None)
+    session = kwargs.pop('session', None)
+    request_callable, timeout, _ = resolve_request(
+        method,
+        session=session,
+        timeout=timeout,
+    )
+    response = request_callable(url, timeout=timeout, **kwargs)
+    response.raise_for_status()
 
+    content_type = response.headers.get('content-type', '').lower()
+    if 'application/json' in content_type:
+        try:
+            payload: Any = response.json()
+        except ValueError:
+            # Malformed JSON despite content-type; fall back to text
+            return {
+                'content': response.text,
+                'content_type': content_type,
+            }
+        if isinstance(payload, dict):
+            return cast(JSONDict, payload)
+        if isinstance(payload, list):
+            if all(isinstance(x, dict) for x in payload):
+                return cast(JSONList, payload)
+            # Coerce non-dict array items into objects for consistency
+            return [{'value': x} for x in payload]
+        # Fallback: wrap scalar JSON
+        return {'value': payload}
 
-# -- Database Extraction (Placeholder) -- #
+    return {'content': response.text, 'content_type': content_type}
 
 
 def extract_from_database(
@@ -96,77 +119,36 @@ def extract_from_database(
     ]
 
 
-# -- REST API Extraction -- #
-
-
-def extract_from_api(
-    url: str,
-    method: HttpMethod | str = HttpMethod.GET,
-    **kwargs: Any,
+def extract_from_file(
+    file_path: StrPath,
+    file_format: FileFormat | str | None = FileFormat.JSON,
 ) -> JSONData:
     """
-    Extract data from a REST API.
+    Extract (semi-)structured data from a local file.
 
     Parameters
     ----------
-    url : str
-        API endpoint URL.
-    method : HttpMethod | str, optional
-        HTTP method to use. Defaults to ``GET``.
-    **kwargs : Any
-        Extra arguments forwarded to the underlying ``requests`` call
-        (for example, ``timeout``). To use a pre-configured
-        :class:`requests.Session`, provide it via ``session``.
+    file_path : StrPath
+        Source file path.
+    file_format : FileFormat | str | None, optional
+        File format to parse. If ``None``, infer from the filename
+        extension. Defaults to `'json'` for backward compatibility when
+        explicitly provided.
 
     Returns
     -------
     JSONData
-        Parsed JSON payload, or a fallback object with raw text.
-
-    Raises
-    ------
-    TypeError
-        If a provided ``session`` does not expose the required HTTP
-        method (for example, ``get``).
+        Parsed data as a mapping or a list of mappings.
     """
-    http_method = HttpMethod.coerce(method)
-
-    # Apply a conservative timeout to guard against hanging requests.
-    timeout = kwargs.pop('timeout', 10.0)
-    session = kwargs.pop('session', None)
-    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',
-        )
-
-    response = request_callable(url, timeout=timeout, **kwargs)
-    response.raise_for_status()
+    path = Path(file_path)
 
-    content_type = response.headers.get('content-type', '').lower()
-    if 'application/json' in content_type:
-        try:
-            payload: Any = response.json()
-        except ValueError:
-            # Malformed JSON despite content-type; fall back to text
-            return {
-                'content': response.text,
-                'content_type': content_type,
-            }
-        if isinstance(payload, dict):
-            return cast(JSONDict, payload)
-        if isinstance(payload, list):
-            if all(isinstance(x, dict) for x in payload):
-                return cast(JSONList, payload)
-            # Coerce non-dict array items into objects for consistency
-            return [{'value': x} for x in payload]
-        # Fallback: wrap scalar JSON
-        return {'value': payload}
+    # If no explicit format is provided, let File infer from extension.
+    if file_format is None:
+        return File(path, None).read()
+    fmt = FileFormat.coerce(file_format)
 
-    return {'content': response.text, 'content_type': content_type}
+    # Let file module perform existence and format validation.
+    return File(path, fmt).read()
 
 
 # -- Orchestration -- #
@@ -202,7 +184,7 @@ def extract(
     ValueError
         If `source_type` is not one of the supported values.
     """
-    match coerce_data_connector_type(source_type):
+    match DataConnectorType.coerce(source_type):
         case DataConnectorType.FILE:
             # Prefer explicit format if provided, else infer from filename.
             return extract_from_file(source, file_format)
@@ -213,6 +195,6 @@ def extract(
             # ``file_format`` is ignored for APIs.
             return extract_from_api(str(source), **kwargs)
         case _:
-            # ``coerce_data_connector_type`` covers invalid entries, but keep
-            # explicit guard for defensive programming.
+            # :meth:`coerce` already raises for invalid connector types, but
+            # keep explicit guard for defensive programming.
             raise ValueError(f'Invalid source type: {source_type}')

etlplus/{load.py → ops/load.py}

@@ -1,5 +1,5 @@
 """
-:mod:`etlplus.load` module.
+:mod:`etlplus.ops.load` module.
 
 Helpers to load data into files, databases, and REST APIs.
 """
@@ -12,20 +12,16 @@ from pathlib import Path
 from typing import Any
 from typing import cast
 
-import requests  # type: ignore[import]
-
-from .enums import DataConnectorType
-from .enums import FileFormat
-from .enums import HttpMethod
-from .enums import coerce_data_connector_type
-from .enums import coerce_file_format
-from .enums import coerce_http_method
-from .file import File
-from .types import JSONData
-from .types import JSONDict
-from .types import JSONList
-from .types import StrPath
-from .utils import count_records
+from ..api import HttpMethod
+from ..api.utils import resolve_request
+from ..enums import DataConnectorType
+from ..file import File
+from ..file import FileFormat
+from ..types import JSONData
+from ..types import JSONDict
+from ..types import JSONList
+from ..types import StrPath
+from ..utils import count_records
 
 # SECTION: INTERNAL FUNCTIONS ============================================== #
 
@@ -72,7 +68,7 @@ def _parse_json_string(
 # SECTION: FUNCTIONS ======================================================== #
 
 
-# -- Data Loading -- #
+# -- Helpers -- #
 
 
 def load_data(
@@ -101,7 +97,7 @@ def load_data(
         return cast(JSONData, source)
 
     if isinstance(source, Path):
-        return File(source, FileFormat.JSON).read_json()
+        return File(source, FileFormat.JSON).read()
 
     if isinstance(source, str):
         # Special case: '-' means read JSON from STDIN (Unix convention).
@@ -111,7 +107,7 @@ def load_data(
         candidate = Path(source)
         if candidate.exists():
             try:
-                return File(candidate, FileFormat.JSON).read_json()
+                return File(candidate, FileFormat.JSON).read()
             except (OSError, json.JSONDecodeError, ValueError):
                 # Fall back to treating the string as raw JSON content.
                 pass
@@ -122,58 +118,59 @@ def load_data(
     )
 
 
-# -- File Loading -- #
-
-
-def load_to_file(
+def load_to_api(
     data: JSONData,
-    file_path: StrPath,
-    file_format: FileFormat | str | None = None,
+    url: str,
+    method: HttpMethod | str,
+    **kwargs: Any,
 ) -> JSONDict:
     """
-    Persist data to a local file.
+    Load data to a REST API.
 
     Parameters
     ----------
     data : JSONData
-        Data to write.
-    file_path : StrPath
-        Target file path.
-    file_format : FileFormat | str | None, optional
-        Output format. If omitted (None), the format is inferred from the
-        filename extension.
+        Data to send as JSON.
+    url : str
+        API endpoint URL.
+    method : HttpMethod | str
+        HTTP method to use.
+    **kwargs : Any
+        Extra arguments forwarded to ``requests`` (e.g., ``timeout``).
+        When omitted, ``timeout`` defaults to 10 seconds.
 
     Returns
     -------
     JSONDict
-        Result dictionary with status and record count.
+        Result dictionary including response payload or text.
     """
-    path = Path(file_path)
-    path.parent.mkdir(parents=True, exist_ok=True)
+    # Apply a conservative timeout to guard against hanging requests.
+    timeout = kwargs.pop('timeout', 10.0)
+    session = kwargs.pop('session', None)
+    request_callable, timeout, http_method = resolve_request(
+        method,
+        session=session,
+        timeout=timeout,
+    )
+    response = request_callable(url, json=data, timeout=timeout, **kwargs)
+    response.raise_for_status()
 
-    # If no explicit format is provided, let File infer from extension.
-    if file_format is None:
-        records = File(path).write(data)
-        ext = path.suffix.lstrip('.').lower()
-        fmt = coerce_file_format(ext) if ext else FileFormat.JSON
-    else:
-        fmt = coerce_file_format(file_format)
-        records = File(path, fmt).write(data)
-    if fmt is FileFormat.CSV and records == 0:
-        message = 'No data to write'
-    else:
-        message = f'Data loaded to {path}'
+    # Try JSON first, fall back to text.
+    try:
+        payload: Any = response.json()
+    except ValueError:
+        payload = response.text
 
     return {
         'status': 'success',
-        'message': message,
-        'records': records,
+        'status_code': response.status_code,
+        'message': f'Data loaded to {url}',
+        'response': payload,
+        'records': count_records(data),
+        'method': http_method.value.upper(),
     }
 
 
-# -- Database Loading (Placeholder) -- #
-
-
 def load_to_database(
     data: JSONData,
     connection_string: str,
@@ -209,69 +206,49 @@ def load_to_database(
     }
 
 
-# -- REST API Loading -- #
-
-
-def load_to_api(
+def load_to_file(
     data: JSONData,
-    url: str,
-    method: HttpMethod | str,
-    **kwargs: Any,
+    file_path: StrPath,
+    file_format: FileFormat | str | None = None,
 ) -> JSONDict:
     """
-    Load data to a REST API.
+    Persist data to a local file.
 
     Parameters
     ----------
     data : JSONData
-        Data to send as JSON.
-    url : str
-        API endpoint URL.
-    method : HttpMethod | str
-        HTTP method to use.
-    **kwargs : Any
-        Extra arguments forwarded to ``requests`` (e.g., ``timeout``).
+        Data to write.
+    file_path : StrPath
+        Target file path.
+    file_format : FileFormat | str | None, optional
+        Output format. If omitted (None), the format is inferred from the
+        filename extension.
 
     Returns
     -------
     JSONDict
-        Result dictionary including response payload or text.
-
-    Raises
-    ------
-    TypeError
-        If the session object is not valid.
+        Result dictionary with status and record count.
     """
-    http_method = coerce_http_method(method)
-
-    # Apply a conservative timeout to guard against hanging requests.
-    timeout = kwargs.pop('timeout', 10.0)
-    session = kwargs.pop('session', None)
-    requester = session or requests
-
-    request_callable = getattr(requester, http_method.value, None)
-    if not callable(request_callable):
-        raise TypeError(
-            'Session object must supply a '
-            f'callable "{http_method.value}" method',
-        )
-
-    response = request_callable(url, json=data, timeout=timeout, **kwargs)
-    response.raise_for_status()
+    path = Path(file_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
 
-    # Try JSON first, fall back to text.
-    try:
-        payload: Any = response.json()
-    except ValueError:
-        payload = response.text
+    # If no explicit format is provided, let File infer from extension.
+    if file_format is None:
+        records = File(path).write(data)
+        ext = path.suffix.lstrip('.').lower()
+        fmt = FileFormat.coerce(ext) if ext else FileFormat.JSON
+    else:
+        fmt = FileFormat.coerce(file_format)
+        records = File(path, fmt).write(data)
+    if fmt is FileFormat.CSV and records == 0:
+        message = 'No data to write'
+    else:
+        message = f'Data loaded to {path}'
 
     return {
         'status': 'success',
-        'status_code': response.status_code,
-        'message': f'Data loaded to {url}',
-        'response': payload,
-        'records': count_records(data),
-        'method': http_method.value.upper(),
+        'message': message,
+        'records': records,
     }
 
 
@@ -316,7 +293,7 @@ def load(
     """
     data = load_data(source)
 
-    match coerce_data_connector_type(target_type):
+    match DataConnectorType.coerce(target_type):
         case DataConnectorType.FILE:
             # Prefer explicit format if provided, else infer from filename.
             return load_to_file(data, target, file_format)
@@ -331,6 +308,6 @@ def load(
                 **kwargs,
             )
         case _:
-            # `coerce_data_connector_type` covers invalid entries, but keep
-            # explicit guard.
+            # :meth:`coerce` already raises for invalid connector types, but
+            # keep explicit guard for defensive programming.
             raise ValueError(f'Invalid target type: {target_type}')