flat-file-renderers 0.1.0__py3-none-any.whl

flat_file_renderers/__init__.py

@@ -0,0 +1,32 @@
+"""flat_file_renderers - render tabular/nested datasets into xlsx, csv, tsv, json, html or
+parquet files, zipped.
+
+Only the dependency-free renderers (csv, tsv, json, html) are exported here, so importing this
+package never requires openpyxl or pyarrow. XlsxRenderer and ParquetRenderer are available from
+their own submodules and require the matching optional extra:
+
+    pip install flat-file-renderers[xlsx]     # from flat_file_renderers.xlsx import XlsxRenderer
+    pip install flat-file-renderers[parquet]  # from flat_file_renderers.parquet import ParquetRenderer
+    pip install flat-file-renderers[all]      # both
+"""
+
+from flat_file_renderers.base import BaseRenderer, ZipFileEntry
+from flat_file_renderers.flat_dict_list_helper import FlatDictListHelper
+from flat_file_renderers.html import HtmlRenderer
+from flat_file_renderers.json import JsonRenderer
+from flat_file_renderers.separated_value import CsvRenderer, FlatDelimitedRenderer, TsvRenderer
+from flat_file_renderers.text import replace_crlf
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BaseRenderer",
+    "ZipFileEntry",
+    "FlatDictListHelper",
+    "replace_crlf",
+    "CsvRenderer",
+    "TsvRenderer",
+    "FlatDelimitedRenderer",
+    "JsonRenderer",
+    "HtmlRenderer",
+]

flat_file_renderers/base.py

@@ -0,0 +1,114 @@
+import logging
+from abc import abstractmethod
+from datetime import datetime
+from io import BytesIO
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from zipfile import ZIP_DEFLATED, ZipFile
+
+logger = logging.getLogger(__name__)
+
+
+class ZipFileEntry:
+    def __init__(self, zipfilealias: str, osfilepath: Path):
+        self.zipfilealias = zipfilealias
+        self.osfilepath = osfilepath
+
+
+class BaseRenderer:
+    """
+    Base class for dataset renderers.
+
+    Defines the interface and basic structure for concrete renderers (CSV, Excel, Parquet, etc).
+    Subclasses must implement the abstract `render` method to provide the file-generation logic.
+
+    Attributes:
+        context (dict): Context dict used to render the file. May hold input data, a validated
+            form, the requesting user, etc.
+
+    Example:
+        class CsvRenderer(BaseRenderer):
+            def render(self, *args, **kwargs) -> BytesIO:
+                ...
+
+        renderer = CsvRenderer({'columns': ["Name", "Age"], 'rows': [{"Name": "Alice", "Age": "30"}]})
+        csv_file = renderer.render()
+        with open("data.csv", "wb") as f:
+            f.write(csv_file.getvalue())
+    """
+
+    def __init__(self, context: dict[str, any]):
+        """
+        Initializes the base renderer with the given context.
+
+        Args:
+            context (dict): Context dict holding whatever the renderer needs to produce the file.
+        """
+        self.context = context
+
+    @property
+    def default_filename(self) -> str:
+        """
+        Builds a default filename from the current date/time and the renderer's extension.
+
+        Returns:
+            str: Suggested filename.
+        """
+        return f"dataset_{datetime.now().strftime('%Y-%m-%d-%H-%M-%S')}.{self.extension}"
+
+    def write_zipfile(self, entries: list["ZipFileEntry"]) -> Path:
+        """
+        Compresses one or more files into a temporary ZIP file.
+
+        Args:
+            entries (list[ZipFileEntry]): Entries to compress.
+
+        Returns:
+            Path: Path to the generated ZIP file.
+
+        Examples:
+        ```python
+        zip_path = renderer.write_zipfile([ZipFileEntry("data.csv", Path("/path/to/data.csv"))])
+
+        with open(zip_path, "rb") as f:
+            zip_content = f.read()
+
+        from zipfile import ZipFile
+        with ZipFile(zip_path, 'r') as zipf:
+            print(zipf.namelist())
+        # ['data.csv']
+        ```
+        """
+        with NamedTemporaryFile(delete=False, suffix=".zip") as zipfilehandler:
+            logger.info(
+                "Creating temporary zip file to compress: %s",
+                [entry.zipfilealias for entry in entries],
+            )
+            with ZipFile(zipfilehandler, mode="w", compression=ZIP_DEFLATED) as archive:
+                for entry in entries:
+                    logger.info("Adding file %s to zip as %s", entry.osfilepath, entry.zipfilealias)
+                    archive.write(entry.osfilepath, arcname=entry.zipfilealias)
+            logger.info("Zip file created successfully: %s", zipfilehandler.name)
+            return Path(zipfilehandler.name)
+
+    @property
+    def extension(self) -> str:
+        """
+        Returns the default file extension produced by this renderer.
+
+        Returns:
+            str: File extension (e.g. 'csv', 'xlsx').
+        """
+        return getattr(self, "_extension", "dat")
+
+    @abstractmethod
+    def render(self, *args, **kwargs) -> BytesIO:
+        """
+        Abstract method that renders the data and produces the file.
+
+        Subclasses must implement this to provide the format-specific generation logic.
+
+        Returns:
+            BytesIO: In-memory generated file.
+        """
+        ...

