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

etlplus/file/txt.py

@@ -16,11 +16,12 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
-
 from ..types import JSONData
 from ..types import JSONList
+from ..types import StrPath
 from ..utils import count_records
+from ._io import coerce_path
+from ._io import ensure_parent_dir
 from ._io import normalize_records
 
 # SECTION: EXPORTS ========================================================== #
@@ -37,14 +38,14 @@ __all__ = [
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read TXT content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the TXT file on disk.
 
     Returns
@@ -52,6 +53,7 @@ def read(
     JSONList
         The list of dictionaries read from the TXT file.
     """
+    path = coerce_path(path)
     rows: JSONList = []
     with path.open('r', encoding='utf-8') as handle:
         for line in handle:
@@ -63,7 +65,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -71,7 +73,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the TXT file on disk.
     data : JSONData
         Data to write. Expects ``{'text': '...'} `` or a list of those.
@@ -87,12 +89,13 @@ def write(
         If any item in *data* is not a dictionary or if any dictionary
         does not contain a ``'text'`` key.
     """
+    path = coerce_path(path)
     rows = normalize_records(data, 'TXT')
 
     if not rows:
         return 0
 
-    path.parent.mkdir(parents=True, exist_ok=True)
+    ensure_parent_dir(path)
     with path.open('w', encoding='utf-8') as handle:
         for row in rows:
             if 'text' not in row:

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

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

etlplus/file/xls.py

@@ -6,12 +6,13 @@ Helpers for reading Excel XLS files (write is not supported).
 
 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 ._imports import get_pandas
+from ._io import coerce_path
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -27,14 +28,14 @@ __all__ = [
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read XLS content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the XLS file on disk.
 
     Returns
@@ -47,6 +48,7 @@ def read(
     ImportError
         If the optional dependency "xlrd" is not installed.
     """
+    path = coerce_path(path)
     pandas = get_pandas('XLS')
     try:
         frame = pandas.read_excel(path, engine='xlrd')
@@ -59,7 +61,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -71,7 +73,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the XLS file on disk.
     data : JSONData
         Data to write.
@@ -86,4 +88,5 @@ def write(
     RuntimeError
         If XLS writing is attempted.
     """
+    path = coerce_path(path)
     raise RuntimeError('XLS write is not supported; use XLSX instead')

etlplus/file/xlsm.py

@@ -1,8 +1,8 @@
 """
 :mod:`etlplus.file.xlsm` module.
 
-Stub helpers for reading/writing Microsoft Excel Macro-Enabled (XLSM)
-spreadsheet files (not implemented yet).
+Helpers for reading/writing Microsoft Excel Macro-Enabled (XLSM)
+spreadsheet files.
 
 Notes
 -----
@@ -19,11 +19,15 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
+from typing import cast
 
 from ..types import JSONData
 from ..types import JSONList
-from . import stub
+from ..types import StrPath
+from ._imports import get_pandas
+from ._io import coerce_path
+from ._io import ensure_parent_dir
+from ._io import normalize_records
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -39,26 +43,40 @@ __all__ = [
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read XLSM content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the XLSM file on disk.
 
     Returns
     -------
     JSONList
         The list of dictionaries read from the XLSM file.
+
+    Raises
+    ------
+    ImportError
+        If optional dependencies for XLSM support are missing.
     """
-    return stub.read(path, format_name='XLSM')
+    path = coerce_path(path)
+    pandas = get_pandas('XLSM')
+    try:
+        frame = pandas.read_excel(path)
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            'XLSM support requires optional dependency "openpyxl".\n'
+            'Install with: pip install openpyxl',
+        ) from e
+    return cast(JSONList, frame.to_dict(orient='records'))
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -66,7 +84,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the XLSM file on disk.
     data : JSONData
         Data to write as XLSM file. Should be a list of dictionaries or a
@@ -76,5 +94,25 @@ def write(
     -------
     int
         The number of rows written to the XLSM file.
+
+    Raises
+    ------
+    ImportError
+        If optional dependencies for XLSM support are missing.
     """
-    return stub.write(path, data, format_name='XLSM')
+    path = coerce_path(path)
+    records = normalize_records(data, 'XLSM')
+    if not records:
+        return 0
+
+    pandas = get_pandas('XLSM')
+    ensure_parent_dir(path)
+    frame = pandas.DataFrame.from_records(records)
+    try:
+        frame.to_excel(path, index=False)
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            'XLSM support requires optional dependency "openpyxl".\n'
+            'Install with: pip install openpyxl',
+        ) from e
+    return len(records)

etlplus/file/xlsx.py

@@ -6,12 +6,14 @@ Helpers for reading/writing Excel XLSX files.
 
 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 ._imports import get_pandas
+from ._io import coerce_path
+from ._io import ensure_parent_dir
 from ._io import normalize_records
 
 # SECTION: EXPORTS ========================================================== #
@@ -28,14 +30,14 @@ __all__ = [
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read XLSX content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the XLSX file on disk.
 
     Returns
@@ -48,6 +50,7 @@ def read(
     ImportError
         If optional dependencies for XLSX support are missing.
     """
+    path = coerce_path(path)
     pandas = get_pandas('XLSX')
     try:
         frame = pandas.read_excel(path)
@@ -60,7 +63,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -68,7 +71,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the XLSX file on disk.
     data : JSONData
         Data to write.
@@ -83,12 +86,13 @@ def write(
     ImportError
         If optional dependencies for XLSX support are missing.
     """
+    path = coerce_path(path)
     records = normalize_records(data, 'XLSX')
     if not records:
         return 0
 
     pandas = get_pandas('XLSX')
-    path.parent.mkdir(parents=True, exist_ok=True)
+    ensure_parent_dir(path)
     frame = pandas.DataFrame.from_records(records)
     try:
         frame.to_excel(path, index=False)

etlplus/file/xml.py

@@ -18,12 +18,14 @@ Notes
 from __future__ import annotations
 
 import xml.etree.ElementTree as ET
-from pathlib import Path
 from typing import Any
 
 from ..types import JSONData
 from ..types import JSONDict
+from ..types import StrPath
 from ..utils import count_records
+from ._io import coerce_path
+from ._io import ensure_parent_dir
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -124,10 +126,7 @@ def _element_to_dict(
             result[tag] = child_data
 
     for key, value in element.attrib.items():
-        if key in result:
-            result[f'@{key}'] = value
-        else:
-            result[key] = value
+        result[f'@{key}'] = value
     return result
 
 
@@ -135,14 +134,14 @@ def _element_to_dict(
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONDict:
     """
     Read XML content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the XML file on disk.
 
     Returns
@@ -150,6 +149,7 @@ def read(
     JSONDict
         Nested dictionary representation of the XML file.
     """
+    path = coerce_path(path)
     tree = ET.parse(path)
     root = tree.getroot()
 
@@ -157,7 +157,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
     *,
     root_tag: str,
@@ -167,7 +167,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the XML file on disk.
     data : JSONData
         Data to write as XML.
@@ -179,6 +179,7 @@ def write(
     int
         The number of records written to the XML file.
     """
+    path = coerce_path(path)
     if isinstance(data, dict) and len(data) == 1:
         root_name, payload = next(iter(data.items()))
         root_element = _dict_to_element(str(root_name), payload)
@@ -186,6 +187,7 @@ def write(
         root_element = _dict_to_element(root_tag, data)
 
     tree = ET.ElementTree(root_element)
+    ensure_parent_dir(path)
     tree.write(path, encoding='utf-8', xml_declaration=True)
 
     return count_records(data)

etlplus/file/xpt.py

@@ -1,8 +1,7 @@
 """
 :mod:`etlplus.file.xpt` module.
 
-Stub helpers for reading/writing SAS Transport (XPT) files (not implemented
-yet).
+Helpers for reading/writing SAS Transport (XPT) files.
 
 Notes
 -----
@@ -19,11 +18,16 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
+from typing import cast
 
 from ..types import JSONData
 from ..types import JSONList
-from . import stub
+from ..types import StrPath
+from ._imports import get_dependency
+from ._imports import get_pandas
+from ._io import coerce_path
+from ._io import ensure_parent_dir
+from ._io import normalize_records
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -39,14 +43,14 @@ __all__ = [
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read XPT content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the XPT file on disk.
 
     Returns
@@ -54,11 +58,22 @@ def read(
     JSONList
         The list of dictionaries read from the XPT file.
     """
-    return stub.read(path, format_name='XPT')
+    path = coerce_path(path)
+    pandas = get_pandas('XPT')
+    pyreadstat = get_dependency('pyreadstat', format_name='XPT')
+    reader = getattr(pyreadstat, 'read_xport', None)
+    if reader is not None:
+        frame, _meta = reader(str(path))
+        return cast(JSONList, frame.to_dict(orient='records'))
+    try:
+        frame = pandas.read_sas(path, format='xport')
+    except TypeError:
+        frame = pandas.read_sas(path)
+    return cast(JSONList, frame.to_dict(orient='records'))
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -66,7 +81,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the XPT file on disk.
     data : JSONData
         Data to write as XPT file. Should be a list of dictionaries or a
@@ -76,5 +91,26 @@ def write(
     -------
     int
         The number of rows written to the XPT file.
+
+    Raises
+    ------
+    ImportError
+        If "pyreadstat" is not installed with write support.
     """
-    return stub.write(path, data, format_name='XPT')
+    path = coerce_path(path)
+    records = normalize_records(data, 'XPT')
+    if not records:
+        return 0
+
+    pandas = get_pandas('XPT')
+    pyreadstat = get_dependency('pyreadstat', format_name='XPT')
+    writer = getattr(pyreadstat, 'write_xport', None)
+    if writer is None:
+        raise ImportError(
+            'XPT write support requires "pyreadstat" with write_xport().',
+        )
+
+    ensure_parent_dir(path)
+    frame = pandas.DataFrame.from_records(records)
+    writer(frame, str(path))
+    return len(records)

etlplus/file/yaml.py

@@ -17,12 +17,13 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
-
 from ..types import JSONData
+from ..types import StrPath
 from ..utils import count_records
 from ._imports import get_yaml
+from ._io import coerce_path
 from ._io import coerce_record_payload
+from ._io import ensure_parent_dir
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -38,7 +39,7 @@ __all__ = [
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONData:
     """
     Read YAML content from *path*.
@@ -47,19 +48,15 @@ def read(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the YAML file on disk.
 
     Returns
     -------
     JSONData
         The structured data read from the YAML file.
-
-    Raises
-    ------
-    TypeError
-        If the YAML root is not an object or an array of objects.
     """
+    path = coerce_path(path)
     with path.open('r', encoding='utf-8') as handle:
         loaded = get_yaml().safe_load(handle)
 
@@ -67,7 +64,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -75,7 +72,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the YAML file on disk.
     data : JSONData
         Data to write as YAML.
@@ -85,6 +82,8 @@ def write(
     int
         The number of records written.
     """
+    path = coerce_path(path)
+    ensure_parent_dir(path)
     with path.open('w', encoding='utf-8') as handle:
         get_yaml().safe_dump(
             data,