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

etlplus/file/arrow.py

@@ -18,13 +18,14 @@ 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 ._io import coerce_path
+from ._io import ensure_parent_dir
 from ._io import normalize_records
 
 # SECTION: EXPORTS ========================================================== #
@@ -37,32 +38,18 @@ __all__ = [
 ]
 
 
-# SECTION: INTERNAL FUNCTIONS =============================================== #
-
-
-def _get_pyarrow() -> Any:
-    """Return the pyarrow module, importing it on first use."""
-    return get_optional_module(
-        'pyarrow',
-        error_message=(
-            'ARROW support requires optional dependency "pyarrow".\n'
-            'Install with: pip install pyarrow'
-        ),
-    )
-
-
 # SECTION: FUNCTIONS ======================================================== #
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read ARROW content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the Apache Arrow file on disk.
 
     Returns
@@ -70,7 +57,8 @@ def read(
     JSONList
         The list of dictionaries read from the Apache Arrow file.
     """
-    pyarrow = _get_pyarrow()
+    path = coerce_path(path)
+    pyarrow = get_dependency('pyarrow', format_name='ARROW')
     with pyarrow.memory_map(str(path), 'r') as source:
         reader = pyarrow.ipc.open_file(source)
         table = reader.read_all()
@@ -78,7 +66,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -86,7 +74,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the ARROW file on disk.
     data : JSONData
         Data to write as ARROW. Should be a list of dictionaries or a
@@ -97,13 +85,14 @@ def write(
     int
         The number of rows written to the ARROW file.
     """
+    path = coerce_path(path)
     records = normalize_records(data, 'ARROW')
     if not records:
         return 0
 
-    pyarrow = _get_pyarrow()
+    pyarrow = get_dependency('pyarrow', format_name='ARROW')
     table = pyarrow.Table.from_pylist(records)
-    path.parent.mkdir(parents=True, exist_ok=True)
+    ensure_parent_dir(path)
     with pyarrow.OSFile(str(path), 'wb') as sink:
         with pyarrow.ipc.new_file(sink, table.schema) as writer:
             writer.write_table(table)

etlplus/file/avro.py

@@ -18,15 +18,16 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
 from typing import Any
 from typing import cast
 
-from etlplus.file._imports import get_fastavro
-
 from ..types import JSONData
 from ..types import JSONDict
 from ..types import JSONList
+from ..types import StrPath
+from ._imports import get_dependency
+from ._io import coerce_path
+from ._io import ensure_parent_dir
 from ._io import normalize_records
 
 # SECTION: EXPORTS ========================================================== #
@@ -122,14 +123,14 @@ def _merge_types(types: list[str]) -> str | list[str]:
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read AVRO content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the AVRO file on disk.
 
     Returns
@@ -137,14 +138,15 @@ def read(
     JSONList
         The list of dictionaries read from the AVRO file.
     """
-    fastavro = get_fastavro()
+    path = coerce_path(path)
+    fastavro = get_dependency('fastavro', format_name='AVRO')
     with path.open('rb') as handle:
         reader = fastavro.reader(handle)
         return [cast(JSONDict, record) for record in reader]
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -152,7 +154,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the AVRO file on disk.
     data : JSONData
         Data to write.
@@ -162,15 +164,16 @@ def write(
     int
         Number of records written.
     """
+    path = coerce_path(path)
     records = normalize_records(data, 'AVRO')
     if not records:
         return 0
 
-    fastavro = get_fastavro()
+    fastavro = get_dependency('fastavro', format_name='AVRO')
     schema = _infer_schema(records)
     parsed_schema = fastavro.parse_schema(schema)
 
-    path.parent.mkdir(parents=True, exist_ok=True)
+    ensure_parent_dir(path)
     with path.open('wb') as handle:
         fastavro.writer(handle, parsed_schema, records)
 

etlplus/file/bson.py

@@ -17,13 +17,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 ._io import coerce_path
+from ._io import ensure_parent_dir
 from ._io import normalize_records
 
 # SECTION: EXPORTS ========================================================== #
@@ -39,7 +41,30 @@ __all__ = [
 # SECTION: INTERNAL FUNCTIONS =============================================== #
 
 
-def _decode_all(bson_module: Any, payload: bytes) -> list[dict[str, Any]]:
+def _decode_all(
+    bson_module: Any,
+    payload: bytes,
+) -> list[dict[str, Any]]:
+    """
+    Decode all BSON documents from raw payload bytes.
+
+    Parameters
+    ----------
+    bson_module : Any
+        The imported BSON module to use for decoding.
+    payload : bytes
+        Raw bytes read from the BSON file.
+
+    Returns
+    -------
+    list[dict[str, Any]]
+        List of decoded BSON documents as dictionaries.
+
+    Raises
+    ------
+    AttributeError
+        If the bson module lacks the required :meth:`decode_all()` method.
+    """
     if hasattr(bson_module, 'decode_all'):
         return bson_module.decode_all(payload)
     if hasattr(bson_module, 'BSON'):
@@ -47,7 +72,30 @@ def _decode_all(bson_module: Any, payload: bytes) -> list[dict[str, Any]]:
     raise AttributeError('bson module lacks decode_all()')
 
 
-def _encode_doc(bson_module: Any, doc: dict[str, Any]) -> bytes:
+def _encode_doc(
+    bson_module: Any,
+    doc: dict[str, Any],
+) -> bytes:
+    """
+    Encode a single BSON document to bytes.
+
+    Parameters
+    ----------
+    bson_module : Any
+        The imported BSON module to use for encoding.
+    doc : dict[str, Any]
+        The BSON document to encode.
+
+    Returns
+    -------
+    bytes
+        The encoded BSON document as bytes.
+
+    Raises
+    ------
+    AttributeError
+        If the bson module lacks the required :meth:`encode()` method.
+    """
     if hasattr(bson_module, 'encode'):
         return bson_module.encode(doc)
     if hasattr(bson_module, 'BSON'):
@@ -55,29 +103,18 @@ def _encode_doc(bson_module: Any, doc: dict[str, Any]) -> bytes:
     raise AttributeError('bson module lacks encode()')
 
 
-def _get_bson() -> Any:
-    """Return the bson module, importing it on first use."""
-    return get_optional_module(
-        'bson',
-        error_message=(
-            'BSON support requires optional dependency "pymongo".\n'
-            'Install with: pip install pymongo'
-        ),
-    )
-
-
 # SECTION: FUNCTIONS ======================================================== #
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read BSON content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the BSON file on disk.
 
     Returns
@@ -85,7 +122,8 @@ def read(
     JSONList
         The list of dictionaries read from the BSON file.
     """
-    bson = _get_bson()
+    path = coerce_path(path)
+    bson = get_dependency('bson', format_name='BSON', pip_name='pymongo')
     with path.open('rb') as handle:
         payload = handle.read()
     docs = _decode_all(bson, payload)
@@ -93,7 +131,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -101,7 +139,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the BSON file on disk.
     data : JSONData
         Data to write as BSON. Should be a list of dictionaries or a
@@ -112,12 +150,13 @@ def write(
     int
         The number of rows written to the BSON file.
     """
-    bson = _get_bson()
+    path = coerce_path(path)
+    bson = get_dependency('bson', format_name='BSON', pip_name='pymongo')
     records = normalize_records(data, 'BSON')
     if not records:
         return 0
 
-    path.parent.mkdir(parents=True, exist_ok=True)
+    ensure_parent_dir(path)
     with path.open('wb') as handle:
         for record in records:
             handle.write(_encode_doc(bson, record))

etlplus/file/cbor.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_cbor() -> Any:
-    """Return the cbor2 module, importing it on first use."""
-    return get_optional_module(
-        'cbor2',
-        error_message=(
-            'CBOR support requires optional dependency "cbor2".\n'
-            'Install with: pip install cbor2'
-        ),
-    )
-
-
 # SECTION: FUNCTIONS ======================================================== #
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONData:
     """
     Read CBOR content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the CBOR file on disk.
 
     Returns
@@ -69,14 +55,15 @@ def read(
     JSONData
         The structured data read from the CBOR file.
     """
-    cbor2 = _get_cbor()
+    path = coerce_path(path)
+    cbor2 = get_dependency('cbor2', format_name='CBOR')
     with path.open('rb') as handle:
         payload = cbor2.loads(handle.read())
     return coerce_record_payload(payload, format_name='CBOR')
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -84,7 +71,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the CBOR file on disk.
     data : JSONData
         Data to write as CBOR file. Should be a list of dictionaries or a
@@ -95,10 +82,11 @@ def write(
     int
         The number of rows written to the CBOR file.
     """
-    cbor2 = _get_cbor()
+    path = coerce_path(path)
+    cbor2 = get_dependency('cbor2', format_name='CBOR')
     records = normalize_records(data, 'CBOR')
     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(cbor2.dumps(payload))
     return len(records)

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

etlplus/file/conf.py

@@ -20,11 +20,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 ========================================================== #
 
@@ -40,14 +40,14 @@ __all__ = [
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read CONF content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the CONF file on disk.
 
     Returns
@@ -59,7 +59,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -67,7 +67,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the CONF file on disk.
     data : JSONData
         Data to write as CONF. Should be a list of dictionaries or a
@@ -78,4 +78,5 @@ def write(
     int
         The number of rows written to the CONF file.
     """
+    path = coerce_path(path)
     return stub.write(path, data, format_name='CONF')

etlplus/file/core.py

@@ -265,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
         -------

etlplus/file/csv.py

@@ -18,10 +18,10 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
-
 from ..types import JSONData
 from ..types import JSONList
+from ..types import StrPath
+from ._io import coerce_path
 from ._io import read_delimited
 from ._io import write_delimited
 
@@ -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.
     """
-    return write_delimited(path, data, delimiter=',')
+    path = coerce_path(path)
+    return write_delimited(path, data, delimiter=',', format_name='CSV')

etlplus/file/dat.py

@@ -19,12 +19,13 @@ Notes
 from __future__ import annotations
 
 import csv
-from pathlib import Path
 from typing import cast
 
 from ..types import JSONData
 from ..types import JSONDict
 from ..types import JSONList
+from ..types import StrPath
+from ._io import coerce_path
 from ._io import write_delimited
 
 # SECTION: EXPORTS ========================================================== #
@@ -41,14 +42,14 @@ __all__ = [
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read DAT content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the DAT file on disk.
 
     Returns
@@ -56,6 +57,7 @@ def read(
     JSONList
         The list of dictionaries read from the DAT file.
     """
+    path = coerce_path(path)
     with path.open('r', encoding='utf-8', newline='') as handle:
         sample = handle.read(4096)
         handle.seek(0)
@@ -95,7 +97,7 @@ def read(
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -103,7 +105,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the DAT file on disk.
     data : JSONData
         Data to write as DAT file. Should be a list of dictionaries or a
@@ -114,4 +116,5 @@ def write(
     int
         The number of rows written to the DAT file.
     """
-    return write_delimited(path, data, delimiter=',')
+    path = coerce_path(path)
+    return write_delimited(path, data, delimiter=',', format_name='DAT')