flat_file_renderers/flat_dict_list_helper.py

@@ -0,0 +1,205 @@
+from typing import Any
+
+
+def _as_plain_dict(row: Any) -> Any:
+    """Returns `row` as a plain dict when it looks like a model/record instance.
+
+    Duck-typed on purpose: rather than importing Django (or any other ORM) to `isinstance`-check
+    for a `Model`, any non-dict object exposing `__dict__` (Django models, dataclasses without
+    `__slots__`, plain objects, etc.) is treated as a record and flattened via its `__dict__`.
+    Dicts and anything without `__dict__` (namedtuples, plain values) pass through unchanged.
+    """
+    if not isinstance(row, dict) and hasattr(row, "__dict__"):
+        return row.__dict__
+    return row
+
+
+class FlatDictListHelper:
+    """
+    Helper for renderers that deal with lists of plain dicts (or dict-like records), without
+    deeply nested structures.
+
+    Provides methods to expand lists of dicts into flat columns and to normalize keys, so that
+    renderers can handle tabular data consistently and without naming collisions. Particularly
+    useful for renderers like CSV/TSV, which need to turn complex data into simple tabular rows.
+    """
+
+    @staticmethod
+    def extract_rows_and_columns(context: dict[str, Any]) -> tuple[list[Any], list[str]]:
+        """
+        Extracts the rows and columns of a dataset present in the rendering context.
+
+        Accepts a dataset shaped as a dict (with 'rows'/'cols'), a list, or any other iterable
+        (e.g. a Django QuerySet or generator) - duck-typed via `__iter__`, no ORM import needed.
+
+        Args:
+            context (dict): Context containing the 'dataset' key.
+
+        Returns:
+            tuple[list, list]: Tuple of (rows, column names - if available).
+
+        Raises:
+            ValueError: If the context has no 'dataset' key, or its type isn't supported.
+        """
+        if "dataset" not in context:
+            raise ValueError("context must contain a 'dataset' key")
+
+        dataset = context.get("dataset", None)
+
+        if isinstance(dataset, dict):
+            rows: list[Any] = dataset.get("rows", [])
+        elif isinstance(dataset, (list, tuple)):
+            rows = list(dataset)
+        elif dataset is not None and not isinstance(dataset, (str, bytes)) and hasattr(dataset, "__iter__"):
+            rows = list(dataset)
+        else:
+            raise ValueError("dataset must be a QuerySet-like iterable, dict, or list")
+
+        cols: list[str] = dataset.get("cols", []) if isinstance(dataset, dict) else []
+        return rows, cols
+
+    @staticmethod
+    def deep_flatten(row: dict, parent_key: str = "") -> dict:
+        """
+        Recursively expands nested dicts and lists of dicts into a flat dict, using dot notation
+        for nested keys.
+
+        Args:
+            row (dict): Data row, possibly containing plain values, lists of dicts, or nested dicts.
+            parent_key (str): Key prefix (used during recursion).
+
+        Returns:
+            dict: Flat dict with all keys expanded.
+
+        Example:
+            deep_flatten({"name": "Alice", "contacts": [{"phone": "1234"}, {"phone": "5678"}]})
+            -> {"name": "Alice", "contacts.1.phone": "1234", "contacts.2.phone": "5678"}
+        """
+        items = {}
+        flat = FlatDictListHelper.expand_row(row)
+        for k, v in flat.items():
+            new_key = f"{parent_key}.{k}" if parent_key else str(k)
+            if isinstance(v, dict):
+                items.update(FlatDictListHelper.deep_flatten(v, new_key))
+            else:
+                items[new_key] = v
+        return items
+
+    @staticmethod
+    def extract_flat_columns(rows: list) -> list[str]:
+        """
+        Given a list of dicts (or record objects), returns the list of flat, normalized columns,
+        including columns expanded from lists of dicts.
+
+        Args:
+            rows (list): List of dicts or record/model objects representing the data rows.
+
+        Returns:
+            list[str]: List of column names, including columns expanded from lists of dicts,
+                with normalized keys.
+
+        Example:
+            rows = [
+                {"name": "Alice", "contacts": [{"phone": "1234"}, {"phone": "5678"}]},
+                {"name": "Bob", "addresses": [{"street": "Street A"}, {"street": "Street B"}]}
+            ]
+            # Output: ["name", "contacts.1.phone", "contacts.2.phone", "addresses.1.street", "addresses.2.street"]
+        """
+        list_dict_max = {}  # key: max_len
+        list_dict_keys = {}  # key: set(subkeys)
+        for row in rows:
+            row = _as_plain_dict(row)
+            for key, value in row.items():
+                if isinstance(value, list) and value and all(isinstance(x, dict) for x in value):
+                    list_dict_max[key] = max(list_dict_max.get(key, 0), len(value))
+                    subkeys = set()
+                    for item in value:
+                        subkeys.update(item.keys())
+                    if key not in list_dict_keys:
+                        list_dict_keys[key] = set()
+                    list_dict_keys[key].update(subkeys)
+
+        cols = set()
+        for row in rows:
+            row = _as_plain_dict(row)
+            flat = FlatDictListHelper.expand_row(row)
+            for key in flat.keys():
+                if key not in list_dict_max:
+                    cols.add(FlatDictListHelper.normalize_key(key))
+        for key, max_len in list_dict_max.items():
+            for idx in range(1, max_len + 1):
+                for subkey in list_dict_keys[key]:
+                    cols.add(FlatDictListHelper.normalize_key(f"{key}.{idx}.{subkey}"))
+        return sorted(cols)
+
+    @staticmethod
+    def expand_row(row: dict) -> dict:
+        """
+        Expands lists of dicts into flat columns.
+
+        Discovers all columns, including expanded lists of dicts, and normalizes keys to avoid
+        collisions. Lists of dicts are expanded into dot+index-notation columns, and keys are
+        normalized by replacing '__' with '.'.
+
+        Args:
+            row (dict): Data row, holding plain values or lists of dicts.
+
+        Returns:
+            dict: Flat dict where lists of dicts have been expanded into dot+index-notation columns.
+
+        Example:
+            expand_row({"name": "Alice", "contacts": [{"phone": "1234"}, {"phone": "5678"}]})
+            -> {"name": "Alice", "contacts.1.phone": "1234", "contacts.2.phone": "5678"}
+        """
+        flat = {}
+        for key, value in row.items():
+            if isinstance(value, list) and value and all(isinstance(x, dict) for x in value):
+                for idx, item in enumerate(value, 1):
+                    for subkey, subval in item.items():
+                        flat[f"{key}.{idx}.{subkey}"] = subval
+            else:
+                flat[key] = value
+        return flat
+
+    @staticmethod
+    def normalize_key(key: str) -> str:
+        """
+        Replaces '__' with '.' in keys, to avoid clashing with the list-of-dicts dot notation.
+
+        Args:
+            key (str): Key to normalize.
+
+        Returns:
+            str: Normalized key, with '__' replaced by '.'.
+
+        Example:
+            normalize_key("address__street") -> "address.street"
+            normalize_key("person__contacts__1__phone") -> "person.contacts.1.phone"
+        """
+        return key.replace("__", ".")
+
+    @staticmethod
+    def flatten_dataset(context: dict[str, Any]) -> tuple[list[dict], list[str]]:
+        """
+        Returns a flat version of the context's dataset, with all rows and columns expanded and
+        normalized.
+
+        Args:
+            context (dict): Context containing the 'dataset' key.
+
+        Returns:
+            tuple[list[dict], list[str]]: List of flat rows and list of column names.
+        """
+        flattened_rows = []
+        all_keys = set()
+        rows, _ = FlatDictListHelper.extract_rows_and_columns(context)
+        for row in rows:
+            row = _as_plain_dict(row)
+            flat = FlatDictListHelper.deep_flatten(row)
+            normalized_flat = {FlatDictListHelper.normalize_key(k): v for k, v in flat.items()}
+            flattened_rows.append(normalized_flat)
+            all_keys.update(normalized_flat.keys())
+
+        cols = list(all_keys)
+        cols.sort()
+        return flattened_rows, cols

