pythonwrench 0.6.4__py3-none-any.whl

pythonwrench/serialization/jsonl.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from io import StringIO, TextIOBase
+from os import PathLike
+from pathlib import Path
+from typing import Union
+
+from pythonwrench.cast import as_builtin
+from pythonwrench.functools import function_alias
+from pythonwrench.semver import Version
+from pythonwrench.serialization._core import _setup_output_fpath
+from pythonwrench.serialization.json import (
+    _serialize_json,
+    dumps_json,
+    load_json,
+    loads_json,
+)
+from pythonwrench.warnings import warn_once
+
+__all__ = [
+    "dump_jsonl",
+    "dumps_jsonl",
+    "save_jsonl",
+    "load_jsonl",
+    "loads_jsonl",
+    "read_jsonl",
+]
+
+# -- Dump / Save / Serialize content to JSONL --
+
+
+def dump_jsonl(
+    data: list,
+    file: Union[str, Path, None, TextIOBase] = None,
+    /,
+    *,
+    overwrite: bool = True,
+    make_parents: bool = True,
+    to_builtins: bool = False,
+    # JSON dump kwargs
+    ensure_ascii: bool = False,
+    **json_dumps_kwds,
+) -> str:
+    r"""Dump content to JSONL format into a string and/or file.
+
+    Args:
+        data: Data to dump to JSONL.
+        file: Optional filepath to save dumped data. Not used if None. defaults to None.
+        overwrite: If True, overwrite target filepath. defaults to True.
+        make_parents: Build intermediate directories to filepath. defaults to True.
+        to_builtins: If True, converts data to builtin equivalent before saving. defaults to False.
+        ensure_ascii: Ensure only ASCII characters. defaults to False.
+        \*\*json_dump_kwds: Other args passed to `json.dumps`.
+
+    Returns:
+        Dumped content as string.
+    """
+    content = dumps_json(
+        data,
+        to_builtins=to_builtins,
+        ensure_ascii=ensure_ascii,
+        **json_dumps_kwds,
+    )
+
+    if isinstance(file, (str, Path, PathLike)):
+        file = _setup_output_fpath(file, overwrite=overwrite, make_parents=make_parents)
+        with open(file, "w") as opened_file:
+            opened_file.write(content)
+    elif isinstance(file, TextIOBase):
+        file.write(content)
+    elif file is None:
+        pass
+    else:
+        msg = f"Invalid argument type {type(file)}. (expected one of str, Path, TextIOBase, None)"
+        raise TypeError(msg)
+
+    return content
+
+
+def dumps_jsonl(
+    data: list,
+    /,
+    *,
+    to_builtins: bool = False,
+    # JSON dump kwargs
+    ensure_ascii: bool = False,
+    **json_dumps_kwds,
+) -> str:
+    """Perform the dumps jsonl operation."""
+    with StringIO() as buffer:
+        _serialize_jsonl(
+            data,
+            buffer,
+            to_builtins=to_builtins,
+            ensure_ascii=ensure_ascii,
+            **json_dumps_kwds,
+        )
+        content = buffer.getvalue()
+    return content
+
+
+def save_jsonl(
+    data: list,
+    file: Union[str, Path, PathLike, TextIOBase],
+    /,
+    *,
+    overwrite: bool = True,
+    make_parents: bool = True,
+    to_builtins: bool = False,
+    # JSON dump kwargs
+    ensure_ascii: bool = False,
+    **json_dumps_kwds,
+) -> None:
+    """Save jsonl."""
+    if isinstance(file, (str, Path, PathLike)):
+        file = _setup_output_fpath(file, overwrite=overwrite, make_parents=make_parents)
+        file = open(file, "w")
+        close = True
+    elif isinstance(file, TextIOBase):
+        close = False
+    else:
+        msg = f"Invalid argument type {type(file)}. (expected one of str, Path, PathLike, TextIOBase)"
+        raise TypeError(msg)
+
+    _serialize_jsonl(
+        data,
+        file,
+        to_builtins=to_builtins,
+        ensure_ascii=ensure_ascii,
+        **json_dumps_kwds,
+    )
+
+    if close:
+        file.close()
+
+
+def _serialize_jsonl(
+    data: list,
+    buffer: TextIOBase,
+    /,
+    *,
+    to_builtins: bool = False,
+    **json_dumps_kwds,
+) -> None:
+    """Perform the serialize jsonl operation."""
+    if to_builtins:
+        data = as_builtin(data)
+
+    indent = json_dumps_kwds.get("indent", None)
+    if indent is not None:
+        warn_once(f"Invalid argument {indent=}. It will be replaced by indent=None")
+        json_dumps_kwds["indent"] = None
+
+    for data_i in data:
+        _serialize_json(data_i, buffer, to_builtins=False, **json_dumps_kwds)
+        buffer.write("\n")
+
+
+# -- Load / Read / Parse JSONL content --
+
+
+def load_jsonl(
+    file: Union[str, Path, PathLike, TextIOBase],
+    /,
+    **json_loads_kwds,
+) -> list:
+    """Load jsonl."""
+    if isinstance(file, (str, Path, PathLike)):
+        file = open(file, "r")
+        close = True
+    else:
+        close = False
+
+    data = _parse_jsonl(file, **json_loads_kwds)
+    if close:
+        file.close()
+    return data
+
+
+def loads_jsonl(content: str, /, **json_loads_kwds) -> list:
+    """Load s jsonl."""
+    with StringIO(content) as buffer:
+        return _parse_jsonl(buffer, **json_loads_kwds)
+
+
+@function_alias(load_json)
+def read_jsonl(*args, **kwargs):
+    """Read jsonl."""
+    ...
+
+
+def _parse_jsonl(buffer: TextIOBase, **json_loads_kwds) -> list:
+    """Parse jsonl."""
+    data_lst = []
+    while True:
+        content = buffer.readline()
+        if content == "":
+            break
+        content = _removesuffix(content, "\n")
+        data = loads_json(content, **json_loads_kwds)
+        data_lst.append(data)
+    return data_lst
+
+
+def _removesuffix(x: str, suffix: str) -> str:
+    """Equivalent to str.removesuffix for python < 3.9.0."""
+    if Version.python() >= Version("3.9.0"):
+        return x.removesuffix(suffix)
+
+    size = len(suffix)
+    if x[size:] != suffix:
+        return x
+    else:
+        return x[:size]

