etlplus 0.9.2__py3-none-any.whl → 0.10.2__py3-none-any.whl

etlplus/file/bson.py

@@ -1,77 +0,0 @@
-"""
-:mod:`etlplus.file.bson` module.
-
-Helpers for reading/writing Binary JSON (BSON) files.
-
-Notes
------
-- A BSON file is a binary-encoded serialization of JSON-like documents.
-- Common cases:
-    - Data storage in MongoDB.
-    - Efficient data interchange between systems.
-    - Handling of complex data types not supported in standard JSON.
-- Rule of thumb:
-    - If the file follows the BSON specification, use this module for reading
-        and writing.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from ..types import JSONData
-from ..types import JSONList
-from . import stub
-
-# SECTION: EXPORTS ========================================================== #
-
-
-__all__ = [
-    'read',
-    'write',
-]
-
-
-# SECTION: FUNCTIONS ======================================================== #
-
-
-def read(
-    path: Path,
-) -> JSONList:
-    """
-    Read BSON content from ``path``.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the BSON file on disk.
-
-    Returns
-    -------
-    JSONList
-        The list of dictionaries read from the BSON file.
-    """
-    return stub.read(path, format_name='BSON')
-
-
-def write(
-    path: Path,
-    data: JSONData,
-) -> int:
-    """
-    Write ``data`` to BSON at ``path`` and return record count.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the BSON file on disk.
-    data : JSONData
-        Data to write as BSON. Should be a list of dictionaries or a
-        single dictionary.
-
-    Returns
-    -------
-    int
-        The number of rows written to the BSON file.
-    """
-    return stub.write(path, data, format_name='BSON')

etlplus/file/cbor.py

@@ -1,78 +0,0 @@
-"""
-:mod:`etlplus.file.cbor` module.
-
-Helpers for reading/writing Concise Binary Object Representation (CBOR) files.
-
-Notes
------
-- A CBOR file is a binary data format designed for small code size and message
-    size, suitable for constrained environments.
-- Common cases:
-    - IoT data interchange.
-    - Efficient data serialization.
-    - Storage of structured data in a compact binary form.
-- Rule of thumb:
-    - If the file follows the CBOR specification, use this module for reading
-        and writing.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from ..types import JSONData
-from ..types import JSONList
-from . import stub
-
-# SECTION: EXPORTS ========================================================== #
-
-
-__all__ = [
-    'read',
-    'write',
-]
-
-
-# SECTION: FUNCTIONS ======================================================== #
-
-
-def read(
-    path: Path,
-) -> JSONList:
-    """
-    Read CBOR content from ``path``.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the CBOR file on disk.
-
-    Returns
-    -------
-    JSONList
-        The list of dictionaries read from the CBOR file.
-    """
-    return stub.read(path, format_name='CBOR')
-
-
-def write(
-    path: Path,
-    data: JSONData,
-) -> int:
-    """
-    Write ``data`` to CBOR at ``path`` and return record count.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the CBOR file on disk.
-    data : JSONData
-        Data to write as CBOR. Should be a list of dictionaries or a
-        single dictionary.
-
-    Returns
-    -------
-    int
-        The number of rows written to the CBOR file.
-    """
-    return stub.write(path, data, format_name='CBOR')

etlplus/file/cfg.py

