httk.core.entry_ids

Format, parse, and validate human-readable httk entry identifiers.

Attributes

ENTRY_ID_PATTERN
IMMUTABLE_ID_PATTERN
ALTERNATIVE_KIND_PATTERN
ALTERNATIVE_ID_PATTERN

Functions

format_entry_id(base, series, number)	Format a recommended entry identifier.
format_immutable_id(entry_id, revision)	Format an immutable identifier for an entry revision.
format_alternative_id(entry_id, kind[, revision])	Format an alternative identifier for a named alternative representation of an entry.
parse_entry_id(value)	Parse a recommended entry identifier.
parse_immutable_id(value)	Parse an immutable identifier with a recommended embedded entry id.
parse_alternative_id(value)	Parse an alternative identifier with a recommended embedded entry id.
is_url_safe_id(value)	Return whether an identifier is safe for use in a URL path segment.
check_entry_id(value)	Check an entry identifier, warning for recommended-syntax deviations.
check_immutable_id(value)	Check an immutable identifier, warning for recommended-syntax deviations.

Module Contents

httk.core.entry_ids.ENTRY_ID_PATTERN

httk.core.entry_ids.IMMUTABLE_ID_PATTERN

httk.core.entry_ids.ALTERNATIVE_KIND_PATTERN

httk.core.entry_ids.ALTERNATIVE_ID_PATTERN

httk.core.entry_ids.format_entry_id(base, series, number)

Format a recommended entry identifier.

Parameters:

• base (str) – Dot-separated identifier namespace.

• series (str) – Identifier series token.

• number (int) – Positive entry number.

Returns:

The formatted entry identifier.

Raises:

• TypeError – If number is not a non-boolean integer.

• ValueError – If the formatted identifier does not match the recommended syntax.

Return type:

str

httk.core.entry_ids.format_immutable_id(entry_id, revision)

Format an immutable identifier for an entry revision.

Parameters:

• entry_id (str) – URL-safe entry identifier, including non-conforming user identifiers.

• revision (int) – Positive revision number.

Returns:

The formatted immutable identifier.

Raises:

• TypeError – If revision is not a non-boolean integer.

• ValueError – If entry_id is not URL-safe or revision is less than one.

Return type:

str

httk.core.entry_ids.format_alternative_id(entry_id, kind, revision=None)

Format an alternative identifier for a named alternative representation of an entry.

Parameters:

• entry_id (str) – URL-safe entry identifier, including non-conforming user identifiers.

• kind (str) – Alternative-kind token matching [a-z][a-z0-9_]*.

• revision (int | None) – Optional positive revision number of the alternative.

Returns:

The formatted alternative identifier.

Raises:

• TypeError – If revision is given and is not a non-boolean integer.

• ValueError – If kind is malformed, entry_id is not URL-safe, or revision is less than one.

Return type:

str

httk.core.entry_ids.parse_entry_id(value)

Parse a recommended entry identifier.

Parameters:

value (str) – Entry identifier to parse.

Returns:

The (base, series, number) parts, or None if invalid.

Return type:

tuple[str, str, int] | None

httk.core.entry_ids.parse_immutable_id(value)

Parse an immutable identifier with a recommended embedded entry id.

Parameters:

value (str) – Immutable identifier to parse.

Returns:

The (entry_id, revision) parts, or None if invalid.

Return type:

tuple[str, int] | None

httk.core.entry_ids.parse_alternative_id(value)

Parse an alternative identifier with a recommended embedded entry id.

Parameters:

value (str) – Alternative identifier to parse.

Returns:

The (entry_id, kind, revision) parts (revision None when absent), or None if invalid.

Return type:

tuple[str, str, int | None] | None

httk.core.entry_ids.is_url_safe_id(value)

Return whether an identifier is safe for use in a URL path segment.

Parameters:

value (str) – Identifier to inspect.

Returns:

True if the value is non-empty printable ASCII without /.

Return type:

bool

httk.core.entry_ids.check_entry_id(value)

Check an entry identifier, warning for recommended-syntax deviations.

Parameters:

value (str) – Entry identifier to check.

Returns:

The unchanged identifier.

Raises:

ValueError – If the identifier is not URL-safe.

Return type:

str

httk.core.entry_ids.check_immutable_id(value)

Check an immutable identifier, warning for recommended-syntax deviations.

Parameters:

value (str) – Immutable identifier to check.

Returns:

The unchanged identifier.

Raises:

ValueError – If the identifier is not URL-safe.

Return type:

str