flat_file_renderers.flat_dict_list_helper module

class flat_file_renderers.flat_dict_list_helper.FlatDictListHelper

Bases: object

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.

static 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.

Parameters:

• row (dict) – Data row, possibly containing plain values, lists of dicts, or nested dicts.

• parent_key (str) – Key prefix (used during recursion).

Returns:

Flat dict with all keys expanded.

Return type:

dict

Example

deep_flatten({“name”: “Alice”, “contacts”: [{“phone”: “1234”}, {“phone”: “5678”}]}) -> {“name”: “Alice”, “contacts.1.phone”: “1234”, “contacts.2.phone”: “5678”}

static 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 ‘.’.

Parameters:

row (dict) – Data row, holding plain values or lists of dicts.

Returns:

Flat dict where lists of dicts have been expanded into dot+index-notation columns.

Return type:

dict

Example

expand_row({“name”: “Alice”, “contacts”: [{“phone”: “1234”}, {“phone”: “5678”}]}) -> {“name”: “Alice”, “contacts.1.phone”: “1234”, “contacts.2.phone”: “5678”}

static 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.

Parameters:

rows (list) – List of dicts or record/model objects representing the data rows.

Returns:

List of column names, including columns expanded from lists of dicts,

with normalized keys.

Return type:

list[str]

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”]

static 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.

Parameters:

context (dict) – Context containing the ‘dataset’ key.

Returns:

Tuple of (rows, column names - if available).

Return type:

tuple[list, list]

Raises:

ValueError – If the context has no ‘dataset’ key, or its type isn’t supported.

static 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.

Parameters:

context (dict) – Context containing the ‘dataset’ key.

Returns:

List of flat rows and list of column names.

Return type:

tuple[list[dict], list[str]]

static normalize_key(key: str) → str

Replaces ‘__’ with ‘.’ in keys, to avoid clashing with the list-of-dicts dot notation.

Parameters:

key (str) – Key to normalize.

Returns:

Normalized key, with ‘__’ replaced by ‘.’.

Return type:

str

Example

normalize_key(“address__street”) -> “address.street” normalize_key(“person__contacts__1__phone”) -> “person.contacts.1.phone”