@@ -1,79 +0,0 @@
-"""
-:mod:`etlplus.file.cfg` module.
-
-Helpers for reading/writing config (CFG) files.
-
-Notes
------
-- A CFG file is a configuration file that may use various syntaxes, such as
-    INI, YAML, or custom formats.
-- Common cases:
-    - INI-style key-value pairs with sections (such as in Python ecosystems,
-        using ``configparser``).
-    - YAML-like structures with indentation.
-    - Custom formats specific to certain applications.
-- Rule of thumb:
-    - If the file follows a standard format like INI or YAML, consider using
-        dedicated parsers.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from ..types import JSONData
-from ..types import JSONList
-from . import stub
-
-# SECTION: EXPORTS ========================================================== #
-
-
-__all__ = [
-    'read',
-    'write',
-]
-
-
-# SECTION: FUNCTIONS ======================================================== #
-
-
-def read(
-    path: Path,
-) -> JSONList:
-    """
-    Read CFG content from ``path``.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the CFG file on disk.
-
-    Returns
-    -------
-    JSONList
-        The list of dictionaries read from the CFG file.
-    """
-    return stub.read(path, format_name='CFG')
-
-
-def write(
-    path: Path,
-    data: JSONData,
-) -> int:
-    """
-    Write ``data`` to CFG file at ``path`` and return record count.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the CFG file on disk.
-    data : JSONData
-        Data to write as CFG file. Should be a list of dictionaries or a
-        single dictionary.
-
-    Returns
-    -------
-    int
-        The number of rows written to the CFG file.
-    """
-    return stub.write(path, data, format_name='CFG')

etlplus/file/conf.py

@@ -1,80 +0,0 @@
-"""
-:mod:`etlplus.file.conf` module.
-
-Helpers for reading/writing config (CONF) files.
-
-Notes
------
-- A CONF file is a configuration file that may use various syntaxes, such as
-    INI, YAML, or custom formats.
-- Common cases:
-    - INI-style key-value pairs with sections.
-    - YAML-like structures with indentation.
-    - Custom formats specific to certain applications (such as Unix-like
-        systems, where ``.conf`` is a strong convention for "This is a
-        configuration file").
-- Rule of thumb:
-    - If the file follows a standard format like INI or YAML, consider using
-        dedicated parsers.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from ..types import JSONData
-from ..types import JSONList
-from . import stub
-
-# SECTION: EXPORTS ========================================================== #
-
-
-__all__ = [
-    'read',
-    'write',
-]
-
-
-# SECTION: FUNCTIONS ======================================================== #
-
-
-def read(
-    path: Path,
-) -> JSONList:
-    """
-    Read CONF content from ``path``.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the CONF file on disk.
-
-    Returns
-    -------
-    JSONList
-        The list of dictionaries read from the CONF file.
-    """
-    return stub.read(path, format_name='CONF')
-
-
-def write(
-    path: Path,
-    data: JSONData,
-) -> int:
-    """
-    Write ``data`` to CONF at ``path`` and return record count.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the CONF file on disk.
-    data : JSONData
-        Data to write as CONF. Should be a list of dictionaries or a
-        single dictionary.
-
-    Returns
-    -------
-    int
-        The number of rows written to the CONF file.
-    """
-    return stub.write(path, data, format_name='CONF')

etlplus/file/core.py

@@ -1,322 +0,0 @@
-"""
-:mod:`etlplus.file.core` module.
-
-Shared helpers for reading and writing structured and semi-structured data
-files.
-"""
-
-from __future__ import annotations
-
-import importlib
-import inspect
-from dataclasses import dataclass
-from functools import cache
-from pathlib import Path
-from types import ModuleType
-
-from ..types import JSONData
-from . import xml
-from .enums import FileFormat
-from .enums import infer_file_format_and_compression
-
-# SECTION: EXPORTS ========================================================== #
-
-
-__all__ = ['File']
-
-
-# SECTION: INTERNAL FUNCTIONS =============================================== #
-
-
-def _accepts_root_tag(handler: object) -> bool:
-    """
-    Return True when ``handler`` supports a ``root_tag`` argument.
-
-    Parameters
-    ----------
-    handler : object
-        Callable to inspect.
-
-    Returns
-    -------
-    bool
-        True if ``root_tag`` is accepted by the handler.
-    """
-    if not callable(handler):
-        return False
-    try:
-        signature = inspect.signature(handler)
-    except (TypeError, ValueError):
-        return False
-    for param in signature.parameters.values():
-        if param.kind is param.VAR_KEYWORD:
-            return True
-    return 'root_tag' in signature.parameters
-
-
-@cache
-def _module_for_format(file_format: FileFormat) -> ModuleType:
-    """
-    Import and return the module for ``file_format``.
-
-    Parameters
-    ----------
-    file_format : FileFormat
-        File format enum value.
-
-    Returns
-    -------
-    ModuleType
-        The module implementing IO for the format.
-    """
-    return importlib.import_module(f'{__package__}.{file_format.value}')
-
-
-# SECTION: CLASSES ========================================================== #
-
-
-@dataclass(slots=True)
-class File:
-    """
-    Convenience wrapper around structured file IO.
-
-    This class encapsulates the one-off helpers in this module as convenient
-    instance methods while retaining the original function API for
-    backward compatibility (those functions delegate to this class).
-
-    Attributes
-    ----------
-    path : Path
-        Path to the file on disk.
-    file_format : FileFormat | None, optional
-        Explicit format. If omitted, the format is inferred from the file
-        extension (``.csv``, ``.json``, etc.).
-
-    Parameters
-    ----------
-    path : StrPath
-        Path to the file on disk.
-    file_format : FileFormat | str | None, optional
-        Explicit format. If omitted, the format is inferred from the file
-        extension (``.csv``, ``.json``, etc.).
-    """
-
-    # -- Attributes -- #
-
-    path: Path
-    file_format: FileFormat | None = None
-
-    # -- Magic Methods (Object Lifecycle) -- #
-
-    def __post_init__(self) -> None:
-        """
-        Auto-detect and set the file format on initialization.
-
-        If no explicit ``file_format`` is provided, attempt to infer it from
-        the file path's extension and update :attr:`file_format`. If the
-        extension is unknown, the attribute is left as ``None`` and will be
-        validated later by :meth:`_ensure_format`.
-        """
-        self.path = Path(self.path)
-        self.file_format = self._coerce_format(self.file_format)
-        if self.file_format is None:
-            self.file_format = self._maybe_guess_format()
-
-    # -- Internal Instance Methods -- #
-
-    def _assert_exists(self) -> None:
-        """
-        Raise FileNotFoundError if :attr:`path` does not exist.
-
-        This centralizes existence checks across multiple read methods.
-        """
-        if not self.path.exists():
-            raise FileNotFoundError(f'File not found: {self.path}')
-
-    def _coerce_format(
-        self,
-        file_format: FileFormat | str | None,
-    ) -> FileFormat | None:
-        """
-        Normalize the file format input.
-
-        Parameters
-        ----------
-        file_format : FileFormat | str | None
-            File format specifier. Strings are coerced into
-            :class:`FileFormat`.
-
-        Returns
-        -------
-        FileFormat | None
-            A normalized file format, or ``None`` when unspecified.
-        """
-        if file_format is None or isinstance(file_format, FileFormat):
-            return file_format
-        return FileFormat.coerce(file_format)
-
-    def _ensure_format(self) -> FileFormat:
-        """
-        Resolve the active format, guessing from extension if needed.
-
-        Returns
-        -------
-        FileFormat
-            The resolved file format.
-        """
-        return (
-            self.file_format
-            if self.file_format is not None
-            else self._guess_format()
-        )
-
-    def _guess_format(self) -> FileFormat:
-        """
-        Infer the file format from the filename extension.
-
-        Returns
-        -------
-        FileFormat
-            The inferred file format based on the file extension.
-
-        Raises
-        ------
-        ValueError
-            If the extension is unknown or unsupported.
-        """
-        fmt, compression = infer_file_format_and_compression(self.path)
-        if fmt is not None:
-            return fmt
-        if compression is not None:
-            raise ValueError(
-                'Cannot infer file format from compressed file '
-                f'{self.path!r} with compression {compression.value!r}',
-            )
-        raise ValueError(
-            f'Cannot infer file format from extension {self.path.suffix!r}',
-        )
-
-    def _maybe_guess_format(self) -> FileFormat | None:
-        """
-        Try to infer the format, returning ``None`` if it cannot be inferred.
-
-        Returns
-        -------
-        FileFormat | None
-            The inferred format, or ``None`` if inference fails.
-        """
-        try:
-            return self._guess_format()
-        except ValueError:
-            # Leave as None; _ensure_format() will raise on use if needed.
-            return None
-
-    def _resolve_handler(self, name: str) -> object:
-        """
-        Resolve a handler from the module for the active file format.
-
-        Parameters
-        ----------
-        name : str
-            Attribute name to resolve (``'read'`` or ``'write'``).
-
-        Returns
-        -------
-        object
-            Callable handler exported by the module.
-
-        Raises
-        ------
-        ValueError
-            If the resolved file format is unsupported.
-        """
-        module = self._resolve_module()
-        try:
-            return getattr(module, name)
-        except AttributeError as e:
-            raise ValueError(
-                f'Module {module.__name__} does not implement {name}()',
-            ) from e
-
-    def _resolve_module(self) -> ModuleType:
-        """
-        Resolve the IO module for the active file format.
-
-        Returns
-        -------
-        ModuleType
-            The module that implements read/write for the format.
-
-        Raises
-        ------
-        ValueError
-            If the resolved file format is unsupported.
-        """
-        fmt = self._ensure_format()
-        try:
-            return _module_for_format(fmt)
-        except ModuleNotFoundError as e:
-            raise ValueError(f'Unsupported format: {fmt}') from e
-
-    # -- Instance Methods -- #
-
-    def read(self) -> JSONData:
-        """
-        Read structured data from :attr:`path` using :attr:`file_format`.
-
-        Returns
-        -------
-        JSONData
-            The structured data read from the file.
-
-        Raises
-        ------
-        TypeError
-            If the resolved 'read' handler is not callable.
-        """
-        self._assert_exists()
-        reader = self._resolve_handler('read')
-        if callable(reader):
-            return reader(self.path)
-        else:
-            raise TypeError(
-                f"'read' handler for format {self.file_format} "
-                'is not callable',
-            )
-
-    def write(
-        self,
-        data: JSONData,
-        *,
-        root_tag: str = xml.DEFAULT_XML_ROOT,
-    ) -> int:
-        """
-        Write ``data`` to :attr:`path` using :attr:`file_format`.
-
-        Parameters
-        ----------
-        data : JSONData
-            Data to write to the file.
-        root_tag : str, optional
-            Root tag name to use when writing XML files. Defaults to
-            ``'root'``.
-
-        Returns
-        -------
-        int
-            The number of records written.
-
-        Raises
-        ------
-        TypeError
-            If the resolved 'write' handler is not callable.
-        """
-        writer = self._resolve_handler('write')
-        if not callable(writer):
-            raise TypeError(
-                f"'write' handler for format {self.file_format} "
-                'is not callable',
-            )
-        if _accepts_root_tag(writer):
-            return writer(self.path, data, root_tag=root_tag)
-        return writer(self.path, data)

etlplus/file/csv.py

@@ -1,79 +0,0 @@
-"""
-:mod:`etlplus.file.csv` module.
-
-Helpers for reading/writing Comma-Separated Values (CSV) files.
-
-Notes
------
-- A CSV file is a plain text file that uses commas to separate values.
-- Common cases:
-    - Each line in the file represents a single record.
-    - The first line often contains headers that define the column names.
-    - Values may be enclosed in quotes, especially if they contain commas
-        or special characters.
-- Rule of thumb:
-    - If the file follows the CSV specification, use this module for
-        reading and writing.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from ..types import JSONData
-from ..types import JSONList
-from ._io import read_delimited
-from ._io import write_delimited
-
-# SECTION: EXPORTS ========================================================== #
-
-
-__all__ = [
-    'read',
-    'write',
-]
-
-
-# SECTION: FUNCTIONS ======================================================== #
-
-
-def read(
-    path: Path,
-) -> JSONList:
-    """
-    Read CSV content from ``path``.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the CSV file on disk.
-
-    Returns
-    -------
-    JSONList
-        The list of dictionaries read from the CSV file.
-    """
-    return read_delimited(path, delimiter=',')
-
-
-def write(
-    path: Path,
-    data: JSONData,
-) -> int:
-    """
-    Write ``data`` to CSV at ``path`` and return record count.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the CSV file on disk.
-    data : JSONData
-        Data to write as CSV. Should be a list of dictionaries or a
-        single dictionary.
-
-    Returns
-    -------
-    int
-        The number of rows written to the CSV file.
-    """
-    return write_delimited(path, data, delimiter=',')