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

etlplus/file/pb.py

@@ -1,29 +1,28 @@
 """
 :mod:`etlplus.file.pb` module.
 
-Stub helpers for reading/writing Protocol Buffer (PB) files (not implemented
-yet).
+Helpers for reading/writing Protocol Buffers binary (PB) files.
 
 Notes
 -----
-- PB (a.k.a. Protobuff) is a binary serialization format developed by Google
-    for structured data.
+- A PB file contains Protocol Buffers (Protobuf) binary-encoded messages.
 - Common cases:
-    - Data interchange between services.
-    - Efficient storage of structured data.
-    - Communication in distributed systems.
+    - Serialized payloads emitted by services or SDKs.
+    - Binary payload dumps for debugging or transport.
 - Rule of thumb:
-    - If the file follows the Protocol Buffer specification, use this module
-        for reading and writing.
+    - Use this module when you need to store or transport raw protobuf bytes.
 """
 
 from __future__ import annotations
 
-from pathlib import Path
+import base64
 
 from ..types import JSONData
-from ..types import JSONList
-from . import stub
+from ..types import StrPath
+from ._io import coerce_path
+from ._io import ensure_parent_dir
+from ._io import require_dict_payload
+from ._io import require_str_key
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -39,26 +38,29 @@ __all__ = [
 
 
 def read(
-    path: Path,
-) -> JSONList:
+    path: StrPath,
+) -> JSONData:
     """
     Read PB content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the PB file on disk.
 
     Returns
     -------
-    JSONList
-        The list of dictionaries read from the PB file.
+    JSONData
+        The structured data read from the PB file.
     """
-    return stub.read(path, format_name='PB')
+    path = coerce_path(path)
+    payload = path.read_bytes()
+    encoded = base64.b64encode(payload).decode('ascii')
+    return {'payload_base64': encoded}
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -66,15 +68,25 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the PB file on disk.
     data : JSONData
-        Data to write as PB. Should be a list of dictionaries or a
-        single dictionary.
+        Data to write as PB. Should be a dictionary with ``payload_base64``.
 
     Returns
     -------
     int
-        The number of rows written to the PB file.
+        The number of records written to the PB file.
     """
-    return stub.write(path, data, format_name='PB')
+    path = coerce_path(path)
+    payload = require_dict_payload(data, format_name='PB')
+    payload_base64 = require_str_key(
+        payload,
+        format_name='PB',
+        key='payload_base64',
+    )
+
+    decoded = base64.b64decode(payload_base64.encode('ascii'))
+    ensure_parent_dir(path)
+    path.write_bytes(decoded)
+    return 1

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

etlplus/file/properties.py

@@ -1,8 +1,7 @@
 """
 :mod:`etlplus.file.properties` module.
 
-Stub helpers for reading/writing properties (PROPERTIES) files (not implemented
-yet).
+Helpers for reading/writing properties (PROPERTIES) files.
 
 Notes
 -----
@@ -19,11 +18,13 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
-
 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 ========================================================== #
 
@@ -39,26 +40,45 @@ __all__ = [
 
 
 def read(
-    path: Path,
-) -> JSONList:
+    path: StrPath,
+) -> JSONData:
     """
     Read PROPERTIES content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the PROPERTIES file on disk.
 
     Returns
     -------
-    JSONList
-        The list of dictionaries read from the PROPERTIES file.
+    JSONData
+        The structured data read from the PROPERTIES file.
     """
-    return stub.read(path, format_name='PROPERTIES')
+    path = coerce_path(path)
+    payload: JSONDict = {}
+    for line in path.read_text(encoding='utf-8').splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith(('#', '!')):
+            continue
+        separator_index = -1
+        for sep in ('=', ':'):
+            if sep in stripped:
+                separator_index = stripped.find(sep)
+                break
+        if separator_index == -1:
+            key = stripped
+            value = ''
+        else:
+            key = stripped[:separator_index].strip()
+            value = stripped[separator_index + 1:].strip()
+        if key:
+            payload[key] = value
+    return payload
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -66,15 +86,21 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the PROPERTIES file on disk.
     data : JSONData
-        Data to write as PROPERTIES. Should be a list of dictionaries or a
-        single dictionary.
+        Data to write as PROPERTIES. Should be a dictionary.
 
     Returns
     -------
     int
