topmark.registry.identity

topmark / registry / identity

Identity helpers for the TopMark registry.

This module centralizes small, dependency-light helpers related to registry identity construction and validation. It is intentionally shared by both file-type and processor models so namespace/local-key rules remain consistent.

owner_label

owner_label(obj_type)

Return a stable fully-qualified owner label for a Python type.

This helper is used in registry identity validation and error reporting to identify the defining class in a consistent diagnostic form.

Parameters:

Name	Type	Description	Default
obj_type	type[object]	The class/type to label.	required

Returns:

Type	Description
str	Fully-qualified owner label for diagnostics and validation messages.

Source code in src/topmark/registry/identity.py

def owner_label(obj_type: type[object]) -> str:
    """Return a stable fully-qualified owner label for a Python type.

    This helper is used in registry identity validation and error reporting to
    identify the defining class in a consistent diagnostic form.

    Args:
        obj_type: The class/type to label.

    Returns:
        Fully-qualified owner label for diagnostics and validation messages.
    """
    return f"{obj_type.__module__}.{obj_type.__qualname__}"

make_qualified_key

make_qualified_key(namespace, local_key)

Build a canonical qualified key from a namespace and local key.

Format: ":"

This helper centralizes identity construction for registry entities such as FileType and HeaderProcessor.

Parameters:

Name	Type	Description	Default
namespace	str	Namespace identifier (must already be validated).	required
local_key	str	Namespace-local identifier.	required

Returns:

Type	Description
str	Fully-qualified key string.

Note

This function does not perform validation. Callers are expected to provide already validated tokens.

Source code in src/topmark/registry/identity.py

def make_qualified_key(namespace: str, local_key: str) -> str:
    """Build a canonical qualified key from a namespace and local key.

    Format: "<namespace>:<local_key>"

    This helper centralizes identity construction for registry entities
    such as FileType and HeaderProcessor.

    Args:
        namespace: Namespace identifier (must already be validated).
        local_key: Namespace-local identifier.

    Returns:
        Fully-qualified key string.

    Note:
        This function does not perform validation. Callers are expected
        to provide already validated tokens.
    """
    return f"{namespace}:{local_key}"

split_qualified_key

split_qualified_key(qualified_key)

Split "<namespace>:<local_key>" into its components.

Parameters:

Name	Type	Description	Default
qualified_key	str	Fully-qualified registry identifier.	required

Returns:

Type	Description
tuple[str, str]	(namespace, local_key).

Notes

This helper performs a lightweight split only. It does not validate the resulting tokens or reject malformed inputs with multiple separators.

Source code in src/topmark/registry/identity.py

def split_qualified_key(qualified_key: str) -> tuple[str, str]:
    """Split ``"<namespace>:<local_key>"`` into its components.

    Args:
        qualified_key: Fully-qualified registry identifier.

    Returns:
        ``(namespace, local_key)``.

    Notes:
        This helper performs a lightweight split only. It does not validate the
        resulting tokens or reject malformed inputs with multiple separators.
    """
    namespace, _, local_key = qualified_key.partition(":")
    return namespace, local_key

is_valid_registry_token

is_valid_registry_token(value)

Return whether a registry token is valid.

Valid tokens are lowercase, must not contain ":", and must match VALID_REGISTRY_TOKEN_RE.

Source code in src/topmark/registry/identity.py

def is_valid_registry_token(value: str) -> bool:
    """Return whether a registry token is valid.

    Valid tokens are lowercase, must not contain ``":"``, and must match
    [`VALID_REGISTRY_TOKEN_RE`][topmark.core.constants.VALID_REGISTRY_TOKEN_RE].
    """
    if value != value.lower():
        return False
    if ":" in value:
        return False
    return bool(re.fullmatch(VALID_REGISTRY_TOKEN_RE, value))

validate_registry_token

validate_registry_token(value, *, field_name, owner)

Validate a single registry token.

Parameters:

Name	Type	Description	Default
value	str	Token value to validate.	required
field_name	str	Name of the corresponding field (for error reporting).	required
owner	str	Fully-qualified owner label (for error reporting).	required

Raises:

Type	Description
TypeError	If validation fails.

Source code in src/topmark/registry/identity.py

def validate_registry_token(value: str, *, field_name: str, owner: str) -> None:
    """Validate a single registry token.

    Args:
        value: Token value to validate.
        field_name: Name of the corresponding field (for error reporting).
        owner: Fully-qualified owner label (for error reporting).

    Raises:
        TypeError: If validation fails.
    """
    if not is_valid_registry_token(value):
        raise TypeError(
            f"{owner}.{field_name} must match {VALID_REGISTRY_TOKEN_RE}, "
            "be lowercase, and not contain ':' "
            f"(found {value!r})"
        )

require_nonempty_str

require_nonempty_str(value, *, field_name, owner)

Return value as str after enforcing type and non-empty presence.

Parameters:

