etlplus 0.14.3__py3-none-any.whl → 0.16.0__py3-none-any.whl

etlplus/file/conf.py

@@ -30,6 +30,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -42,7 +43,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read CONF content from ``path``.
+    Read CONF content from *path*.
 
     Parameters
     ----------
@@ -62,7 +63,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to CONF at ``path`` and return record count.
+    Write *data* to CONF at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/core.py

@@ -22,7 +22,10 @@ from .enums import infer_file_format_and_compression
 # SECTION: EXPORTS ========================================================== #
 
 
-__all__ = ['File']
+__all__ = [
+    # Classes
+    'File',
+]
 
 
 # SECTION: INTERNAL FUNCTIONS =============================================== #
@@ -30,7 +33,7 @@ __all__ = ['File']
 
 def _accepts_root_tag(handler: object) -> bool:
     """
-    Return True when ``handler`` supports a ``root_tag`` argument.
+    Return True when *handler* supports a ``root_tag`` argument.
 
     Parameters
     ----------
@@ -57,7 +60,7 @@ def _accepts_root_tag(handler: object) -> bool:
 @cache
 def _module_for_format(file_format: FileFormat) -> ModuleType:
     """
-    Import and return the module for ``file_format``.
+    Import and return the module for *file_format*.
 
     Parameters
     ----------
@@ -112,8 +115,8 @@ class File:
         """
         Auto-detect and set the file format on initialization.
 
-        If no explicit ``file_format`` is provided, attempt to infer it from
-        the file path's extension and update :attr:`file_format`. If the
+        If no explicit :attr:`file_format` is provided, attempt to infer it
+        from the file path's extension and update :attr:`file_format`. If the
         extension is unknown, the attribute is left as ``None`` and will be
         validated later by :meth:`_ensure_format`.
         """
@@ -262,7 +265,7 @@ class File:
 
     def read(self) -> JSONData:
         """
-        Read structured data from :attr:`path` using :attr:`file_format`.
+        Read structured data from :attr:path` using :attr:`file_format`.
 
         Returns
         -------
@@ -291,7 +294,7 @@ class File:
         root_tag: str = xml.DEFAULT_XML_ROOT,
     ) -> int:
         """
-        Write ``data`` to :attr:`path` using :attr:`file_format`.
+        Write *data* to *path* using :attr:`file_format`.
 
         Parameters
         ----------
@@ -299,7 +302,7 @@ class File:
             Data to write to the file.
         root_tag : str, optional
             Root tag name to use when writing XML files. Defaults to
-            ``'root'``.
+            ``xml.DEFAULT_XML_ROOT``.
 
         Returns
         -------

etlplus/file/csv.py

@@ -29,6 +29,7 @@ from ._io import write_delimited
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -41,7 +42,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read CSV content from ``path``.
+    Read CSV content from *path*.
 
     Parameters
     ----------
@@ -61,7 +62,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to CSV at ``path`` and return record count.
+    Write *data* to CSV at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/dat.py

@@ -28,6 +28,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -40,7 +41,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read DAT content from ``path``.
+    Read DAT content from *path*.
 
     Parameters
     ----------
@@ -60,7 +61,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to DAT file at ``path`` and return record count.
+    Write *data* to DAT file at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/dta.py

@@ -27,6 +27,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -39,7 +40,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read DTA content from ``path``.
+    Read DTA content from *path*.
 
     Parameters
     ----------
@@ -59,7 +60,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to DTA file at ``path`` and return record count.
+    Write *data* to DTA file at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/duckdb.py

@@ -28,6 +28,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -40,7 +41,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read DUCKDB content from ``path``.
+    Read DUCKDB content from *path*.
 
     Parameters
     ----------
@@ -60,7 +61,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to DUCKDB at ``path`` and return record count.
+    Write *data* to DUCKDB at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/enums.py

@@ -281,7 +281,7 @@ def infer_file_format_and_compression(
         A filename, extension, MIME type, or existing enum member.
     filename : object | None, optional
         A filename to consult for extension-based inference (e.g. when
-        ``value`` is ``application/octet-stream``).
+        *value* is ``application/octet-stream``).
 
     Returns
     -------

etlplus/file/feather.py

@@ -30,6 +30,7 @@ from ._io import normalize_records
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -42,7 +43,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read Feather content from ``path``.
+    Read Feather content from *path*.
 
     Parameters
     ----------
@@ -75,7 +76,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to Feather at ``path`` and return record count.
+    Write *data* to Feather at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/fwf.py

@@ -27,6 +27,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -39,7 +40,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read FWF content from ``path``.
+    Read FWF content from *path*.
 
     Parameters
     ----------
@@ -59,7 +60,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to FWF file at ``path`` and return record count.
+    Write *data* to FWF file at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/gz.py

