tlc.helpers.url_aliases

Programmatic URL-alias registration.

These helpers let user code add and remove URL aliases at runtime:

• tlc.url.register_url_alias() — add a <TOKEN> → path mapping.

• tlc.url.unregister_url_alias() — remove a previously-registered alias.

• tlc.url.get_registered_url_aliases() — snapshot of the current merged view (token → path).

• tlc.url.get_alias_path() — look up the path for a single token.

Programmatic registrations are recorded at the API tier of the unified configuration store (tlc.config). Aliases declared in config files, environment variables (TLC_ALIAS_*), or on the CLI continue to participate alongside; the merged view returned to URL operations follows the normal configuration precedence ladder (API > CLI > env > file > default), so higher-priority sources override lower-priority ones for the same token.

For the typical end-user entry point, see tlc.url.

Module Contents

Functions

Function	Description
get_alias_path	Return the path of a registered URL alias, or None if not registered.
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.

Data

Data	Description
alias_logger

API

exception AliasConflictError

Bases: tlc.helpers.url_aliases.AliasError, ValueError

tlc.url.register_url_alias() failed because the token is already mapped to a different path and force=False. Multi-inherits ValueError so existing except ValueError: handlers keep working.

Initialize self. See help(type(self)) for accurate signature.

exception AliasError

Bases: Exception

Base class for alias-registry errors. Catch this to handle any failure.

Initialize self. See help(type(self)) for accurate signature.

exception AliasNotFoundError

Bases: tlc.helpers.url_aliases.AliasError, KeyError

tlc.url.unregister_url_alias() was given a token that isn’t present at the programmatic API tier. Multi-inherits KeyError so existing except KeyError: handlers keep working.

Initialize self. See help(type(self)) for accurate signature.

alias_logger = getLogger(...)

get_alias_path(

token: str,

) → str | None

Return the path of a registered URL alias, or None if not registered.

This is a read-only lookup and never raises for a bad token. A token that is unregistered or syntactically invalid simply yields None — no validation exception is raised. For validation (and the rules a token must satisfy), see tlc.url.register_url_alias().

The token is canonicalized before lookup, so a bare name such as HOME is matched against the registered <HOME> entry.

Parameters:

token – The alias token to look up. May be given bare (HOME) or canonical (<HOME>).

Returns:

The registered path for the token, or None if the token is not registered or is syntactically invalid.

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,

*args: bool,

force: bool = _FORCE_UNSET,

) → 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.

• *args – Deprecated positional slot for force. Pass force as a keyword argument instead.

• force – If True, overwrite an existing registration that points to a different path. Defaults to False so two unrelated callers that both try to claim the same token surface as a conflict rather than silently last-writer-wins. Pass this as a keyword argument (force=True); passing it positionally is deprecated and will be removed in a future release.

Raises:

• ValueError – If the token or path is syntactically invalid.

• AliasConflictError – If the alias is already registered with a different path and force=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:

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