comicbox.formats.base.online.transform_helpers

source module comicbox.formats.base.online.transform_helpers

Shared helpers for online-source transforms.

Both MetronApiTransform and ComicVineApiTransform need to convert list-of-dicts collections into comicbox’s SimpleNamedDictField shape ({name: {extra_fields}}), parse credit/role lists, and build identifier sub-dicts. Putting the shared logic here keeps the per- source transforms readable.

Functions

  • named_dict — Convert a list of {name, ...} dicts into a {name: {}} dict.

  • named_dict_with_id — Like named_dict, but each entry carries an identifiers sub-dict.

  • build_identifier — Build the identifier sub-dict for one id.

  • parse_creator_roles — Split a comma-string of role names (“writer, penciler”) into a list.

  • split_aliases — Split ComicVine’s newline-separated volume aliases string into a list.

  • credits_to_cb — Convert a list of credits into comicbox’s nested credits shape.

  • named_block — Pull {key: {name: <name>}} out of a nested {id, name} dict, or None.

  • alt_names_to_cb — Convert a series’ alternative names into comicbox alternative names.

  • reprints_to_cb — Convert mokkari’s reprints list into comicbox’s ReprintSchema list.

source named_dict(items: Iterable[Mapping[str, Any]] | None, *, key: str = ‘name’) → dict[str, dict]

Convert a list of {name, ...} dicts into a {name: {}} dict.

Used for SimpleNamedDictField targets: characters, teams, story arcs, locations, universes, etc.

source named_dict_with_id(items: Iterable[Mapping[str, Any]] | None, source: str, id_type: str = ‘issue’) → dict[str, dict]

Like named_dict, but each entry carries an identifiers sub-dict.

The id field of each item maps to comicbox’s IdentifiedNameSchema identifiers.<source>.{key, url}. Used where the upstream provides an id alongside the name (most named collections on Metron and CV).

source build_identifier(source: str, id_type: str, value: Any) → dict[str, str]

Build the identifier sub-dict for one id.

source parse_creator_roles(raw: str | None) → list[str]

Split a comma-string of role names (“writer, penciler”) into a list.

ComicVine returns creator roles as a comma-separated string; mokkari returns them as a list of {id, name} dicts so this is only used for the CV path. Empty / None inputs produce [].

source split_aliases(raw: str | None) → list[str]

Split ComicVine’s newline-separated volume aliases string into a list.

mokkari returns series alt names as a list already so this is only used for the CV path. Empty / None inputs produce [].

source credits_to_cb(credits_list: Iterable[Mapping[str, Any]] | None, *, creator_key: str, role_key: str, role_is_string: bool = False, source: str | None = None, creator_id_type: str = ‘creator’) → dict[str, dict]

Convert a list of credits into comicbox’s nested credits shape.

The shape is {<creator>: {roles: {<role>: {}}, identifiers: {...}}}.

role_is_string=True means role is a comma-separated string (CV). Otherwise role is a list of {id, name} dicts (mokkari).

source and creator_id_type populate the per-creator identifiers sub-dict from the upstream creator id; pass None to skip.

source named_block(parent: Mapping[str, Any], key: str) → dict[str, str] | None

Pull {key: {name: <name>}} out of a nested {id, name} dict, or None.

Used for publisher / imprint / similar single-named blocks where the upstream returns a small {id, name} object but comicbox stores it as {name: ...} only.

source alt_names_to_cb(alt_names: Iterable[str | None] | None, primary_name: str | None) → list[dict]

Convert a series’ alternative names into comicbox alternative names.

These land in series.alternative_names, the same place MetronInfo.xml’s Series/AlternativeNames do. They are other names for this series, not reprints of this issue. The online APIs carry no language for them, so no language is set.

Names are stripped; empties, case-insensitive duplicates, and names matching the primary series name are dropped.

source reprints_to_cb(reprints: Iterable[Mapping[str, Any]] | None, *, source: str) → list[dict]

Convert mokkari’s reprints list into comicbox’s ReprintSchema list.

mokkari Reprint has id (Metron issue id) and issue (display string like “Series Name #N”). We pass the issue string through; the metron id goes into identifiers.<source> per ReprintSchema.