Catalog#

class scikitplot.cleanprompt.Catalog(packs=<factory>, formats=<factory>, documents=<factory>, partial=False)[source]#

An immutable set of packs and formats.

Parameters:
packsmapping

Name to PackSpec.

formatsmapping

Name to FormatSpec.

documentsmapping

"pack:NAME" or "format:NAME" to the canonical JSON the spec was built from. Carried so a plan can be fingerprinted by content.

partialbool, default=False

A fragment meant only to be merged — a set of custom definitions whose requires name packs that live in the catalog it will join. Cross references are checked when it is merged, not before.

Raises:
CleanPromptError

If two formats claim one extension, or a requires names a pack that is not in the catalog, or the requirements form a cycle.

Parameters:
static code_vocabulary(packs)[source]#

Return the union of the packs’ code sections.

Parameters:
packsiterable of PackSpec

Resolved packs.

Returns:
CodeSpec

Sorted and deduplicated.

Parameters:

packs (Iterable[PackSpec])

Return type:

CodeSpec

documents: Mapping[str, str][source]#
static field_index(packs)[source]#

Return normalised field name to rule, across packs.

Parameters:
packsiterable of PackSpec

Resolved packs.

Returns:
dict

One entry per field name.

Raises:
CleanPromptError

If two packs give one field name different kinds. Silently keeping either would decide what a value is called by the order packs were listed in.

Parameters:

packs (Iterable[PackSpec])

Return type:

dict[str, FieldSpec]

fingerprint(packs, formats)[source]#

Return a digest of the selected definitions’ content.

Parameters:
packs, formatsiterable

The selection.

Returns:
str

Hex SHA-256 over their canonical documents.

Parameters:
Return type:

str

format_for(path, allowed=None)[source]#

Return the format that reads a file, or None.

Parameters:
pathstr or path-like

The file name. Only the name is used; nothing is opened.

allowediterable of FormatSpec, optional

Restrict the answer to these formats.

Returns:
FormatSpec or None

None when no allowed format claims the extension.

Parameters:
Return type:

FormatSpec | None

Notes

Developer notes. A dotfile such as .env has no suffix to pathlib, so its whole name is tried as the extension. That is the only special case, and it is the one that matters: .env is where credentials live.

Examples

>>> builtin_catalog().format_for("deploy/.env").name
'env'
>>> builtin_catalog().format_for("notes.MD").name
'markdown'
formats: Mapping[str, FormatSpec][source]#
merge(other, conflict='error')[source]#

Return this catalog with another’s definitions added.

Parameters:
otherCatalog

Usually a custom catalog.

conflict{‘error’, ‘replace’}, default=’error’

What to do when both define a name differently. An identical redefinition is never a conflict.

Returns:
Catalog

A new catalog.

Raises:
CleanPromptError

On a conflict under 'error', naming every clashing definition.

Parameters:
Return type:

Catalog

packs: Mapping[str, PackSpec][source]#
partial: bool = False#
resolve_formats(selection='all')[source]#

Return the formats a selection means, sorted by name.

Parameters:
selectionstr or iterable of str or None, default=’all’

'all', one name, or several; None or 'none' for none. An extension such as '.sh' is accepted in place of a name.

Returns:
tuple of FormatSpec

Sorted by name.

Raises:
CleanPromptError

If a name or extension is unknown.

Parameters:

selection (str | Iterable[str] | None)

Return type:

tuple[FormatSpec, …]

resolve_packs(selection='all', formats=None)[source]#

Return the packs a selection means, with their requirements.

Parameters:
selectionstr or iterable of str or None, default=’all’

'all', 'none', 'auto', one name, or several. None means 'none'.

formatsiterable of FormatSpec, optional

Consulted only by 'auto': the union of their suggested packs.

Returns:
tuple of PackSpec

Dependencies first, ties broken by name.

Raises:
CleanPromptError

If a name is unknown.

Parameters:
Return type:

tuple[PackSpec, …]

Examples

>>> [p.name for p in builtin_catalog().resolve_packs("addressbook")]
['personal', 'addressbook']