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

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

@@ -19,12 +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 ._imports import get_pandas
+from ._io import coerce_path
+from ._io import ensure_parent_dir
 from ._io import normalize_records
 
 # SECTION: EXPORTS ========================================================== #
@@ -41,14 +43,14 @@ __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
@@ -61,6 +63,7 @@ def read(
     ImportError
         If optional dependencies for XLSM support are missing.
     """
+    path = coerce_path(path)
     pandas = get_pandas('XLSM')
     try:
         frame = pandas.read_excel(path)
@@ -73,7 +76,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -81,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
@@ -97,12 +100,13 @@ def write(
     ImportError
         If optional dependencies for XLSM support are missing.
     """
+    path = coerce_path(path)
     records = normalize_records(data, 'XLSM')
     if not records:
         return 0
 
     pandas = get_pandas('XLSM')
-    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/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

@@ -18,14 +18,15 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
-from typing import Any
 from typing import cast
 
 from ..types import JSONData
 from ..types import JSONList
-from ._imports import get_optional_module
+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 ========================================================== #
@@ -38,39 +39,18 @@ __all__ = [
 ]
 
 
-# SECTION: INTERNAL HELPERS ================================================ #
-
-
-def _get_pyreadstat() -> Any:
-    """Return the pyreadstat module, importing it on first use."""
-    return get_optional_module(
-        'pyreadstat',
-        error_message=(
-            'XPT support requires optional dependency "pyreadstat".\n'
-            'Install with: pip install pyreadstat'
-        ),
-    )
-
-
-def _raise_readstat_error(err: ImportError) -> None:
-    raise ImportError(
-        'XPT support requires optional dependency "pyreadstat".\n'
-        'Install with: pip install pyreadstat',
-    ) from err
-
-
 # SECTION: FUNCTIONS ======================================================== #
 
 
 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
@@ -78,8 +58,9 @@ def read(
     JSONList
         The list of dictionaries read from the XPT file.
     """
+    path = coerce_path(path)
     pandas = get_pandas('XPT')
-    pyreadstat = _get_pyreadstat()
+    pyreadstat = get_dependency('pyreadstat', format_name='XPT')
     reader = getattr(pyreadstat, 'read_xport', None)
     if reader is not None:
         frame, _meta = reader(str(path))
@@ -88,13 +69,11 @@ def read(
         frame = pandas.read_sas(path, format='xport')
     except TypeError:
         frame = pandas.read_sas(path)
-    except ImportError as err:  # pragma: no cover
-        _raise_readstat_error(err)
     return cast(JSONList, frame.to_dict(orient='records'))
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -102,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
@@ -118,19 +97,20 @@ def write(
     ImportError
         If "pyreadstat" is not installed with write support.
     """
+    path = coerce_path(path)
     records = normalize_records(data, 'XPT')
     if not records:
         return 0
 
     pandas = get_pandas('XPT')
-    pyreadstat = _get_pyreadstat()
+    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().',
         )
 
-    path.parent.mkdir(parents=True, exist_ok=True)
+    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,

etlplus/file/zip.py

@@ -12,6 +12,9 @@ from pathlib import Path
 
 from ..types import JSONData
 from ..types import JSONDict
+from ..types import StrPath
+from ._io import coerce_path
+from ._io import ensure_parent_dir
 from .enums import CompressionFormat
 from .enums import FileFormat
 from .enums import infer_file_format_and_compression
@@ -87,14 +90,14 @@ def _extract_payload(
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONData:
     """
     Read ZIP content from *path* and parse the inner payload(s).
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the ZIP file on disk.
 
     Returns
@@ -107,6 +110,7 @@ def read(
     ValueError
         If the ZIP archive is empty.
     """
+    path = coerce_path(path)
     with zipfile.ZipFile(path, 'r') as archive:
         entries = [entry for entry in archive.infolist() if not entry.is_dir()]
         if not entries:
@@ -137,7 +141,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -145,7 +149,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the ZIP file on disk.
     data : JSONData
         Data to write.
@@ -155,6 +159,7 @@ def write(
     int
         Number of records written.
     """
+    path = coerce_path(path)
     fmt = _resolve_format(path.name)
     inner_name = Path(path.name).with_suffix('').name
 
@@ -165,7 +170,7 @@ def write(
         count = File(tmp_path, fmt).write(data)
         payload = tmp_path.read_bytes()
 
-    path.parent.mkdir(parents=True, exist_ok=True)
+    ensure_parent_dir(path)
     with zipfile.ZipFile(
         path,
         'w',

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

{etlplus-0.17.2.dist-info → etlplus-0.17.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.17.2
+Version: 0.17.4
 Summary: A Swiss Army knife for simple ETL operations
 Home-page: https://github.com/Dagitali/ETLPlus
 Author: ETLPlus Team