flat_file_renderers/html.py

@@ -0,0 +1,88 @@
+import logging
+from html import escape
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+
+from flat_file_renderers.base import BaseRenderer, ZipFileEntry
+from flat_file_renderers.flat_dict_list_helper import FlatDictListHelper
+from flat_file_renderers.text import replace_crlf
+
+logger = logging.getLogger(__name__)
+
+
+class HtmlRenderer(BaseRenderer):
+    """
+    Renders data as HTML (an HTML table).
+    """
+
+    _extension = "html"
+
+    def render(self, context: dict[str, any], *args, **kwargs) -> Path:
+        """Renders the data as HTML and writes it into a temporary zip file on disk.
+
+        Returns:
+            Path: Path to the compressed (zip) file containing the .html file(s).
+        """
+        if "dataset" not in context:
+            raise ValueError("context must contain a 'dataset' key")
+
+        dataset = context.get("dataset")
+
+        def dump_html_file(title: str, sub_dataset: any) -> Path:
+            html_parts = [
+                "<!DOCTYPE html>",
+                "<html lang='en'>",
+                "<head>",
+                "  <meta charset='utf-8'>",
+                f"  <title>{escape(str(title or 'Report'))}</title>",
+                "  <style>",
+                "    body { font-family: Arial, sans-serif; margin: 20px; color: #333; }",
+                "    h2 { color: #0056b3; border-bottom: 2px solid #0056b3; padding-bottom: 5px; }",
+                "    table { border-collapse: collapse; width: 100%; margin-bottom: 30px; font-size: 14px; }",
+                "    th, td { border: 1px solid #ddd; padding: 8px; text-align: left; }",
+                "    th { background-color: #f2f2f2; font-weight: bold; }",
+                "    tr:nth-child(even) { background-color: #f9f9f9; }",
+                "  </style>",
+                "</head>",
+                "<body>",
+            ]
+            if title:
+                html_parts.append(f"<h2>{escape(str(title))}</h2>")
+
+            rows, cols = FlatDictListHelper.flatten_dataset({"dataset": sub_dataset})
+            html_parts.append("<table>")
+            html_parts.append("  <thead><tr>")
+            for col in cols:
+                html_parts.append(f"    <th>{escape(str(col))}</th>")
+            html_parts.append("  </tr></thead>")
+            html_parts.append("  <tbody>")
+            for row in rows:
+                # `rows` always comes from FlatDictListHelper.flatten_dataset(), which always
+                # produces dicts - so every row here is a dict.
+                html_parts.append("    <tr>")
+                for col in cols:
+                    val = row.get(col, "")
+                    val_str = replace_crlf(str(val)) if val is not None else ""
+                    html_parts.append(f"      <td>{escape(val_str)}</td>")
+                html_parts.append("    </tr>")
+            html_parts.append("  </tbody>")
+            html_parts.append("</table>")
+            html_parts.append("</body>")
+            html_parts.append("</html>")
+
+            content = "\n".join(html_parts)
+            with NamedTemporaryFile(delete=False, mode="w", encoding="utf-8", suffix=".html") as tmp:
+                tmp.write(content)
+                return Path(tmp.name)
+
+        if isinstance(dataset, dict) and "rows" not in dataset:
+            entries = []
+            for table_name, table_data in dataset.items():
+                slug_name = str(table_name).lower().replace(" ", "_").replace("í", "i").replace("á", "a")
+                alias = f"{slug_name}.html"
+                tmp_path = dump_html_file(table_name, table_data)
+                entries.append(ZipFileEntry(zipfilealias=alias, osfilepath=tmp_path))
+            return self.write_zipfile(entries)
+        else:
+            tmp_path = dump_html_file("Report", dataset)
+            return self.write_zipfile([ZipFileEntry(zipfilealias=self.default_filename, osfilepath=tmp_path)])