pythonwrench/serialization/pickle.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import os
+import pickle
+from io import BytesIO
+from os import PathLike
+from pathlib import Path
+from typing import Any, BinaryIO, Union
+
+from pythonwrench.cast import as_builtin
+from pythonwrench.functools import function_alias
+from pythonwrench.serialization._core import _setup_output_fpath
+
+# -- Dump / Save / Serialize content to PICKLE --
+
+
+def dump_pickle(
+    data: Any,
+    file: Union[str, Path, os.PathLike, BinaryIO, None] = None,
+    /,
+    *,
+    overwrite: bool = True,
+    make_parents: bool = True,
+    to_builtins: bool = False,
+    **pkl_dumps_kwds,
+) -> bytes:
+    r"""Dump content to PICKLE format into bytes and/or file.
+
+    Args:
+        data: Data to dump to PICKLE.
+        file: Optional filepath to save dumped data. Not used if None. defaults to None.
+        overwrite: If True, overwrite target filepath. defaults to True.
+        make_parents: Build intermediate directories to filepath. defaults to True.
+        to_builtins: If True, converts data to builtin equivalent before saving. defaults to False.
+        \*\*pkl_dumps_kwds: Other args passed to `pickle.dumps`.
+
+    Returns:
+        Dumped content as bytes.
+    """
+    content = dumps_pickle(
+        data,
+        to_builtins=to_builtins,
+        **pkl_dumps_kwds,
+    )
+
+    if isinstance(file, (str, Path, PathLike)):
+        file = _setup_output_fpath(file, overwrite=overwrite, make_parents=make_parents)
+        with open(file, "wb") as opened_file:
+            opened_file.write(content)
+    elif isinstance(file, BinaryIO):
+        file.write(content)
+    elif file is None:
+        pass
+    else:
+        msg = f"Invalid argument type {type(file)}. (expected one of str, Path, TextIOBase, None)"
+        raise TypeError(msg)
+
+    return content
+
+
+def dumps_pickle(
+    data: Any,
+    /,
+    *,
+    to_builtins: bool = False,
+    **pkl_dumps_kwds,
+) -> bytes:
+    r"""Dump content to PICKLE format into bytes.
+
+    Args:
+        data: Data to dump to PICKLE.
+        to_builtins: If True, converts data to builtin equivalent before saving. defaults to False.
+        \*\*pkl_dumps_kwds: Other args passed to `pickle.dumps`.
+
+    Returns:
+        Dumped content as bytes.
+    """
+    with BytesIO() as buffer:
+        _serialize_pickle(
+            data,
+            buffer,
+            to_builtins=to_builtins,
+            **pkl_dumps_kwds,
+        )
+        content = buffer.getvalue()
+    return content
+
+
+def save_pickle(
+    data: Any,
+    file: Union[str, Path, PathLike, BinaryIO],
+    /,
+    *,
+    overwrite: bool = True,
+    make_parents: bool = True,
+    to_builtins: bool = False,
+    **pkl_dumps_kwds,
+) -> None:
+    r"""Dump content to PICKLE format into file.
+
+    Args:
+        data: Data to dump to PICKLE.
+        file: Filepath to save dumped data.
+        overwrite: If True, overwrite target filepath. defaults to True.
+        make_parents: Build intermediate directories to filepath. defaults to True.
+        to_builtins: If True, converts data to builtin equivalent before saving. defaults to False.
+        \*\*pkl_dumps_kwds: Other args passed to `pickle.dumps`.
+    """
+    if isinstance(file, (str, Path, PathLike)):
+        file = _setup_output_fpath(file, overwrite=overwrite, make_parents=make_parents)
+        file = open(file, "wb")
+        close = True
+    elif isinstance(file, BinaryIO):
+        close = False
+    else:
+        msg = f"Invalid argument type {type(file)}. (expected one of str, Path, PathLike, TextIOBase)"
+        raise TypeError(msg)
+
+    _serialize_pickle(
+        data,
+        file,
+        to_builtins=to_builtins,
+        **pkl_dumps_kwds,
+    )
+
+    if close:
+        file.close()
+
+
+def _serialize_pickle(
+    data: Any,
+    buffer: BinaryIO,
+    /,
+    *,
+    to_builtins: bool = False,
+    **pkl_dump_kwds,
+) -> None:
+    """Perform the serialize pickle operation."""
+    if to_builtins:
+        data = as_builtin(data)
+    return pickle.dump(data, buffer, **pkl_dump_kwds)
+
+
+# -- Load / Read / Parse PICKLE content --
+
+
+def load_pickle(file: Union[str, Path, BinaryIO], /, **pkl_loads_kwds) -> Any:
+    r"""Load content from PICKLE file.
+
+    Args:
+        file: Filepath file path.
+        \*\*pkl_loads_kwds: Other args passed to `pickle.loads`.
+    """
+    if isinstance(file, (str, Path, PathLike)):
+        file = open(file, "rb")
+        close = True
+    else:
+        close = False
+
+    data = _parse_pickle(file, **pkl_loads_kwds)
+    if close:
+        file.close()
+    return data
+
+
+def loads_pickle(content: bytes, /, **pkl_loads_kwds) -> Any:
+    r"""Load content from raw bytes.
+
+    Args:
+        content: Encoded elements bytes.
+        \*\*pkl_loads_kwds: Other args passed to `pickle.loads`.
+    """
+    with BytesIO(content) as buffer:
+        return _parse_pickle(buffer, **pkl_loads_kwds)
+
+
+@function_alias(load_pickle)
+def read_pickle(*args, **kwargs):
+    """Read pickle."""
+    ...
+
+
+def _parse_pickle(buffer: BinaryIO, **pkl_loads_kwds) -> Any:
+    """Parse pickle."""
+    return pickle.load(buffer, **pkl_loads_kwds)

