flat-file-renderers 0.1.0__tar.gz

flat_file_renderers-0.1.0/AUTHORS.md

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

flat_file_renderers-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,78 @@
+# 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/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-0.1.0/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-0.1.0/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