Convention Class Reference¶

Convention ¶

A Convention is a pattern made up of Fields, and follows the syntax: - {field_name} -> field - {@convention} -> reference to another convention - {$env_variable} -> environment variable

Convention instances use Rules to validate the value of each Field. Convention instances may include FixedFields, ensuring specific fields always retain predetermined values.

Parameters:

template (str) –

Template string
fixed_fields (dict[str, str], default: dict[str, str]() ) –

Optional mapping of field names to constant values.

Attributes¶

all_fields ¶

all_fields: list[str]

Return all fields appearing in the template.

Returns:

list[str] –

List of unique field names (including those used as environment variables).

environment_variables_fields ¶

environment_variables_fields: dict[str, str]

Return a mapping of environment variable placeholders to their values.

Returns:

dict[str, str] –

Mapping like {"$VAR": "value"} extracted from the process environment.

expanded_fixed_fields ¶

expanded_fixed_fields: dict[str, str]

Returns the fixed fields from the Convention, merged with the fixed fields of referenced Conventions Returns: dict: fully merged fixed_fields

expanded_template ¶

expanded_template: str

Return the template with references to other Conventions resolved.

References use the {@other_convention} syntax and are expanded recursively.

Returns:

str –

Template string with all {@...} references replaced.

Raises:

LucentRecursionError –

when too much recursion is detected.
LucentConventionNotFoundError –

when a referenced Convention does not exist.

fixed_fields ¶

fixed_fields: dict[str, str] = dataclass_field(default_factory=dict[str, str])

mandatory_fields ¶

mandatory_fields: list[str]

Return fields the user must provide to format the template.

Fields covered by fixed_fields are excluded.

Returns:

list[str] –

List of mandatory field names.

name ¶

name: str = dataclass_field(default='', init=False)

regex_pattern ¶

regex_pattern: str

Construct a regular expression that matches the Convention as a whole.

required_environment_variables ¶

required_environment_variables: list[str]

Return names of environment variables used in the template.

Environment variables use the {$NAME} syntax.

Returns:

list[str] –

List of environment variable names required by this Convention.

required_fields ¶

required_fields: list[str]

Return fields required to format the template that are not environment variables.

Returns:

list[str] –

List of unique field names required by the Convention.

template ¶

template: str

Methods:¶

format ¶

format(fields: dict[str, str] | None = None) -> str

Format the Convention's template with provided fields. FixedFields and environment variables are filled in automatically.

Parameters:

fields (dict[str, str] | None, default: None ) –

Mapping of field names to values to use when formatting.

Returns:

str –

Formatted string.

Raises:

LucentMissingFieldsError –

if required fields are missing.
LucentMissingEnvironmentVariablesError –

if required environment vars are missing.
LucentFieldValueError –

if any provided field value violates its Rule.

format_path ¶

format_path(fields: dict[str, str] | None = None) -> Path

Format the template and return a pathlib.Path object.

Parameters:

fields (dict[str, str] | None, default: None ) –

Mapping of field names to values.

Returns:

Path –

Path object representing the formatted template.

generate_examples ¶

generate_examples(fields: dict[str, str] | None = None, num: int = 5)

Generate up to num unique example strings by combining example values from Rules for mandatory fields.

Parameters:

fields (dict[str, str] | None, default: None ) –

Optional mapping to prefill some fields.
num (int, default: 5 ) –

Maximum number of distinct examples to generate.

Returns:

–

Either a single human-readable pattern string (if no examples available)
–

or a sorted list of generated example strings.

get_last_path ¶

get_last_path(fields: dict[str, str] | None = None, order: str = 'alphabetical') -> Path

Return the last path in the requested ordering.

Parameters:

fields (dict[str, str] | None, default: None ) –

Optional mapping to prefill some fields. All fields that are not provided will be replaced by wildcards
order (str, default: 'alphabetical' ) –

"alphabetical" or "date".

Returns:

Path –

Last Path matching the convention.

get_paths ¶

get_paths(fields: dict[str, str] | None = None, sort_callback: Callable[[list[Path]], list[Path]] | None = None) -> list[Path]

Resolve the Convention to a list of filesystem paths using globbing.

Parameters:

fields (dict[str, str] | None, default: None ) –

Optional mapping to prefill some fields (may include wildcards).
sort_callback (Callable[[list[Path]], list[Path]] | None, default: None ) –

Optional function to sort the matched paths.

Returns:

list[Path] –

List of Path objects strictly matching the Convention.

get_paths_sorted_by_date ¶

get_paths_sorted_by_date(fields: dict[str, str] | None = None) -> list[Path]

Return matching paths sorted by filesystem modification time.

glob_pattern ¶

glob_pattern(fields: dict[str, str] | None = None) -> str

Produce a glob-style pattern for filesystem lookups where unspecified fields are replaced by '*' wildcards.

Parameters:

fields (dict[str, str] | None, default: None ) –

Optional mapping used to prefill some fields.

Returns:

str –

Glob-compatible pattern string.

Raises:

LucentFieldValueError –

if provided fields violate their Rules.
LucentMissingEnvironmentVariablesError –

if required environment vars are missing.

human_readable_example_pattern ¶

human_readable_example_pattern(fields: dict[str, str] | None = None) -> str

Produce a human-readable template where missing fields are replaced by example values from their associated Rules when possible.

Parameters:

fields (dict[str, str] | None, default: None ) –

Optional mapping used to prefill some fields.

Returns:

str –

Formatted example pattern.

human_readable_pattern ¶

human_readable_pattern(fields: dict[str, str] | None = None) -> str

Produce a human-readable representation of the template with missing fields left as placeholders.

Parameters:

fields (dict[str, str] | None, default: None ) –

Optional mapping used to prefill some fields.

Returns:

str –

Formatted, human-readable template string.

increment ¶

increment(string: str | Path, field_to_increment: str = 'version', fields_to_enforce: dict[str, str] | None = None) -> 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

Raises:

LucentFieldValueError –

if any value does not match its Rule.

match ¶

match(string: str | Path) -> bool

Return whether the string matches the template.

parse ¶

parse(string: str | Path) -> dict[str, str]

Parse a string according to the Convention. Extracted field values are returned as a dict.

Parameters:

string (str | Path) –

The string or Path to parse. Please note that Lucent uses strings internally,

Returns:

dict ( dict[str, str] ) –

Mapping of field names to parsed values.

Raises:

LucentParseError –

when the string does not match the convention.
LucentMissingEnvironmentVariablesError –

if required environment vars are missing.
LucentInconsistentFieldsError –

if a field appears multiple times with different values.

show_mismatch ¶

show_mismatch(string: str | Path, fields: dict[str, str] | None = None)

Compare the provided string against a reference string generated from the provided fields.