Name	Type	Description	Default
value	object	Candidate value to validate.	required
field_name	str	Name of the corresponding field (for error reporting).	required
owner	str	Fully-qualified owner label (for error reporting).	required

Returns:

Type	Description
str	The validated string value.

Raises:

Type	Description
TypeError	If value is not a non-empty string.

Source code in src/topmark/registry/identity.py

def require_nonempty_str(value: object, *, field_name: str, owner: str) -> str:
    """Return `value` as `str` after enforcing type and non-empty presence.

    Args:
        value: Candidate value to validate.
        field_name: Name of the corresponding field (for error reporting).
        owner: Fully-qualified owner label (for error reporting).

    Returns:
        The validated string value.

    Raises:
        TypeError: If `value` is not a non-empty string.
    """
    if not isinstance(value, str) or not value:
        raise TypeError(f"{owner}.{field_name} must be a non-empty str")
    return value

require_and_validate_registry_identity

require_and_validate_registry_identity(
    *, namespace, local_key, owner
)

Validate and normalize a registry identity pair.

This helper first enforces that both values are non-empty strings and then validates them as registry tokens.

Parameters:

Name	Type	Description	Default
namespace	object	Candidate namespace value.	required
local_key	object	Candidate namespace-local identifier.	required
owner	str	Fully-qualified owner label (for error reporting).	required

Returns:

Type	Description
tuple[str, str]	Normalized (namespace, local_key) strings.

Raises:

Type	Description
TypeError	If either value is missing, not a string, or fails token validation.

Source code in src/topmark/registry/identity.py

def require_and_validate_registry_identity(
    *,
    namespace: object,
    local_key: object,
    owner: str,
) -> tuple[str, str]:
    """Validate and normalize a registry identity pair.

    This helper first enforces that both values are non-empty strings and then
    validates them as registry tokens.

    Args:
        namespace: Candidate namespace value.
        local_key: Candidate namespace-local identifier.
        owner: Fully-qualified owner label (for error reporting).

    Returns:
        Normalized `(namespace, local_key)` strings.

    Raises:
        TypeError: If either value is missing, not a string, or fails token
            validation.
    """
    ns: str = require_nonempty_str(namespace, field_name="namespace", owner=owner)
    lk: str = require_nonempty_str(local_key, field_name="local_key", owner=owner)
    try:
        validate_registry_identity(namespace=ns, local_key=lk, owner=owner)
    except TypeError:  # noqa: TRY203
        raise

    return ns, lk

validate_registry_identity

validate_registry_identity(*, namespace, local_key, owner)

Validate a registry identity pair (namespace, local_key).

Parameters:

Name	Type	Description	Default
namespace	str	Namespace value to validate.	required
local_key	str	Namespace-local identifier to validate.	required
owner	str	Fully-qualified owner label (for error reporting).	required

Raises:

Type	Description
TypeError	If either token fails validation.

Source code in src/topmark/registry/identity.py

def validate_registry_identity(
    *,
    namespace: str,
    local_key: str,
    owner: str,
) -> None:
    """Validate a registry identity pair (`namespace`, `local_key`).

    Args:
        namespace: Namespace value to validate.
        local_key: Namespace-local identifier to validate.
        owner: Fully-qualified owner label (for error reporting).

    Raises:
        TypeError: If either token fails validation.
    """
    try:
        validate_registry_token(
            local_key,
            field_name="local_key",
            owner=owner,
        )

        validate_registry_token(
            namespace,
            field_name="namespace",
            owner=owner,
        )
    except TypeError:  # noqa: TRY203
        raise

validate_reserved_topmark_namespace

validate_reserved_topmark_namespace(
    namespace, *, owner, owner_module, entities
)

Validate reserved use of the built-in topmark namespace.

Parameters:

Name	Type	Description	Default
namespace	str	Namespace value to validate.	required
owner	str	Fully-qualified owner label (for error reporting).	required
owner_module	str	Defining module of the corresponding entity.	required
entities	str	Human label for the validated entity type (for example, "file types" or "processors").	required

Raises:

Type	Description
TypeError	If the reserved TopMark namespace is used outside the TopMark package.

Source code in src/topmark/registry/identity.py

def validate_reserved_topmark_namespace(
    namespace: str,
    *,
    owner: str,
    owner_module: str,
    entities: str,
) -> None:
    """Validate reserved use of the built-in `topmark` namespace.

    Args:
        namespace: Namespace value to validate.
        owner: Fully-qualified owner label (for error reporting).
        owner_module: Defining module of the corresponding entity.
        entities: Human label for the validated entity type (for example,
            ``"file types"`` or ``"processors"``).

    Raises:
        TypeError: If the reserved TopMark namespace is used outside the TopMark package.
    """
    if namespace == TOPMARK_NAMESPACE and not owner_module.startswith(f"{PACKAGE_NAME}."):
        raise TypeError(
            f"{owner}: namespace '{TOPMARK_NAMESPACE}' is reserved for built-in TopMark {entities}."
        )