@@ -19,6 +19,7 @@ from .enums import infer_file_format_and_compression
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -65,7 +66,7 @@ def read(
     path: Path,
 ) -> JSONData:
     """
-    Read GZ content from ``path`` and parse the inner payload.
+    Read GZ content from *path* and parse the inner payload.
 
     Parameters
     ----------
@@ -94,7 +95,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to GZ at ``path`` and return record count.
+    Write *data* to GZ at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/hbs.py

@@ -28,6 +28,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -40,7 +41,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read ZSAV content from ``path``.
+    Read ZSAV content from *path*.
 
     Parameters
     ----------
@@ -60,7 +61,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to HBS file at ``path`` and return record count.
+    Write *data* to HBS file at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/hdf5.py

@@ -28,6 +28,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -40,7 +41,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read HDF5 content from ``path``.
+    Read HDF5 content from *path*.
 
     Parameters
     ----------
@@ -60,7 +61,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to HDF5 file at ``path`` and return record count.
+    Write *data* to HDF5 file at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/ini.py

@@ -29,6 +29,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -41,7 +42,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read INI content from ``path``.
+    Read INI content from *path*.
 
     Parameters
     ----------
@@ -61,7 +62,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to INI at ``path`` and return record count.
+    Write *data* to INI at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/ion.py

@@ -28,6 +28,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -40,7 +41,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read ION content from ``path``.
+    Read ION content from *path*.
 
     Parameters
     ----------
@@ -60,7 +61,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to ION at ``path`` and return record count.
+    Write *data* to ION at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/jinja2.py

@@ -28,6 +28,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -40,7 +41,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read JINJA2 content from ``path``.
+    Read JINJA2 content from *path*.
 
     Parameters
     ----------
@@ -60,7 +61,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to JINJA2 file at ``path`` and return record count.
+    Write *data* to JINJA2 file at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/json.py

@@ -20,17 +20,16 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
-from typing import cast
 
 from ..types import JSONData
-from ..types import JSONDict
-from ..types import JSONList
 from ..utils import count_records
+from ._io import coerce_record_payload
 
 # SECTION: EXPORTS ========================================================== #
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -43,7 +42,7 @@ def read(
     path: Path,
 ) -> JSONData:
     """
-    Read JSON content from ``path``.
+    Read JSON content from *path*.
 
     Validates that the JSON root is a dict or a list of dicts.
 
@@ -65,17 +64,7 @@ def read(
     with path.open('r', encoding='utf-8') as handle:
         loaded = json.load(handle)
 
-    if isinstance(loaded, dict):
-        return cast(JSONDict, loaded)
-    if isinstance(loaded, list):
-        if all(isinstance(item, dict) for item in loaded):
-            return cast(JSONList, loaded)
-        raise TypeError(
-            'JSON array must contain only objects (dicts) when loading file',
-        )
-    raise TypeError(
-        'JSON root must be an object or an array of objects when loading file',
-    )
+    return coerce_record_payload(loaded, format_name='JSON')
 
 
 def write(
@@ -83,7 +72,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` as formatted JSON to ``path``.
+    Write *data* as formatted JSON to *path*.
 
     Parameters
     ----------

etlplus/file/log.py

@@ -28,6 +28,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -40,7 +41,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read LOG content from ``path``.
+    Read LOG content from *path*.
 
     Parameters
     ----------
@@ -60,7 +61,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to LOG at ``path`` and return record count.
+    Write *data* to LOG at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/mat.py

@@ -28,6 +28,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -40,7 +41,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read MAT content from ``path``.
+    Read MAT content from *path*.
 
     Parameters
     ----------
@@ -60,7 +61,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to MAT file at ``path`` and return record count.
+    Write *data* to MAT file at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/mdb.py

@@ -28,6 +28,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -40,7 +41,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read CSV content from ``path``.
+    Read CSV content from *path*.
 
     Parameters
     ----------
@@ -60,7 +61,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to CSV at ``path`` and return record count.
+    Write *data* to CSV at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/msgpack.py

@@ -28,6 +28,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -40,7 +41,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read MsgPack content from ``path``.
+    Read MsgPack content from *path*.
 
     Parameters
     ----------
@@ -60,7 +61,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to MsgPack at ``path`` and return record count.
+    Write *data* to MsgPack at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/mustache.py

@@ -28,6 +28,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -40,7 +41,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read MUSTACHE content from ``path``.
+    Read MUSTACHE content from *path*.
 
     Parameters
     ----------
@@ -60,7 +61,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to MUSTACHE file at ``path`` and return record count.
+    Write *data* to MUSTACHE file at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/nc.py

@@ -28,6 +28,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -40,7 +41,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read NC content from ``path``.
+    Read NC content from *path*.
 
     Parameters
     ----------
@@ -60,7 +61,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to NC file at ``path`` and return record count.
+    Write *data* to NC file at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/ndjson.py

@@ -31,6 +31,7 @@ from ._io import normalize_records
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -43,7 +44,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read NDJSON content from ``path``.
+    Read NDJSON content from *path*.
 
     Parameters
     ----------
@@ -80,7 +81,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to NDJSON at ``path``.
+    Write *data* to NDJSON at *path*.
 
     Parameters
     ----------

etlplus/file/numbers.py

@@ -25,6 +25,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -37,7 +38,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read NUMBERS content from ``path``.
+    Read NUMBERS content from *path*.
 
     Parameters
     ----------
@@ -57,7 +58,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to NUMBERS file at ``path`` and return record count.
+    Write *data* to NUMBERS file at *path* and return record count.
 
     Parameters
     ----------