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

etlplus/file/hbs.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 ZSAV content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the HBS 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 HBS file on disk.
     data : JSONData
         Data to write as HBS file. Should be a list of dictionaries or a
@@ -77,4 +77,5 @@ def write(
     int
         The number of rows written to the HBS file.
     """
+    path = coerce_path(path)
     return stub.write(path, data, format_name='HBS')

etlplus/file/hdf5.py

@@ -1,8 +1,8 @@
 """
 :mod:`etlplus.file.hdf5` module.
 
-Stub helpers for reading/writing Hierarchical Data Format (HDF5) files (not
-implemented yet).
+Helpers for reading Hierarchical Data Format (HDF5) files. Stub helpers for
+writing such files (not implemented yet).
 
 Notes
 -----
@@ -19,11 +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 ========================================================== #
 
@@ -35,30 +38,89 @@ __all__ = [
 ]
 
 
+# SECTION: INTERNAL CONSTANTS ============================================== #
+
+
+DEFAULT_KEY = 'data'
+
+
+# SECTION: INTERNAL FUNCTIONS =============================================== #
+
+
+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',
+    ) from err
+
+
 # SECTION: FUNCTIONS ======================================================== #
 
 
 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.
     """
-    return stub.read(path, format_name='HDF5')
+    path = coerce_path(path)
+    pandas = get_pandas('HDF5')
+    try:
+        store = pandas.HDFStore(path)
+    except ImportError as err:  # pragma: no cover
+        _raise_tables_error(err)
+
+    with store:
+        keys = [key.lstrip('/') for key in store.keys()]
+        if not keys:
+            return []
+        if DEFAULT_KEY in keys:
+            key = DEFAULT_KEY
+        elif len(keys) == 1:
+            key = keys[0]
+        else:
+            raise ValueError(
+                'Multiple datasets found in HDF5 file; expected "data" or '
+                'a single dataset',
+            )
+        frame = store.get(key)
+    return cast(JSONList, frame.to_dict(orient='records'))
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -66,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
@@ -77,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

@@ -1,8 +1,7 @@
 """
 :mod:`etlplus.file.ini` module.
 
-Stub helpers for reading/writing initialization (INI) files (not implemented
-yet).
+Helpers for reading/writing initialization (INI) files.
 
 Notes
 -----
@@ -20,11 +19,15 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
+import configparser
 
 from ..types import JSONData
-from ..types import JSONList
-from . import stub
+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 ========================================================== #
 
@@ -40,26 +43,39 @@ __all__ = [
 
 
 def read(
-    path: Path,
-) -> JSONList:
+    path: StrPath,
+) -> JSONData:
     """
     Read INI content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the INI file on disk.
 
     Returns
     -------
-    JSONList
-        The list of dictionaries read from the INI file.
+    JSONData
+        The structured data read from the INI file.
     """
-    return stub.read(path, format_name='INI')
+    path = coerce_path(path)
+    parser = configparser.ConfigParser()
+    parser.read(path, encoding='utf-8')
+
+    payload: JSONDict = {}
+    if parser.defaults():
+        payload['DEFAULT'] = dict(parser.defaults())
+    defaults = dict(parser.defaults())
+    for section in parser.sections():
+        raw_section = dict(parser.items(section))
+        for key in defaults:
+            raw_section.pop(key, None)
+        payload[section] = raw_section
+    return payload
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -67,15 +83,42 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the INI file on disk.
     data : JSONData
-        Data to write as INI. Should be a list of dictionaries or a
-        single dictionary.
+        Data to write as INI. Should be a dictionary.
 
     Returns
     -------
     int
-        The number of rows written to the INI file.
+        The number of records written to the INI file.
+
+    Raises
+    ------
+    TypeError
+        If *data* is not a dictionary.
     """
-    return stub.write(path, data, format_name='INI')
+    path = coerce_path(path)
+    payload = require_dict_payload(data, format_name='INI')
+
+    parser = configparser.ConfigParser()
+    for section, values in payload.items():
+        if section == 'DEFAULT':
+            if isinstance(values, dict):
+                parser['DEFAULT'] = {
+                    key: stringify_value(value)
+                    for key, value in values.items()
+                }
+            else:
+                raise TypeError('INI DEFAULT section must be a dict')
+            continue
+        if not isinstance(values, dict):
+            raise TypeError('INI sections must map to dicts')
+        parser[section] = {
+            key: stringify_value(value) for key, value in values.items()
+        }
+
+    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')