Extend file stream

.github/workflows/ci.yml

@@ -23,8 +23,8 @@ jobs:
       run: uv sync --all-extras --dev
     - name: Run lint
       run:  |
-        uv run ruff check
-        uv run ruff format
+        uv run ruff check --no-fix
+        uv run ruff format --check
     - name: Run tests
       run: uv run pytest -v --cov=./pyrio --cov-fail-under=90 --cov-report=xml
     - name: Upload coverage to Codecov

README.md

@@ -585,6 +585,42 @@ FileStream("path/to/file.json").concat(in_memory_dict).save(
 )
 ```
 
+--------------------------------------------
+NB: instead of passing file_options as dict you can use provided custom classes for different supported file types
+```python
+FileStream("./tests/resources/plain.txt").map(lambda x: x.strip()).head(2).save(
+    file_path="path/to/file.txt",
+    f_write_options=TextWriteOpts.with_(header="---START---\n", footer="\n---END---"),
+)
+
+# ---START---
+# Lorem ipsum dolor sit amet, consectetur adipisicing elit,
+# sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+# ---END---
+```
+
+```python
+FileStream("./tests/resources/nested.md").save(
+    file_path="path/to/output.yaml",
+    f_open_options=FileOpts.utf8(),
+    f_write_options=YamlWriteOpts.block_style(),
+)
+
+# Email:
+#   primary: jen123@gmail.com
+# Job: null
+# Name: Jennifer Smith
+# Phone: 555-123-4568
+# first:
+#   second:
+#   - 1
+#   - 2
+#   - 3
+#   - 4
+#   still-second:
+#     third: 42
+```
+
 --------------------------------------------
 ### How far can we actually push it?
 ```python

docs/quickstart.md

@@ -566,6 +566,42 @@ FileStream("path/to/file.json").concat(in_memory_dict).save(
 )
 ```
 
+--------------------------------------------
+NB: instead of passing file_options as dict you can use provided custom classes for the different supported file types
+```python
+FileStream("./tests/resources/plain.txt").map(lambda x: x.strip()).head(2).save(
+    file_path="path/to/file.txt",
+    f_write_options=TextWriteOpts.with_(header="---START---\n", footer="\n---END---"),
+)
+
+# ---START---
+# Lorem ipsum dolor sit amet, consectetur adipisicing elit,
+# sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+# ---END---
+```
+
+```python
+FileStream("./tests/resources/nested.md").save(
+    file_path="path/to/output.yaml",
+    f_open_options=FileOpts.utf8(),
+    f_write_options=YamlWriteOpts.block_style(),
+)
+
+# Email:
+#   primary: jen123@gmail.com
+# Job: null
+# Name: Jennifer Smith
+# Phone: 555-123-4568
+# first:
+#   second:
+#   - 1
+#   - 2
+#   - 3
+#   - 4
+#   still-second:
+#     third: 42
+```
+
 --------------------------------------------
 ### How far can we actually push it?
 ```python

pyproject.toml