flat_file_renderers/json.py

@@ -0,0 +1,75 @@
+import json
+import logging
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+
+from flat_file_renderers.base import BaseRenderer, ZipFileEntry
+
+logger = logging.getLogger(__name__)
+
+
+def _serialize_item(item):
+    """Duck-typed record -> plain dict/value conversion.
+
+    Recognizes Django-style models (an object exposing `_meta.concrete_fields`) without
+    importing Django, so the encoder works the same whether or not Django is installed. Any
+    other non-dict object exposing `__dict__` (dataclasses, plain objects) is serialized via
+    its instance attributes. Everything else (dicts, plain values) passes through unchanged -
+    including values `json.dump`'s `default=str` fallback will stringify on its own
+    (date/datetime/Decimal/UUID/etc. all have a sensible `__str__`).
+    """
+    meta = getattr(item, "_meta", None)
+    concrete_fields = getattr(meta, "concrete_fields", None)
+    if concrete_fields is not None:
+        return {field.name: getattr(item, field.name) for field in concrete_fields}
+    if not isinstance(item, dict) and hasattr(item, "__dict__"):
+        return dict(vars(item))
+    return item
+
+
+class JsonRenderer(BaseRenderer):
+    """
+    Renders data as JSON.
+    """
+
+    _extension = "json"
+
+    def render(self, context: dict[str, any], *args, **kwargs) -> Path:
+        """Renders the data as JSON and writes it into a temporary zip file on disk.
+
+        Returns:
+            Path: Path to the compressed (zip) file containing the .json file(s).
+        """
+        if "dataset" not in context:
+            raise ValueError("context must contain a 'dataset' key")
+
+        dataset = context.get("dataset")
+
+        def dump_json_file(data) -> Path:
+            if isinstance(data, list):
+                serial_data = [_serialize_item(item) for item in data]
+            elif hasattr(data, "model") and hasattr(data, "__iter__"):
+                serial_data = [_serialize_item(item) for item in data]
+            elif isinstance(data, dict):
+                serial_data = {
+                    k: [_serialize_item(i) for i in v] if isinstance(v, list) else _serialize_item(v)
+                    for k, v in data.items()
+                }
+            else:
+                serial_data = _serialize_item(data)
+
+            with NamedTemporaryFile(delete=False, mode="w", encoding="utf-8", suffix=".json") as tmp:
+                json.dump(serial_data, tmp, ensure_ascii=False, default=str, indent=2)
+                return Path(tmp.name)
+
+        if isinstance(dataset, dict) and "rows" not in dataset:
+            entries = []
+            for table_name, table_data in dataset.items():
+                slug_name = str(table_name).lower().replace(" ", "_").replace("í", "i").replace("á", "a")
+                alias = f"{slug_name}.json"
+                tmp_path = dump_json_file(table_data)
+                entries.append(ZipFileEntry(zipfilealias=alias, osfilepath=tmp_path))
+            return self.write_zipfile(entries)
+        else:
+            tmp_path = dump_json_file(dataset)
+            return self.write_zipfile([ZipFileEntry(zipfilealias=self.default_filename, osfilepath=tmp_path)])

