tlc.helpers.url_aliases¶

Programmatic URL-alias registration backed by the unified Configuration store.

Mutation of the URL alias registry lives at the configuration layer rather than on the private UrlAliasRegistry itself: the URL package stays a read-only facade over an installed AliasProvider, while writes go through these free functions which target the API-tier slice of tlc.config. File / env / CLI tiers continue to participate via the normal precedence merge.

Module Contents¶

Functions¶

Function

Description

get_alias_path

Return the path of a registered URL alias.

get_registered_url_aliases

Return the registered URL aliases.

register_url_alias

Register an alias for a URL.

unregister_url_alias

Unregister a programmatically-registered URL alias.

API¶

get_alias_path(
token: str,
) → str | None¶

Return the path of a registered URL alias.

get_registered_url_aliases() → dict[str, str]¶

Return the registered URL aliases.

Returns:

A dictionary mapping alias tokens to paths.

register_url_alias(
token: str,
path: str | Url | Path,
force: bool = True,
) → None¶

Register an alias for a URL.

Writes the alias into the API-tier slice of the unified configuration store (tlc.config). File / env-tier alias entries are not touched, so later reloads of those sources continue to take effect normally.

Parameters:

  • token – The alias token to register. Must match the regex [A-Z][A-Z0-9_]*.

  • path – The path to alias.

  • force – If True, force the registration of the alias even if it is already registered.

Raises:

ValueError – If the token or path is invalid, or if the alias already exists (in the merged view) with a different path and force is False.

unregister_url_alias(
token: str,
) → None¶

Unregister a programmatically-registered URL alias.

Removes the token from the API-tier slice only. If the same token is also defined at a lower-precedence source (env, file), that value resurfaces in the merged view via the normal precedence merge.

Parameters:

token – The alias token to unregister. Must match the regex [A-Z][A-Z0-9_]*.

Raises:

KeyError – If the token is not present in the API-tier slice — file / env entries cannot be removed through this API; edit the underlying source to take them out.