pythonwrench/time.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import time
+from typing import Callable, Optional
+
+
+class Ticker:
+    def __init__(
+        self,
+        *,
+        get_time_fn: Callable[[], float] = time.perf_counter,
+        prev_tick: Optional[float] = None,
+    ) -> None:
+        """Utility class to show time elapsed since last tick."""
+        if prev_tick is None:
+            prev_tick = get_time_fn()
+
+        super().__init__()
+        self._get_time_fn = get_time_fn
+        self._prev_tick = prev_tick
+
+    def tick(self) -> float:
+        """Set tick time and returns duration since last tick."""
+        now = self._get_time_fn()
+        duration = now - self._prev_tick
+        self._prev_tick = now
+        return duration
+
+    def set_prev_tick(self, prev_tick: Optional[float] = None) -> None:
+        """Set tick time."""
+        if prev_tick is None:
+            prev_tick = self._get_time_fn()
+        self._prev_tick = prev_tick

pythonwrench/typing/__init__.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from typing import TYPE_CHECKING
+
+try:
+    import lazy_loader as lazy  # type: ignore
+except ImportError:
+    lazy = None
+
+
+if TYPE_CHECKING or lazy is None:
+    from .checks import (
+        check_args_types,
+        is_builtin_collection,
+        is_builtin_number,
+        is_builtin_obj,
+        is_builtin_scalar,
+        is_collection_alias,
+        is_dataclass_instance,
+        is_dataclass_type,
+        is_iterable_bool,
+        is_iterable_bytes_or_list,
+        is_iterable_float,
+        is_iterable_int,
+        is_iterable_integral,
+        is_iterable_str,
+        is_namedtuple_instance,
+        is_parameterized,
+        is_sequence_str,
+        is_special_form,
+        is_typed_dict,
+        isinstance_generic,
+    )
+    from .classes import (
+        BuiltinCollection,
+        BuiltinNumber,
+        BuiltinScalar,
+        Dataclass,
+        DataclassInstance,
+        EllipsisType,
+        ListOrTuple,
+        NamedTupleInstance,
+        NoneType,
+        SupportsAdd,
+        SupportsAnd,
+        SupportsBool,
+        SupportsDiv,
+        SupportsGetitem,
+        SupportsGetitem2,
+        SupportsGetitemIterLen,
+        SupportsGetitemIterLen2,
+        SupportsGetitemLen,
+        SupportsGetitemLen2,
+        SupportsIter,
+        SupportsIterLen,
+        SupportsLen,
+        SupportsMatmul,
+        SupportsMul,
+        SupportsOr,
+        T_BuiltinNumber,
+        T_BuiltinScalar,
+    )
+
+else:
+    __getattr__, __dir__, __all__ = lazy.attach(
+        __name__,
+        submodules=[
+            "checks",
+            "classes",
+        ],
+        submod_attrs={
+            "checks": [
+                "check_args_types",
+                "is_builtin_collection",
+                "is_builtin_number",
+                "is_builtin_obj",
+                "is_builtin_scalar",
+                "is_collection_alias",
+                "is_dataclass_instance",
+                "is_dataclass_type",
+                "is_iterable_bool",
+                "is_iterable_bytes_or_list",
+                "is_iterable_float",
+                "is_iterable_int",
+                "is_iterable_integral",
+                "is_iterable_str",
+                "is_namedtuple_instance",
+                "is_parameterized",
+                "is_sequence_str",
+                "is_special_form",
+                "is_typed_dict",
+                "isinstance_generic",
+            ],
+            "classes": [
+                "BuiltinCollection",
+                "BuiltinNumber",
+                "BuiltinScalar",
+                "Dataclass",
+                "DataclassInstance",
+                "EllipsisType",
+                "ListOrTuple",
+                "NamedTupleInstance",
+                "NoneType",
+                "SupportsAdd",
+                "SupportsAnd",
+                "SupportsBool",
+                "SupportsDiv",
+                "SupportsGetitem",
+                "SupportsGetitem2",
+                "SupportsGetitemIterLen",
+                "SupportsGetitemIterLen2",
+                "SupportsGetitemLen",
+                "SupportsGetitemLen2",
+                "SupportsIter",
+                "SupportsIterLen",
+                "SupportsLen",
+                "SupportsMatmul",
+                "SupportsMul",
+                "SupportsOr",
+                "T_BuiltinNumber",
+                "T_BuiltinScalar",
+            ],
+        },
+    )