-        The number of rows written to the PROPERTIES file.
+        The number of records written to the PROPERTIES file.
     """
-    return stub.write(path, data, format_name='PROPERTIES')
+    path = coerce_path(path)
+    payload = require_dict_payload(data, format_name='PROPERTIES')
+
+    ensure_parent_dir(path)
+    with path.open('w', encoding='utf-8', newline='') as handle:
+        for key in sorted(payload.keys()):
+            handle.write(f'{key}={stringify_value(payload[key])}\n')
+    return 1

etlplus/file/proto.py

@@ -1,8 +1,7 @@
 """
 :mod:`etlplus.file.proto` module.
 
-Stub helpers for reading/writing Protocol Buffers schema (PROTO) files (not
-implemented yet).
+Helpers for reading/writing Protocol Buffers schema (PROTO) files.
 
 Notes
 -----
@@ -18,11 +17,12 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
-
 from ..types import JSONData
-from ..types import JSONList
-from . import stub
+from ..types import StrPath
+from ._io import coerce_path
+from ._io import ensure_parent_dir
+from ._io import require_dict_payload
+from ._io import require_str_key
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -38,26 +38,27 @@ __all__ = [
 
 
 def read(
-    path: Path,
-) -> JSONList:
+    path: StrPath,
+) -> JSONData:
     """
     Read PROTO content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the PROTO file on disk.
 
     Returns
     -------
-    JSONList
-        The list of dictionaries read from the PROTO file.
+    JSONData
+        The structured data read from the PROTO file.
     """
-    return stub.read(path, format_name='PROTO')
+    path = coerce_path(path)
+    return {'schema': path.read_text(encoding='utf-8')}
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -65,15 +66,20 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the PROTO file on disk.
     data : JSONData
-        Data to write as PROTO. Should be a list of dictionaries or a
-        single dictionary.
+        Data to write as PROTO. Should be a dictionary with ``schema``.
 
     Returns
     -------
     int
-        The number of rows written to the PROTO file.
+        The number of records written to the PROTO file.
     """
-    return stub.write(path, data, format_name='PROTO')
+    path = coerce_path(path)
+    payload = require_dict_payload(data, format_name='PROTO')
+    schema = require_str_key(payload, format_name='PROTO', key='schema')
+
+    ensure_parent_dir(path)
+    path.write_text(schema, encoding='utf-8')
+    return 1

etlplus/file/psv.py

@@ -1,8 +1,7 @@
 """
 :mod:`etlplus.file.psv` module.
 
-Stub helpers for reading/writing Pipe-Separated Values (PSV) files (not
-implemented yet).
+Helpers for reading/writing Pipe-Separated Values (PSV) files.
 
 Notes
 -----
@@ -20,11 +19,12 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
-
 from ..types import JSONData
 from ..types import JSONList