flat_file_renderers/parquet.py

@@ -0,0 +1,68 @@
+import logging
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+
+from flat_file_renderers.base import BaseRenderer, ZipFileEntry
+from flat_file_renderers.flat_dict_list_helper import FlatDictListHelper
+
+logger = logging.getLogger(__name__)
+
+
+class ParquetRenderer(BaseRenderer):
+    """
+    Renders data as Apache Parquet (.parquet). Requires the ``parquet`` extra (pyarrow):
+    ``pip install flat-file-renderers[parquet]``.
+    """
+
+    _extension = "parquet"
+
+    def render(self, context: dict[str, any], *args, **kwargs) -> Path:
+        """Renders the data as Apache Parquet and writes it into a temporary zip file on disk.
+
+        Returns:
+            Path: Path to the compressed (zip) file containing the .parquet file(s).
+        """
+        if "dataset" not in context:
+            raise ValueError("context must contain a 'dataset' key")
+
+        dataset = context.get("dataset")
+
+        def dump_parquet_file(sub_dataset: any) -> Path:
+            rows, cols = FlatDictListHelper.flatten_dataset({"dataset": sub_dataset})
+
+            # `rows` always comes from FlatDictListHelper.flatten_dataset(), which always
+            # produces dicts - so every row here is a dict.
+            cleaned_rows = []
+            for row in rows:
+                cleaned_row = {}
+                for col in cols:
+                    val = row.get(col)
+                    if isinstance(val, (list, dict)):
+                        cleaned_row[col] = str(val)
+                    else:
+                        cleaned_row[col] = val
+                cleaned_rows.append(cleaned_row)
+
+            # `pa.Table.from_batches([])` requires an explicit (possibly empty) schema - without
+            # one it raises "Must pass schema, or at least one RecordBatch".
+            table = (
+                pa.Table.from_pylist(cleaned_rows) if cleaned_rows else pa.Table.from_batches([], schema=pa.schema([]))
+            )
+            with NamedTemporaryFile(delete=False, suffix=".parquet") as tmp:
+                pq.write_table(table, tmp.name)
+                return Path(tmp.name)
+
+        if isinstance(dataset, dict) and "rows" not in dataset:
+            entries = []
+            for table_name, table_data in dataset.items():
+                slug_name = str(table_name).lower().replace(" ", "_").replace("í", "i").replace("á", "a")
+                alias = f"{slug_name}.parquet"
+                tmp_path = dump_parquet_file(table_data)
+                entries.append(ZipFileEntry(zipfilealias=alias, osfilepath=tmp_path))
+            return self.write_zipfile(entries)
+        else:
+            tmp_path = dump_parquet_file(dataset)
+            return self.write_zipfile([ZipFileEntry(zipfilealias=self.default_filename, osfilepath=tmp_path)])

flat_file_renderers/separated_value.py

