caosadvancedtools.table_json_conversion.table_generator module#

This module allows to generate template tables from JSON schemas.

exception caosadvancedtools.table_json_conversion.table_generator.EmptySchemaException#

Bases: RuntimeError

Exception for when a schema is empty, so that no meaningful table can be generated.

class caosadvancedtools.table_json_conversion.table_generator.TableTemplateGenerator#

Bases: ABC

Base class for generating tables from json schema

abstractmethod generate(schema: dict, foreign_keys: dict, filepath: str, use_ids_as_foreign: bool = False)#

Generate a sheet definition from a given JSON schema.

Parameters:#

schema: dict

Given JSON schema.

foreign_keys: dict

A tree-like configuration (nested dict) that defines which attributes shall be used to create additional columns when a list of references exists. The nested dict is structured like the data model, its innermost elements are leaves of the path trees within the JSON, they define the required keys.

Suppose we want to distinguish Persons that are referenced by Trainings, then foreign_keys must at least contain the following:
{"Training": {"Person": ["name", "email"]}}.

Values within the dicts can be either a list representing the keys (as in the example above) or a dict that allows to set additional foreign keys at higher depths. In the latter case (dict instead of list) if foreign keys exist at that level (e.g. in the above example there might be further levels below “Person”), then the foreign keys can be set using the special __this__ key.

Example: {"Training": {"__this__": ["date"], "Person": ["name", "email"]}} Here, date is the sole foreign key for Training.

It probably is worth extending the first example, with a case where a “Training” shall be distiguished by the “name” and “email” of a “Person” which it references. The foreign keys for this example are specified like this:
{"Training": {"__this__": [["Person", "name"], ["Person", "email"]]}}
use_ids_as_foreign: bool, optional

If True, use the id (a property named “id”) as foreign key, if the key does not exist in the dict. Default is False.

class caosadvancedtools.table_json_conversion.table_generator.XLSXTemplateGenerator#

Bases: TableTemplateGenerator

Class for generating XLSX tables from json schema definitions.

generate(schema: dict, foreign_keys: dict, filepath: str | Path, use_ids_as_foreign: bool = False) → None#

Generate a sheet definition from a given JSON schema.

Parameters:#

schema: dict

Given JSON schema

foreign_keys: dict

A configuration that defines which attributes shall be used to create additional columns when a list of references exists. See foreign_keys argument of TableTemplateGenerator.generate() .

filepath: Union[str, Path]

The XLSX file will be stored under this path.

static normalize_sheet_titles(sheets: dict[str, Any]) → dict[str, Any]#

Shorten title with more than 31 characters. Return normalized dict.

Specification:

  • Short titles are left unchanged.

  • Titles are unique.

  • Long titles are shortened like this:

    1. Titles are split into parts at the dot character (.)

    2. Parts are reused from the end to front, until at most 26 characters are used up. These parts form the tail (joined by . characters).

    3. A head is added, and also joined by the . character. The head is exactly 4 characters long and consists of these parts:

      • The first character of the first part.

      • An underscore character (_).

      • The lowest two-digit number starting from 01 (so one of 01, 02, …, 98, 99), that leads to no collision with existing titles. If all options would lead to a collision, a OverflowError is thrown.

Parameters:

sheets (dict[str, Any]) – The title -> content dict of sheets.

Returns:

out – Same as the input sheets, but long titles (keys) are shortened in a sensible way.

Return type:

dict[str, Any]