-from . import stub
+from ..types import StrPath
+from ._io import coerce_path
+from ._io import read_delimited
+from ._io import write_delimited
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -40,14 +40,14 @@ __all__ = [
 
 
 def read(
-    path: Path,
+    path: StrPath,
 ) -> JSONList:
     """
     Read PSV content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the PSV file on disk.
 
     Returns
@@ -55,11 +55,11 @@ def read(
     JSONList
         The list of dictionaries read from the PSV file.
     """
-    return stub.read(path, format_name='PSV')
+    return read_delimited(path, delimiter='|')
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -67,7 +67,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the PSV file on disk.
     data : JSONData
         Data to write as PSV file. Should be a list of dictionaries or a
@@ -78,4 +78,5 @@ def write(
     int
         The number of rows written to the PSV file.
     """
-    return stub.write(path, data, format_name='PSV')
+    path = coerce_path(path)
+    return write_delimited(path, data, delimiter='|', format_name='PSV')

etlplus/file/rda.py

@@ -1,8 +1,7 @@
 """
 :mod:`etlplus.file.rda` module.
 
-Stub helpers for reading/writing RData workspace/object bundle (RDA) files (not
-implemented yet).
+Helpers for reading/writing RData workspace/object bundle (RDA) files.
 
 Notes
 -----
@@ -19,11 +18,15 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
-
 from ..types import JSONData
-from ..types import JSONList
-from . import stub
+from ..types import JSONDict
+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
+from ._r import coerce_r_object
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -39,26 +42,38 @@ __all__ = [
 
 
 def read(
-    path: Path,
-) -> JSONList:
+    path: StrPath,
+) -> JSONData:
     """
     Read RDA content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the RDA file on disk.
 
     Returns
     -------
-    JSONList
-        The list of dictionaries read from the RDA file.
+    JSONData
+        The structured data read from the RDA file.
     """
-    return stub.read(path, format_name='RDA')
+    path = coerce_path(path)
+    pyreadr = get_dependency('pyreadr', format_name='RDA')
+    pandas = get_pandas('RDA')
+    result = pyreadr.read_r(str(path))
+    if not result:
+        return []
+    if len(result) == 1:
+        value = next(iter(result.values()))
+        return coerce_r_object(value, pandas)
+    payload: JSONDict = {}
+    for key, value in result.items():
+        payload[str(key)] = coerce_r_object(value, pandas)
+    return payload
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -66,7 +81,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the RDA file on disk.
     data : JSONData
         Data to write as RDA file. Should be a list of dictionaries or a
@@ -76,5 +91,32 @@ def write(
     -------
     int
         The number of rows written to the RDA file.
+
+    Raises
+    ------
+    ImportError
+        If "pyreadr" is not installed with write support.
     """
-    return stub.write(path, data, format_name='RDA')
+    path = coerce_path(path)
+    pyreadr = get_dependency('pyreadr', format_name='RDA')
+    pandas = get_pandas('RDA')
+    records = normalize_records(data, 'RDA')
+    frame = pandas.DataFrame.from_records(records)
+    count = len(records)
+
+    writer = getattr(pyreadr, 'write_rdata', None) or getattr(
+        pyreadr,
+        'write_rda',
+        None,
+    )
+    if writer is None:
+        raise ImportError(
+            'RDA write support requires "pyreadr" with write_rdata().',
+        )
+
+    ensure_parent_dir(path)
+    try:
+        writer(str(path), frame, df_name='data')
+    except TypeError:
+        writer(str(path), frame)
+    return count

etlplus/file/rds.py

@@ -1,7 +1,7 @@
 """
 :mod:`etlplus.file.rds` module.
 
-Stub helpers for reading/writing R (RDS) data files (not implemented yet).
+Helpers for reading/writing R (RDS) data files.
 
 Notes
 -----
@@ -18,11 +18,15 @@ Notes
 
 from __future__ import annotations
 
-from pathlib import Path
-
 from ..types import JSONData
-from ..types import JSONList
-from . import stub
+from ..types import JSONDict
+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
+from ._r import coerce_r_object
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -38,26 +42,38 @@ __all__ = [
 
 
 def read(
-    path: Path,
-) -> JSONList:
+    path: StrPath,
+) -> JSONData:
     """
     Read RDS content from *path*.
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the RDS file on disk.
 
     Returns
     -------
-    JSONList
-        The list of dictionaries read from the RDS file.
+    JSONData
+        The structured data read from the RDS file.
     """
-    return stub.read(path, format_name='RDS')
+    path = coerce_path(path)
+    pyreadr = get_dependency('pyreadr', format_name='RDS')
+    pandas = get_pandas('RDS')
+    result = pyreadr.read_r(str(path))
+    if not result:
+        return []
+    if len(result) == 1:
+        value = next(iter(result.values()))
+        return coerce_r_object(value, pandas)
+    payload: JSONDict = {}
+    for key, value in result.items():
+        payload[str(key)] = coerce_r_object(value, pandas)
+    return payload
 
 
 def write(
-    path: Path,
+    path: StrPath,
     data: JSONData,
 ) -> int:
     """
@@ -65,7 +81,7 @@ def write(
 
     Parameters
     ----------
-    path : Path
+    path : StrPath
         Path to the RDS file on disk.
     data : JSONData
         Data to write as RDS file. Should be a list of dictionaries or a
@@ -75,5 +91,25 @@ def write(
     -------
     int
         The number of rows written to the RDS file.
+
+    Raises
+    ------
+    ImportError
+        If "pyreadr" is not installed with write support.
     """
-    return stub.write(path, data, format_name='RDS')
+    path = coerce_path(path)
+    pyreadr = get_dependency('pyreadr', format_name='RDS')
+    pandas = get_pandas('RDS')
+    records = normalize_records(data, 'RDS')
+    frame = pandas.DataFrame.from_records(records)
+    count = len(records)
+
+    writer = getattr(pyreadr, 'write_rds', None)
+    if writer is None:
+        raise ImportError(
+            'RDS write support requires "pyreadr" with write_rds().',
+        )
+
+    ensure_parent_dir(path)
+    writer(str(path), frame)
+    return count