@@ -12,6 +12,7 @@ license-files = ["LICENSE"]
 
 [project.optional-dependencies]
 fs = [
+    "aldict>=1.1.1",
     "pyyaml>=6.0.2",
     "tomli-w>=1.1.0",
     "xmltodict>=0.14.2",

pyrio/__init__.py

@@ -2,5 +2,32 @@
 from .streams.file_stream import FileStream as FileStream
 from .utils.optional import Optional as Optional
 from .utils.dict_item import DictItem as DictItem
+from .utils.file_options import (
+    FileOpts as FileOpts,
+    CsvReadOpts as CsvReadOpts,
+    CsvWriteOpts as CsvWriteOpts,
+    JsonReadOpts as JsonReadOpts,
+    JsonWriteOpts as JsonWriteOpts,
+    YamlReadOpts as YamlReadOpts,
+    YamlWriteOpts as YamlWriteOpts,
+    XmlReadOpts as XmlReadOpts,
+    XmlWriteOpts as XmlWriteOpts,
+    TextWriteOpts as TextWriteOpts,
+)
 
-__all__ = ["Stream", "FileStream", "Optional", "DictItem"]
+__all__ = [
+    "Stream",
+    "FileStream",
+    "Optional",
+    "DictItem",
+    "FileOpts",
+    "CsvReadOpts",
+    "CsvWriteOpts",
+    "JsonReadOpts",
+    "JsonWriteOpts",
+    "YamlReadOpts",
+    "YamlWriteOpts",
+    "XmlReadOpts",
+    "XmlWriteOpts",
+    "TextWriteOpts",
+]

pyrio/decorators/__init__.py

@@ -1,3 +1,2 @@
-from .handler import pre_call as pre_call
-from .handler import handle_consumed as handle_consumed
+from .handler import pre_call as pre_call, handle_consumed as handle_consumed
 from .mapper import map_dict_items as map_dict_items

pyrio/exceptions/__init__.py

@@ -1,4 +1,6 @@
-from .exception import IllegalStateError as IllegalStateError
-from .exception import NoneTypeError as NoneTypeError
-from .exception import NoSuchElementError as NoSuchElementError
-from .exception import UnsupportedTypeError as UnsupportedTypeError
+from .exception import (
+    IllegalStateError as IllegalStateError,
+    NoneTypeError as NoneTypeError,
+    NoSuchElementError as NoSuchElementError,
+    UnsupportedTypeError as UnsupportedTypeError,
+)

pyrio/streams/file_stream.py

@@ -3,60 +3,78 @@
 from contextlib import contextmanager
 from pathlib import Path
 
-from pyrio.utils import DictItem
+from aldict import AliasDict
+
+from pyrio.utils import DictItem, Mappable
 from pyrio.streams import BaseStream, Stream
 from pyrio.exceptions import NoneTypeError
 
 TEMP_PATH = "{file_path}.tmp"
-DSV_TYPES = {".csv", ".tsv"}
-MAPPING_READ_CONFIG = {
-    ".toml": {
-        "import_mod": "tomllib",
-        "callable": "load",
-        "read_mode": "rb",
-    },
-    ".json": {
-        "import_mod": "json",
-        "callable": "load",
-        "read_mode": "r",
-    },
-    ".yaml": {
-        "import_mod": "yaml",
-        "callable": "safe_load",
-        "read_mode": "r",
+
+DSV_CONFIG = {
+    ".csv": {
+        "delimiter": ",",
     },
-    ".xml": {
-        "import_mod": "xmltodict",
-        "callable": "parse",
-        "read_mode": "rb",
+    ".tsv": {
+        "delimiter": "\t",
     },
 }
-MAPPING_WRITE_CONFIG = {
-    ".toml": {
-        "import_mod": "tomli_w",
-        "callable": "dump",
-        "write_mode": "wb",
-        "default_null_handler": lambda x: DictItem(x.key, "N/A") if x.value is None else x,
-    },
-    ".json": {
-        "import_mod": "json",
-        "callable": "dump",
-        "write_mode": "w",
-        "default_null_handler": None,
-    },
-    ".yaml": {
-        "import_mod": "yaml",
-        "callable": "dump",
-        "write_mode": "w",
-        "default_null_handler": None,
+
+MAPPING_READ_CONFIG = AliasDict(
+    {
+        ".toml": {
+            "import_mod": "tomllib",
+            "callable": "load",
+            "read_mode": "rb",
+        },
+        ".json": {
+            "import_mod": "json",
+            "callable": "load",
+            "read_mode": "r",
+        },
+        ".yaml": {
+            "import_mod": "yaml",
+            "callable": "safe_load",
+            "read_mode": "r",
+        },
+        ".xml": {
+            "import_mod": "xmltodict",
+            "callable": "parse",
+            "read_mode": "rb",
+        },
     },
-    ".xml": {
-        "import_mod": "xmltodict",
-        "callable": "unparse",
-        "write_mode": "w",
-        "default_null_handler": None,
+    aliases={".yaml": ".yml"},
+)
+
+MAPPING_WRITE_CONFIG = AliasDict(
+    {
+        ".toml": {
+            "import_mod": "tomli_w",
+            "callable": "dump",
+            "write_mode": "wb",
+            "default_null_handler": lambda x: DictItem(x.key, "N/A") if x.value is None else x,
+        },
+        ".json": {
+            "import_mod": "json",
+            "callable": "dump",
+            "write_mode": "w",
+            "default_null_handler": None,
+        },
+        ".yaml": {
+            "import_mod": "yaml",
+            "callable": "dump",
+            "write_mode": "w",
+            "default_null_handler": None,
+        },
+        ".xml": {
+            "import_mod": "xmltodict",
+            "callable": "unparse",
+            "write_mode": "w",
+            "default_null_handler": None,
+        },
     },
-}
+    aliases={".yaml": ".yml"},
+)
 
 
 class FileStream(BaseStream):
@@ -98,14 +116,12 @@ def process(cls, file_path, *, f_open_options=None, f_read_options=None, **kwarg
     def _read_file(cls, file_path, f_open_options=None, f_read_options=None, **kwargs):
         path = cls._get_file_path(file_path)
 
-        if f_open_options is None:
-            f_open_options = {}
-        if f_read_options is None:
-            f_read_options = {}
+        f_open_options = cls._normalize_options(f_open_options)
+        f_read_options = cls._normalize_options(f_read_options)
 
-        if (suffix := path.suffix) in DSV_TYPES:
+        if (suffix := path.suffix) in DSV_CONFIG:
             return cls._read_dsv(path, f_open_options, f_read_options)
-        elif suffix in MAPPING_READ_CONFIG.keys():
+        elif suffix in MAPPING_READ_CONFIG:
             return cls._read_mapping(path, f_open_options, f_read_options, **kwargs)
         else:
             return cls._read_plain(path, f_open_options)
@@ -117,7 +133,7 @@ def _read_dsv(path, f_open_options, f_read_options):
         FileStream._prepare_io_options(
             [
                 (f_open_options, "newline", ""),
-                (f_read_options, "delimiter", "\t" if path.suffix == ".tsv" else ","),
+                (f_read_options, "delimiter", DSV_CONFIG[path.suffix]["delimiter"]),
             ]
         )
         file_handler = open(path, **f_open_options)
@@ -156,14 +172,12 @@ def save(
         """Writes Stream to a new file (or updates an existing one) with advanced 'writing' options passed by the user"""
         path, tmp_path = self._prepare_file_paths(file_path)
 
-        if f_open_options is None:
-            f_open_options = {}
-        if f_write_options is None:
-            f_write_options = {}
+        f_open_options = self._normalize_options(f_open_options)
+        f_write_options = self._normalize_options(f_write_options)
 
-        if (suffix := path.suffix) in DSV_TYPES:
+        if (suffix := path.suffix) in DSV_CONFIG:
             return self._write_dsv(path, tmp_path, f_open_options, f_write_options, null_handler)
-        elif suffix in MAPPING_READ_CONFIG.keys():
+        elif suffix in MAPPING_WRITE_CONFIG:
             return self._write_mapping(
                 path, tmp_path, f_open_options, f_write_options, null_handler, **kwargs
             )
@@ -180,11 +194,11 @@ def _write_dsv(self, path, tmp_path, f_open_options, f_write_options, null_handl
         self._prepare_io_options(
             [
                 (f_open_options, "mode", "w"),
-                (f_write_options, "delimiter", "\t" if path.suffix == ".tsv" else ","),
+                (f_write_options, "delimiter", DSV_CONFIG[path.suffix]["delimiter"]),
                 (f_write_options, "fieldnames", output[0].keys() if output else ()),
             ]
         )
-        with self._atomic_write(path, tmp_path, f_open_options) as f:
+        with self._atomic_write(path, tmp_path, f_open_options) as f:  # noqa
             writer = csv.DictWriter(f, **f_write_options)
             writer.writeheader()
             writer.writerows(output)
@@ -202,11 +216,11 @@ def _write_mapping(
         if path.suffix == ".xml":
             root = kwargs.get("xml_root", "root")
             output = {root: output}
-            io_opts_setting.append((f_write_options, "pretty", True))
+            io_opts_setting.append((f_write_options, "pretty", True))  # noqa
         self._prepare_io_options(io_opts_setting)
 
         dump = getattr(importlib.import_module(config["import_mod"]), config["callable"])
-        with self._atomic_write(path, tmp_path, f_open_options) as f:
+        with self._atomic_write(path, tmp_path, f_open_options) as f:  # noqa
             dump(output, f, **f_write_options)
 
     def _write_plain(self, path, tmp_path, f_open_options, f_write_options):
@@ -218,10 +232,19 @@ def _write_plain(self, path, tmp_path, f_open_options, f_write_options):
         if header or footer:
             output = f"{header}{output}{footer}"
 
-        with self._atomic_write(path, tmp_path, f_open_options) as f:
+        with self._atomic_write(path, tmp_path, f_open_options) as f:  # noqa
             f.writelines(output)
 
     # ### helpers ###
+    @staticmethod
+    def _normalize_options(options):
+        """Converts option objects to dicts if needed, returns empty dict for None."""
+        if options is None:
+            return {}
+        if isinstance(options, Mappable):
+            return options.to_dict()
+        return options
+
     @staticmethod
     def _get_file_path(file_path, read_mode=True):
         path = Path(file_path)

pyrio/utils/__init__.py

@@ -1,2 +1,15 @@
 from .dict_item import DictItem as DictItem
 from .optional import Optional as Optional
+from .file_options import (
+    Mappable as Mappable,
+    FileOpts as FileOpts,
+    CsvReadOpts as CsvReadOpts,
+    CsvWriteOpts as CsvWriteOpts,
+    JsonReadOpts as JsonReadOpts,
+    JsonWriteOpts as JsonWriteOpts,
+    YamlReadOpts as YamlReadOpts,
+    YamlWriteOpts as YamlWriteOpts,
+    XmlReadOpts as XmlReadOpts,
+    XmlWriteOpts as XmlWriteOpts,
+    TextWriteOpts as TextWriteOpts,
+)