@@ -0,0 +1,112 @@
+import logging
+from csv import DictWriter
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+
+from flat_file_renderers.base import BaseRenderer, ZipFileEntry
+from flat_file_renderers.flat_dict_list_helper import FlatDictListHelper
+from flat_file_renderers.text import replace_crlf
+
+logger = logging.getLogger(__name__)
+
+
+class FlatDelimitedRenderer(BaseRenderer):
+    """
+    Renders data as delimiter-separated values (CSV or TSV).
+
+    This base class exports tabular data into delimiter-separated files, such as CSV (comma)
+    or TSV (tab).
+
+    The context must contain the 'dataset' key, which can be:
+        - A QuerySet-like iterable: columns are inferred from the record fields.
+        - A dict: must contain 'rows' (list of dicts) and 'cols' (list of column names).
+        - A list: list of dicts, columns inferred from the first item's keys.
+
+    Usage examples:
+        renderer = CsvRenderer({'dataset': {'cols': ["Name", "Age"], 'rows': [{"Name": "Alice", "Age": "30"}]}})
+        csv_file = renderer.render({'dataset': ...})
+        with open("data.csv", "wb") as f:
+            f.write(csv_file.read_bytes())
+
+        renderer = CsvRenderer({})
+        csv_file = renderer.render({'dataset': [{"Name": "Alice", "Age": "30"}, {"Name": "Bob", "Age": "25"}]})
+    """
+
+    @property
+    def delimiter(self):
+        """
+        Returns the delimiter used to separate values.
+
+        Returns:
+            str: Delimiter (comma by default).
+        """
+        return getattr(self, "_delimiter", ",")
+
+    def render(self, context: dict[str, any], *args, **kwargs) -> Path:
+        """
+        Renders the data as delimiter-separated values and writes it into a temporary zip file
+        on disk.
+
+        Args:
+            context (dict): Dict holding the data to render. Must contain the 'dataset' key.
+            *args: Extra positional arguments.
+            **kwargs: Extra keyword arguments.
+
+        Returns:
+            Path: Path to the compressed (zip) file containing the delimited file(s).
+        """
+        dataset = context.get("dataset")
+        entries = []
+
+        if isinstance(dataset, dict) and "rows" not in dataset:
+            for table_name, table_data in dataset.items():
+                slug_name = str(table_name).lower().replace(" ", "_").replace("í", "i").replace("á", "a")
+                alias = f"{slug_name}.{self.extension}"
+                tmp = NamedTemporaryFile(delete=False, mode="w", encoding="utf-8", newline="")
+                self.__write_dsv({"dataset": table_data}, tmp)
+                tmp.close()
+                entries.append(ZipFileEntry(zipfilealias=alias, osfilepath=Path(tmp.name)))
+            return self.write_zipfile(entries)
+        else:
+            with NamedTemporaryFile(delete=False, mode="w", encoding="utf-8", newline="") as csvfile:
+                logger.info("Rendering file %s with delimiter '%s'", self.default_filename, self.delimiter)
+                self.__write_dsv(context, csvfile)
+                logger.info("File %s rendered successfully.", self.default_filename)
+                csvfile_path = Path(csvfile.name)
+            # write_zipfile needs to read the file from disk: calling it while still inside the
+            # "with" block would zip the file before its write buffer was flushed/closed,
+            # producing an empty csv/tsv inside the zip.
+            return self.write_zipfile([ZipFileEntry(zipfilealias=self.default_filename, osfilepath=csvfile_path)])
+
+    def __write_dsv(self, context: dict[str, any], csvfile: NamedTemporaryFile):
+        rows, cols = FlatDictListHelper.flatten_dataset(context)
+        writer = DictWriter(csvfile, fieldnames=cols, delimiter=self.delimiter)
+        writer.writeheader()
+        line_num = 1
+        for row in rows:
+            if line_num % 500 == 1 and line_num > 1:
+                logger.info("Progress: %d rows written to %s", line_num - 1, self.default_filename)
+            writer.writerow({col: replace_crlf(row.get(col) or "") for col in cols})
+            line_num += 1
+
+
+class CsvRenderer(FlatDelimitedRenderer):
+    """
+    Renders data as CSV (Comma-Separated Values).
+
+    Uses comma as delimiter and '.csv' extension.
+    """
+
+    _delimiter = ","
+    _extension = "csv"
+
+
+class TsvRenderer(FlatDelimitedRenderer):
+    """
+    Renders data as TSV (Tab-Separated Values).
+
+    Uses tab as delimiter and '.tsv' extension.
+    """
+
+    _delimiter = "\t"
+    _extension = "tsv"

flat_file_renderers/text.py

@@ -0,0 +1,7 @@
+def replace_crlf(val: str) -> str:
+    """Replaces embedded newline/carriage-return characters with a visible ``\\n``/``\\r`` marker.
+
+    Useful before writing a value into a single tabular cell (CSV/TSV/XLSX/HTML), where a raw
+    embedded line break would otherwise corrupt the row layout.
+    """
+    return val.replace("\n", r"\\n").replace("\r", r"\\r") if isinstance(val, str) else val

flat_file_renderers/xlsx.py

@@ -0,0 +1,64 @@
+import logging
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+
+from openpyxl import Workbook
+
+from flat_file_renderers.base import BaseRenderer, ZipFileEntry
+from flat_file_renderers.flat_dict_list_helper import FlatDictListHelper
+from flat_file_renderers.text import replace_crlf
+
+logger = logging.getLogger(__name__)
+
+
+class XlsxRenderer(BaseRenderer):
+    """
+    Renders data as XLSX (Excel). Requires the ``xlsx`` extra (openpyxl):
+    ``pip install flat-file-renderers[xlsx]``.
+    """
+
+    _extension = "xlsx"
+
+    def render(self, context: dict[str, any], *args, **kwargs) -> Path:
+        """Renders the data as XLSX and writes it into a temporary zip file on disk.
+
+        Returns:
+            Path: Path to the compressed (zip) file containing the .xlsx file.
+        """
+        dataset = context.get("dataset")
+        wb = Workbook()
+
+        if isinstance(dataset, dict) and "rows" not in dataset:
+            first = True
+            for sheet_name, sheet_data in dataset.items():
+                if first:
+                    ws = wb.active
+                    ws.title = str(sheet_name)[:31]
+                    first = False
+                else:
+                    ws = wb.create_sheet(title=str(sheet_name)[:31])
+
+                rows, cols = FlatDictListHelper.flatten_dataset({"dataset": sheet_data})
+                ws.append(cols)
+
+                # `rows` always comes from FlatDictListHelper.flatten_dataset(), which always
+                # produces dicts - so every row here is a dict.
+                for row in rows:
+                    ws.append(
+                        [replace_crlf(str(row.get(col, "") or "")) if row.get(col) is not None else "" for col in cols]
+                    )
+        else:
+            ws = wb.active
+            rows, cols = FlatDictListHelper.flatten_dataset(context)
+            ws.append(cols)
+
+            for row in rows:
+                ws.append(
+                    [replace_crlf(str(row.get(col, "") or "")) if row.get(col) is not None else "" for col in cols]
+                )
+
+        with NamedTemporaryFile(delete=False, suffix=".xlsx") as tmp:
+            wb.save(tmp.name)
+            tmp_path = Path(tmp.name)
+
+        return self.write_zipfile([ZipFileEntry(zipfilealias=self.default_filename, osfilepath=tmp_path)])

