etlplus 0.17.2__py3-none-any.whl → 0.17.3__py3-none-any.whl

etlplus/file/hdf5.py

@@ -19,13 +19,14 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
 from typing import cast
 
 from ..types import JSONData
 from ..types import JSONList
+from ..types import StrPath
 from . import stub
 from ._imports import get_pandas
+from ._io import coerce_path
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -46,7 +47,23 @@ DEFAULT_KEY = 'data'
 # SECTION: INTERNAL FUNCTIONS =============================================== #
 
 
-def _raise_tables_error(err: ImportError) -> None:
+def _raise_tables_error(
+    err: ImportError,
+) -> None:
+    """
+    Raise a consistent ImportError for missing PyTables support.
+
+    Parameters
+    ----------
+    err : ImportError
+        The original ImportError raised when trying to use HDF5 support without
+        the required dependency.
+
+    Raises
+    ------
+    ImportError
+        Consistent ImportError indicating that PyTables is required.
+    """
     raise ImportError(
         'HDF5 support requires optional dependency "tables".\n'
         'Install with: pip install tables',
@@ -57,21 +74,28 @@ def _raise_tables_error(err: ImportError) -> None:
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read HDF5 content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the HDF5 file on disk.
 
     Returns
     -------
     JSONList
         The list of dictionaries read from the HDF5 file.
+
+    Raises
+    ------
+    ValueError
+        If multiple datasets are found in the HDF5 file without a clear key to
+        use.
     """
+    path = coerce_path(path)
     pandas = get_pandas('HDF5')
     try:
         store = pandas.HDFStore(path)
@@ -96,7 +120,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -104,7 +128,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the HDF5 file on disk.
     data : JSONData
         Data to write as HDF5 file. Should be a list of dictionaries or a
@@ -115,4 +139,5 @@ def write(
     int
         The number of rows written to the HDF5 file.
     """
+    path = coerce_path(path)
     return stub.write(path, data, format_name='HDF5')

etlplus/file/ini.py

@@ -20,11 +20,14 @@ Notes
 from __future__ import annotations
 
 import configparser
-from pathlib import Path
-from typing import Any
 
 from ..types import JSONData
 from ..types import JSONDict
+from ..types import StrPath
+from ._io import coerce_path
+from ._io import ensure_parent_dir
+from ._io import require_dict_payload
+from ._io import stringify_value
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -36,28 +39,18 @@ __all__ = [
 ]
 
 
-# SECTION: INTERNAL FUNCTIONS =============================================== #
-
-
-def _stringify(value: Any) -> str:
-    """Normalize INI values into strings."""
-    if value is None:
-        return ''
-    return str(value)
-
-
 # SECTION: FUNCTIONS ======================================================== #
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONData:
     """
     Read INI content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the INI file on disk.
 
     Returns
@@ -65,6 +58,7 @@ def read(
     JSONData
         The structured data read from the INI file.
     """
+    path = coerce_path(path)
     parser = configparser.ConfigParser()
     parser.read(path, encoding='utf-8')
 
@@ -81,7 +75,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -89,7 +83,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the INI file on disk.
     data : JSONData
         Data to write as INI. Should be a dictionary.
@@ -104,17 +98,16 @@ def write(
     TypeError
         If *data* is not a dictionary.
     """
-    if isinstance(data, list):
-        raise TypeError('INI payloads must be a dict')
-    if not isinstance(data, dict):
-        raise TypeError('INI payloads must be a dict')
+    path = coerce_path(path)
+    payload = require_dict_payload(data, format_name='INI')
 
     parser = configparser.ConfigParser()
-    for section, values in data.items():
+    for section, values in payload.items():
         if section == 'DEFAULT':
             if isinstance(values, dict):
                 parser['DEFAULT'] = {
-                    key: _stringify(value) for key, value in values.items()
+                    key: stringify_value(value)
+                    for key, value in values.items()
                 }
             else:
                 raise TypeError('INI DEFAULT section must be a dict')
@@ -122,10 +115,10 @@ def write(
         if not isinstance(values, dict):
             raise TypeError('INI sections must map to dicts')
         parser[section] = {
-            key: _stringify(value) for key, value in values.items()
+            key: stringify_value(value) for key, value in values.items()
         }
 
-    path.parent.mkdir(parents=True, exist_ok=True)
+    ensure_parent_dir(path)
     with path.open('w', encoding='utf-8', newline='') as handle:
         parser.write(handle)
     return 1

etlplus/file/ion.py

@@ -18,11 +18,11 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
-
 from ..types import JSONData
 from ..types import JSONList
+from ..types import StrPath
 from . import stub
+from ._io import coerce_path
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -38,14 +38,14 @@ __all__ = [
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read ION content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the ION file on disk.
 
     Returns
@@ -57,7 +57,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -65,7 +65,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the ION file on disk.
     data : JSONData
         Data to write as ION. Should be a list of dictionaries or a
@@ -76,4 +76,5 @@ def write(
     int
         The number of rows written to the ION file.
     """
+    path = coerce_path(path)
     return stub.write(path, data, format_name='ION')

etlplus/file/jinja2.py

@@ -19,11 +19,11 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
-
 from ..types import JSONData
 from ..types import JSONList
+from ..types import StrPath
 from . import stub
+from ._io import coerce_path
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -39,14 +39,14 @@ __all__ = [
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read JINJA2 content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the JINJA2 file on disk.
 
     Returns
@@ -58,7 +58,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -66,7 +66,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the JINJA2 file on disk.
     data : JSONData
         Data to write as JINJA2 file. Should be a list of dictionaries or a
@@ -77,4 +77,5 @@ def write(
     int
         The number of rows written to the JINJA2 file.
     """
+    path = coerce_path(path)
     return stub.write(path, data, format_name='JINJA2')

etlplus/file/json.py

@@ -19,11 +19,13 @@ Notes
 from __future__ import annotations
 
 import json
-from pathlib import Path
 
 from ..types import JSONData
+from ..types import StrPath
 from ..utils import count_records
+from ._io import coerce_path
 from ._io import coerce_record_payload
+from ._io import ensure_parent_dir
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -39,7 +41,7 @@ __all__ = [
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONData:
     """
     Read JSON content from *path*.
@@ -48,19 +50,15 @@ def read(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the JSON file on disk.
 
     Returns
     -------
     JSONData
         The structured data read from the JSON file.
-
-    Raises
-    ------
-    TypeError
-        If the JSON root is not an object or an array of objects.
     """
+    path = coerce_path(path)
     with path.open('r', encoding='utf-8') as handle:
         loaded = json.load(handle)
 
@@ -68,7 +66,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -76,7 +74,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the JSON file on disk.
     data : JSONData
         Data to serialize as JSON.
@@ -86,7 +84,8 @@ def write(
     int
         The number of records written to the JSON file.
     """
-    path.parent.mkdir(parents=True, exist_ok=True)
+    path = coerce_path(path)
+    ensure_parent_dir(path)
     with path.open('w', encoding='utf-8') as handle:
         json.dump(
             data,

etlplus/file/log.py

@@ -18,11 +18,11 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
-
 from ..types import JSONData
 from ..types import JSONList
+from ..types import StrPath
 from . import stub
+from ._io import coerce_path
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -38,14 +38,14 @@ __all__ = [
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read LOG content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the LOG file on disk.
 
     Returns
@@ -57,7 +57,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -65,7 +65,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the LOG file on disk.
     data : JSONData
         Data to write as LOG. Should be a list of dictionaries or a
@@ -76,4 +76,5 @@ def write(
     int
         The number of rows written to the LOG file.
     """
+    path = coerce_path(path)
     return stub.write(path, data, format_name='LOG')

etlplus/file/mat.py

@@ -18,11 +18,11 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
-
 from ..types import JSONData
 from ..types import JSONList
+from ..types import StrPath
 from . import stub
+from ._io import coerce_path
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -38,14 +38,14 @@ __all__ = [
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read MAT content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the MAT file on disk.
 
     Returns
@@ -57,7 +57,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -65,7 +65,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the MAT file on disk.
     data : JSONData
         Data to write as MAT file. Should be a list of dictionaries or a
@@ -76,4 +76,5 @@ def write(
     int
         The number of rows written to the MAT file.
     """
+    path = coerce_path(path)
     return stub.write(path, data, format_name='MAT')

etlplus/file/mdb.py

@@ -19,11 +19,11 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
-
 from ..types import JSONData
 from ..types import JSONList
+from ..types import StrPath
 from . import stub
+from ._io import coerce_path
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -39,14 +39,14 @@ __all__ = [
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read CSV content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the CSV file on disk.
 
     Returns
@@ -58,7 +58,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -66,7 +66,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the CSV file on disk.
     data : JSONData
         Data to write as CSV. Should be a list of dictionaries or a
@@ -77,4 +77,5 @@ def write(
     int
         The number of rows written to the CSV file.
     """
+    path = coerce_path(path)
     return stub.write(path, data, format_name='DAT')

etlplus/file/msgpack.py

@@ -18,12 +18,12 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
-from typing import Any
-
 from ..types import JSONData
-from ._imports import get_optional_module
+from ..types import StrPath
+from ._imports import get_dependency
+from ._io import coerce_path
 from ._io import coerce_record_payload
+from ._io import ensure_parent_dir
 from ._io import normalize_records
 
 # SECTION: EXPORTS ========================================================== #
@@ -36,32 +36,18 @@ __all__ = [
 ]
 
 
-# SECTION: INTERNAL FUNCTIONS =============================================== #
-
-
-def _get_msgpack() -> Any:
-    """Return the msgpack module, importing it on first use."""
-    return get_optional_module(
-        'msgpack',
-        error_message=(
-            'MSGPACK support requires optional dependency "msgpack".\n'
-            'Install with: pip install msgpack'
-        ),
-    )
-
-
 # SECTION: FUNCTIONS ======================================================== #
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONData:
     """
     Read MsgPack content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the MsgPack file on disk.
 
     Returns
@@ -69,14 +55,15 @@ def read(
     JSONData
         The structured data read from the MsgPack file.
     """
-    msgpack = _get_msgpack()
+    path = coerce_path(path)
+    msgpack = get_dependency('msgpack', format_name='MSGPACK')
     with path.open('rb') as handle:
         payload = msgpack.unpackb(handle.read(), raw=False)
     return coerce_record_payload(payload, format_name='MSGPACK')
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -84,7 +71,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the MsgPack file on disk.
     data : JSONData
         Data to write as MsgPack. Should be a list of dictionaries or a
@@ -95,10 +82,11 @@ def write(
     int
         The number of rows written to the MsgPack file.
     """
-    msgpack = _get_msgpack()
+    path = coerce_path(path)
+    msgpack = get_dependency('msgpack', format_name='MSGPACK')
     records = normalize_records(data, 'MSGPACK')
     payload: JSONData = records if isinstance(data, list) else records[0]
-    path.parent.mkdir(parents=True, exist_ok=True)
+    ensure_parent_dir(path)
     with path.open('wb') as handle:
         handle.write(msgpack.packb(payload, use_bin_type=True))
     return len(records)

etlplus/file/mustache.py

@@ -19,11 +19,11 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
-
 from ..types import JSONData
 from ..types import JSONList
+from ..types import StrPath
 from . import stub
+from ._io import coerce_path
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -39,14 +39,14 @@ __all__ = [
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read MUSTACHE content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the MUSTACHE file on disk.
 
     Returns
@@ -58,7 +58,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -66,7 +66,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the MUSTACHE file on disk.
     data : JSONData
         Data to write as MUSTACHE file. Should be a list of dictionaries or a
@@ -77,4 +77,5 @@ def write(
     int
         The number of rows written to the MUSTACHE file.
     """
+    path = coerce_path(path)
     return stub.write(path, data, format_name='MUSTACHE')