Codex Class Reference¶

Codex ¶

Top-level container that binds Rules and Conventions together.

A Codex injects itself into all registered Convention instances so they can resolve references and access the shared Rules.

Attributes¶

convs ¶

convs: Conventions

human_readable ¶

human_readable: str

Returns a human readable version of the codex, detailing its Rules and Conventions

rules ¶

rules: Rules

Methods:¶

get_convention ¶

get_convention(string: str | Path, conventions: list[Convention] | None = None, reverse: bool = True) -> Convention

Return the Convention that matches the provided string.

Parameters:

string (str | Path) –

The string to resolve.
conventions (list[Convention] | None, default: None ) –

Optional list to limit candidate Conventions.
reverse (bool, default: True ) –

Whether to search in reverse order.

Returns:

Convention –

Convention instance that matched the string.

get_convention_by_name ¶

get_convention_by_name(name: str) -> Convention

Retrieve a registered Convention by name.

Parameters:

name (str) –

Name of the Convention to retrieve.

Returns:

Convention –

Convention instance.

Raises:

LucentConventionNotFoundError –

when the named Convention does not exist.

get_datetime_fields ¶

get_datetime_fields() -> dict[str, str]

Return a mapping of current datetime fields (year, month, day, hour, min, sec).

get_fields ¶

get_fields(string: str | Path, conventions: list[Convention] | None = None, reverse: bool = True) -> dict[str, str]

Parse a string and return its fields.

Parameters:

string (str | Path) –

The string to parse.
conventions (list[Convention] | None, default: None ) –

Optional list to limit search.
reverse (bool, default: True ) –

Whether to iterate conventions in reverse order.

Returns:

dict[str, str] –

Mapping of field names to values.

get_rule_by_name ¶

get_rule_by_name(name: str, default: bool = False) -> Rule

Retrieve a Rule by name.

Parameters:

name (str) –

Name of the Rule.
default (bool, default: False ) –

When True, return the 'default' Rule instead of raising if not found.

Returns:

Rule –

Rule instance or None (if default is False and not found).

Raises:

LucentRuleNotFoundError –

when the Rule is not found and default is False.

get_uuid_field ¶

get_uuid_field() -> dict[str, str]

Return a mapping containing a generated uuid value for the 'uuid' field.

increment ¶

increment(string: str | Path, field_to_increment: str = 'version', fields_to_enforce: dict[str, str] | None = None, conventions: list[Convention] | None = None, reverse: bool = False) -> str

Increments a field from the provided string (by default, the "version" field) Additional fields may be set in the process.

Parameters:

string (str | Path) –

string to modify
field_to_increment (str, default: 'version' ) –

name of the field that needs to be incremented
fields_to_enforce (dict[str, str] | None, default: None ) –

additional fields to format
conventions (list[Convention] | None, default: None ) –

Optional list to limit candidate Conventions when parsing.
reverse (bool, default: False ) –

Whether to iterate over conventions in reverse order.

Returns:

str –

source string, with a field incremented by one

solve ¶

solve(string: str | Path, conventions: list[Convention] | None = None, reverse: bool = False) -> tuple[Convention, dict[str, str]]

Iterates through available Conventions (or a provided subset) and tries to parse the string. Returns a tuple containing the matching Convention and the fields deduced from the parsing operation

Parameters:

string (str | Path) –

The string to resolve.
conventions (list[Convention] | None, default: None ) –

Optional list of Convention instances to limit search.
reverse (bool, default: False ) –

Whether to iterate conventions in reverse order.

Returns:

tuple[Convention, dict[str, str]] –

Tuple containing the matching Convention and the fields deduced from the parsing operation

Raises:

LucentParseError –

if no Convention matches.

transmute ¶

transmute(string: str | Path, target_convention: Convention | None = None, fields: dict[str, str] | None = None, conventions: list[Convention] | None = None) -> str

Parse a string and re-format it using another Convention.

Parameters:

string (str | Path) –

Source string to parse.
target_convention (Convention | None, default: None ) –

Convention to format to. If None, the source Convention is reused.
fields (dict[str, str] | None, default: None ) –

Optional fields to override parsed values.
conventions (list[Convention] | None, default: None ) –

Optional list to limit candidate Conventions when parsing.

Returns:

str –

Reformatted string according to the target Convention.