flat_file_renderers-0.1.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: flat-file-renderers
+Version: 0.1.0
+Summary: Render tabular/nested datasets (list/dict/QuerySet-like) into xlsx, csv, tsv, json, html or parquet files, zipped, with zero required dependencies
+Author-email: Kelson da Costa Medeiros <kelsoncm@gmail.com>
+License: # License
+        
+        ## The MIT License (MIT)
+        
+        Copyright (c) 2026 python-by-kelsoncm
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/python-by-kelsoncm/python-flat-file-renderers
+Project-URL: Bug Tracker, https://github.com/python-by-kelsoncm/python-flat-file-renderers/issues
+Project-URL: Download, https://github.com/python-by-kelsoncm/python-flat-file-renderers/releases/
+Project-URL: Docs, https://python-by-kelsoncm.github.io/python-flat-file-renderers/
+Keywords: export,xlsx,csv,tsv,json,html,parquet,renderer,flatten
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+License-File: AUTHORS.md
+Provides-Extra: xlsx
+Requires-Dist: openpyxl>=3.1; extra == "xlsx"
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=15; extra == "parquet"
+Provides-Extra: all
+Requires-Dist: openpyxl>=3.1; extra == "all"
+Requires-Dist: pyarrow>=15; extra == "all"
+Provides-Extra: dev
+Requires-Dist: openpyxl>=3.1; extra == "dev"
+Requires-Dist: pyarrow>=15; extra == "dev"
+Requires-Dist: pre-commit>=4.6.0; extra == "dev"
+Requires-Dist: black>=26.3.1; extra == "dev"
+Requires-Dist: ruff>=0.15.11; extra == "dev"
+Requires-Dist: doc8>=2.0.0; extra == "dev"
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
+Requires-Dist: pytest-coverage-gate>=1.0.3; extra == "dev"
+Dynamic: license-file
+
+# flat-file-renderers
+
+[![License](https://img.shields.io/badge/License-MIT-lemon.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/pypi/pyversions/flat-file-renderers.svg)](https://pypi.org/project/flat-file-renderers/)
+[![QA](https://github.com/python-by-kelsoncm/python-flat-file-renderers/actions/workflows/qa.yml/badge.svg)](https://github.com/python-by-kelsoncm/python-flat-file-renderers/actions/workflows/qa.yml)
+[![Coverage](https://codecov.io/gh/python-by-kelsoncm/python-flat-file-renderers/branch/main/graph/badge.svg)](https://codecov.io/gh/python-by-kelsoncm/python-flat-file-renderers)
+[![Publish](https://github.com/python-by-kelsoncm/python-flat-file-renderers/actions/workflows/publish.yml/badge.svg)](https://github.com/python-by-kelsoncm/python-flat-file-renderers/actions/workflows/publish.yml)
+[![Docs](https://github.com/python-by-kelsoncm/python-flat-file-renderers/actions/workflows/docs.yml/badge.svg)](https://python-by-kelsoncm.github.io/python-flat-file-renderers/)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+
+Render tabular/nested datasets - a `list` of dicts, a `dict` of `{"rows": [...], "cols": [...]}`,
+a QuerySet-like iterable, or record/model objects - into **xlsx, csv, tsv, json, html or parquet**
+files, zipped. Nested lists of dicts are flattened automatically into dot+index-notation columns
+(`contacts.1.phone`, `contacts.2.phone`, ...), and a `dict[str, dataset]` renders one file per key
+into the same zip (one sheet per key for xlsx, one file per key for the others).
+
+No required dependencies for csv/tsv/json/html. `xlsx` and `parquet` are optional extras.
+
+## Installation
+
+```bash
+pip install flat-file-renderers            # csv, tsv, json, html - zero extra dependencies
+pip install flat-file-renderers[xlsx]       # + openpyxl, for XlsxRenderer
+pip install flat-file-renderers[parquet]    # + pyarrow, for ParquetRenderer
+pip install flat-file-renderers[all]        # everything
+```
+
+## Quick start
+
+```python
+from flat_file_renderers import CsvRenderer
+
+renderer = CsvRenderer({})
+zip_path = renderer.render({"dataset": [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]})
+# zip_path -> Path to a .zip containing one .csv
+```
+
+```python
+from flat_file_renderers.xlsx import XlsxRenderer  # requires the "xlsx" extra
+
+renderer = XlsxRenderer({})
+zip_path = renderer.render({"dataset": {"Students": [{"name": "Alice"}], "Courses": [{"title": "Python"}]}})
+# zip_path -> Path to a .zip containing one .xlsx with two sheets
+```
+
+Every renderer shares the same interface (`BaseRenderer.render(context) -> Path`, where
+`context["dataset"]` holds the data), so switching output formats is a one-line change:
+
+```python
+from flat_file_renderers import CsvRenderer, TsvRenderer, JsonRenderer, HtmlRenderer
+from flat_file_renderers.xlsx import XlsxRenderer
+from flat_file_renderers.parquet import ParquetRenderer
+
+for Renderer in (CsvRenderer, TsvRenderer, JsonRenderer, HtmlRenderer, XlsxRenderer, ParquetRenderer):
+    zip_path = Renderer({}).render({"dataset": rows})
+```
+
+## Modules
+
+* `flat_file_renderers.base` - `BaseRenderer`, `ZipFileEntry`
+* `flat_file_renderers.flat_dict_list_helper` - `FlatDictListHelper`, the flattening engine shared
+  by every renderer
+* `flat_file_renderers.separated_value` - `CsvRenderer`, `TsvRenderer`
+* `flat_file_renderers.json` - `JsonRenderer`
+* `flat_file_renderers.html` - `HtmlRenderer`
+* `flat_file_renderers.xlsx` - `XlsxRenderer` (extra: `xlsx`)
+* `flat_file_renderers.parquet` - `ParquetRenderer` (extra: `parquet`)
+
+See the [documentation](https://python-by-kelsoncm.github.io/python-flat-file-renderers/) for
+details and more examples.
+
+## Security
+
+Please report vulnerabilities according to [SECURITY.md](SECURITY.md).
+
+## Author
+
+Kelson da Costa Medeiros <kelsoncm@gmail.com>

flat_file_renderers-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+flat_file_renderers/__init__.py,sha256=jTonALV9bV3WLdASnkKp5SKTspffVEMKjcW0Ycm5IOg,1243
+flat_file_renderers/base.py,sha256=BwLjZADhwLAb--GUm7XLm02Ntq4D23O0RmE76Gyoiik,3717
+flat_file_renderers/flat_dict_list_helper.py,sha256=rwzYjvRfpwGjOjdIiGUF6Xruxrx4QEJ6CG_Z8ViVZlA,8233
+flat_file_renderers/html.py,sha256=6UqSflI3s19q2vjJlS6ocIrfGTAj1d59EMBQ7NrXE4g,3877
+flat_file_renderers/json.py,sha256=cn3r0CnrCDT0Kz15OLhC8VRPFKCkTQhHdAnoEwT5fqc,3156
+flat_file_renderers/parquet.py,sha256=956MgarUDkC6nCGg5clscB6rD96wvUow7NnD81MTWjs,2810
+flat_file_renderers/separated_value.py,sha256=P2_uIhdg8bx6OQ8EnIyWj336AsOpfihZjwPL-mUwRLs,4463
+flat_file_renderers/text.py,sha256=keouP5ByikDBr-o1QQcEUEFwd0PTgHBUbWsL1rqQgUs,393
+flat_file_renderers/xlsx.py,sha256=JVjXy8tmsoOw9PaINbMOXHZKqSI_Y1QqGNIYu4X_NqE,2317
+flat_file_renderers-0.1.0.dist-info/licenses/AUTHORS.md,sha256=qk2yCTi5iFKzq5whkvvZ-Wq-Mj47xcoOJGJkbu_RnI0,84
+flat_file_renderers-0.1.0.dist-info/licenses/LICENSE.md,sha256=mYRSY4lBNy3XDQwvexDjx4MsqTkyIosr8nZF4aqQRIE,1099
+flat_file_renderers-0.1.0.dist-info/METADATA,sha256=tu6g2zOXjj4Eob6lBHG9GXBQwEMxh6nZ_5ZSJTsxdQw,7275
+flat_file_renderers-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flat_file_renderers-0.1.0.dist-info/top_level.txt,sha256=rBvZ2SJJvUO7TnXRPlSy0M3bMQYSl6f5mU7wwoEcesY,20
+flat_file_renderers-0.1.0.dist-info/RECORD,,

flat_file_renderers-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flat_file_renderers-0.1.0.dist-info/licenses/AUTHORS.md

@@ -0,0 +1,3 @@
+# Authors
+
+- Kelson da Costa Medeiros <kelsoncm@gmail.com>, Tech Leader & Developer

flat_file_renderers-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,23 @@
+# License
+
+## The MIT License (MIT)
+
+Copyright (c) 2026 python-by-kelsoncm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flat_file_renderers-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+flat_file_renderers