wasat.uri

Gemini and Titan URI representation and parsing.

GEMINI_DEFAULT_PORT module-attribute

GEMINI_DEFAULT_PORT: Final[int] = 1965

The default network port for the Gemini protocol.

GEMINI_PREFIX module-attribute

GEMINI_PREFIX: Final[str] = f'{GEMINI_SCHEME}://'

The standard prefix for Gemini URIs.

GEMINI_SCHEME module-attribute

GEMINI_SCHEME: Final[str] = 'gemini'

The URL scheme for the Gemini protocol.

TITAN_DEFAULT_PORT module-attribute

TITAN_DEFAULT_PORT: Final[int] = 1965

The default network port for the Titan protocol.

TITAN_PREFIX module-attribute

TITAN_PREFIX: Final[str] = f'{TITAN_SCHEME}://'

The standard prefix for Titan URIs.

TITAN_SCHEME module-attribute

TITAN_SCHEME: Final[str] = 'titan'

The URL scheme for the Titan protocol.

AnyURI

AnyURI = GeminiURI | TitanURI

Type alias for any supported protocol URI.

GeminiURI

GeminiURI(uri: str | GeminiURI)

Bases: _BaseURI

Represents a validated Gemini protocol URI.

Parameters:

Name	Type	Description	Default
uri	str | GeminiURI	The raw URI string or an existing GeminiURI to clone.	required

Raises:

Type	Description
URIError	If the URI is empty, the scheme is missing or is not 'gemini', the host is missing or invalid, or if parsing of the URI fails.

parent property

parent: Self

The URI representing the parent directory of this URI's path.

Note

Any query will be removed.

root property

root: Self

The URI representing the root directory of this URI's host.

Note

Any query will be removed.

without_query property

without_query: Self

Return a new GeminiURI with the query parameter removed.

Returns:

Type	Description
Self	A new GeminiURI instance without the query string.

Raises:

Type	Description
URIError	If the resulting URI is invalid.

__hash__

__hash__() -> int

Return the hash value of the URI.

__str__

__str__() -> str

Return the string representation of the URI.

replace

replace(
    *,
    host: str | _UnsetType = _UNSET,
    port: int | _UnsetType = _UNSET,
    path: str | None | _UnsetType = _UNSET,
    query: str | None | _UnsetType = _UNSET,
) -> Self

Create a new GeminiURI by replacing specific parts of this URI.

Parameters:

Name	Type	Description	Default
host	str | _UnsetType	The new hostname, or _UNSET to keep the current host.	_UNSET
port	int | _UnsetType	The new port number, or _UNSET to keep the current port.	_UNSET
path	str | None | _UnsetType	The new path, None to clear the path, or _UNSET to keep current.	_UNSET
query	str | None | _UnsetType	The new query string, None to clear the query, or _UNSET to keep current.	_UNSET

Returns:

Type	Description
Self	A new GeminiURI instance with the replaced components.

Raises:

Type	Description
URIError	If the resulting URI is invalid.

resolve

resolve(relative_uri: str) -> GeminiURI | TitanURI

Resolve a relative URI string against this URI as a base.

Parameters:

Name	Type	Description	Default
relative_uri	str	The relative or absolute target URI string.	required

Returns:

Type	Description
GeminiURI | TitanURI	A new GeminiURI or TitanURI representing the resolved target.

Raises:

Type	Description
URIError	If the resolved target URI is invalid, or if the relative URI cannot be parsed or resolved against the base URI.

to_titan

to_titan(
    *,
    edit: bool = False,
    size: int | None = None,
    mime: str | None = None,
    token: str | None = None,
) -> TitanURI

Convert this GeminiURI into a TitanURI with optional parameters.

Parameters:

Name	Type	Description	Default
edit	bool	Whether to generate an edit Titan URI (with ';edit' parameter).	False
size	int | None	Optional upload payload size in bytes.	None
mime	str | None	Optional MIME type of the payload.	None
token	str | None	Optional authorisation token.	None

Returns:

Type	Description
TitanURI	A new TitanURI instance.

Raises:

Type	Description
URIError	If edit is True and size is specified.

with_default_scheme classmethod

with_default_scheme(uri: str) -> Self

Add the Gemini scheme to a URI if it is missing.

Parameters:

Name	Type	Description	Default
uri	str	The URI string to check and potentially modify.	required

Returns:

Type	Description
Self	A new GeminiURI instance with the scheme added if it was missing.

Raises:

Type	Description
URIError	If the URI is empty, the scheme is not 'gemini', the host is missing or invalid, or if parsing of the URI fails.

with_host

with_host(host: str) -> Self

Return a new GeminiURI with the host replaced.

Parameters:

Name	Type	Description	Default
host	str	The new hostname.	required

Returns:

Type	Description
Self	A new GeminiURI instance with the updated host.

Raises:

Type	Description
URIError	If the resulting URI has an invalid or empty host.

with_path

with_path(path: str | None) -> Self

Return a new GeminiURI with the path replaced or cleared.

Parameters:

Name	Type	Description	Default
path	str | None	The new path, or None to clear/reset the path.	required

Returns:

Type	Description
Self	A new GeminiURI instance with the updated path.

Raises:

Type	Description
URIError	If the resulting URI path is invalid.

with_port

with_port(port: int) -> Self

Return a new GeminiURI with the port replaced.

Parameters:

Name	Type	Description	Default
port	int	The new port number.	required

Returns:

Type	Description
Self	A new GeminiURI instance with the updated port.

Raises:

Type	Description
URIError	If the resulting URI has an invalid or empty port.

with_query

with_query(query: str | None) -> Self

Return a new GeminiURI with the query parameter replaced, set or cleared.

Parameters:

Name	Type	Description	Default
query	str | None	The new query string (will be URL-encoded), or None to clear.	required

Returns:

Type	Description
Self	A new GeminiURI instance with the updated query.

Raises:

Type	Description
URIError	If the resulting URI query is invalid.

TitanURI

TitanURI(uri: str | TitanURI)

Bases: _BaseURI

Represents a validated Titan protocol URI with support for path parameters.

Parameters:

Name	Type	Description	Default
uri	str | TitanURI	The raw URI string or an existing TitanURI to clone.	required

Raises:

Type	Description
URIError	If the URI is empty, the scheme is missing or is not 'titan', the host is missing or invalid, or if parsing of the URI fails.

is_edit property

is_edit: bool

Whether this Titan URI represents an edit request (has ';edit' parameter).

mime property

mime: str | None

The MIME type parameter, or None if omitted.

parameters property

parameters: dict[str, str | None]

The dictionary of path parameters.

parent property

parent: Self

The URI representing the parent directory of this URI's path.

Note

Any query and parameters will be removed.

root property

root: Self

The URI representing the root directory of this URI's host.

Note

Any query and parameters will be removed.

size property

size: int | None

The upload size parameter in bytes, or None if omitted.

token property

token: str | None

The authorisation token parameter, or None if omitted.

without_parameters property

without_parameters: Self

Return a new TitanURI with all path parameters removed.

Returns:

Type	Description
Self	A new TitanURI instance without parameters.

without_query property

without_query: Self

Return a new TitanURI with the query parameter removed.

Returns:

Type	Description
Self	A new TitanURI instance without the query string.

Raises:

Type	Description
URIError	If the resulting URI is invalid.

__hash__

__hash__() -> int

Return the hash value of the URI.

__str__

__str__() -> str

Return the string representation of the URI.

replace

replace(
    *,
    host: str | _UnsetType = _UNSET,
    port: int | _UnsetType = _UNSET,
    path: str | None | _UnsetType = _UNSET,
    query: str | None | _UnsetType = _UNSET,
    size: int | None | _UnsetType = _UNSET,
    mime: str | None | _UnsetType = _UNSET,
    token: str | None | _UnsetType = _UNSET,
    edit: bool | _UnsetType = _UNSET,
    parameters: dict[str, str | None] | _UnsetType = _UNSET,
) -> Self

Create a new TitanURI by replacing specific parts of this URI.

Parameters:

Name	Type	Description	Default
host	str | _UnsetType	The new hostname, or _UNSET to keep current.	_UNSET
port	int | _UnsetType	The new port number, or _UNSET to keep current.	_UNSET
path	str | None | _UnsetType	The new path, or _UNSET to keep current.	_UNSET
query	str | None | _UnsetType	The new query string, or _UNSET to keep current.	_UNSET
size	int | None | _UnsetType	The new size parameter, None to remove, or _UNSET to keep current.	_UNSET
mime	str | None | _UnsetType	The new mime parameter, None to remove, or _UNSET to keep current.	_UNSET
token	str | None | _UnsetType	The new token parameter, None to remove, or _UNSET to keep current.	_UNSET
edit	bool | _UnsetType	True to set the edit parameter, False to remove, or _UNSET to keep current.	_UNSET
parameters	dict[str, str | None] | _UnsetType	Complete dictionary replacement of parameters, or _UNSET.	_UNSET

Returns:

Type	Description
Self	A new TitanURI instance with the replaced components.

Raises:

Type	Description
URIError	If the resulting URI is invalid.

resolve

resolve(relative_uri: str) -> GeminiURI | TitanURI

Resolve a relative URI string against this URI as a base.

Parameters:

Name	Type	Description	Default
relative_uri	str	The relative or absolute target URI string.	required

Returns:

Type	Description
GeminiURI | TitanURI	A new GeminiURI or TitanURI representing the resolved target.

Raises:

Type	Description
URIError	If the resolved target URI is invalid, or if the relative URI cannot be parsed or resolved against the base URI.

to_gemini

to_gemini() -> GeminiURI

Convert this TitanURI into a GeminiURI, stripping Titan parameters.

Returns:

Type	Description
GeminiURI	A new GeminiURI instance.

with_default_scheme classmethod

with_default_scheme(uri: str) -> Self

Add the Titan scheme to a URI if it is missing.

Parameters:

Name	Type	Description	Default
uri	str	The URI string to check and potentially modify.	required

Returns:

Type	Description
Self	A new TitanURI instance with the scheme added if it was missing.

Raises:

Type	Description
URIError	If the URI is empty, the scheme is not 'titan', the host is missing or invalid, or if parsing of the URI fails.

with_edit

with_edit(edit: bool = True) -> Self

Return a new TitanURI with the edit parameter set or removed.

Parameters:

Name	Type	Description	Default
edit	bool	True to set the edit parameter, False to remove it.	True

Returns:

Type	Description
Self	A new TitanURI instance.

with_host

with_host(host: str) -> Self

Return a new TitanURI with the host replaced.

Parameters:

Name	Type	Description	Default
host	str	The new hostname.	required

Returns:

Type	Description
Self	A new TitanURI instance with the updated host.

Raises:

Type	Description
URIError	If the resulting URI has an invalid or empty host.

with_mime

with_mime(mime: str | None) -> Self

Return a new TitanURI with the MIME type parameter set or removed.

Parameters:

Name	Type	Description	Default
mime	str | None	The MIME type string, or None to remove.	required

Returns:

Type	Description
Self	A new TitanURI instance.

with_parameters

with_parameters(parameters: dict[str, str | None]) -> Self

Return a new TitanURI with the parameters dictionary replaced.

Parameters:

Name	Type	Description	Default
parameters	dict[str, str | None]	The new dictionary of parameters.	required

Returns:

Type	Description
Self	A new TitanURI instance.

with_path

with_path(path: str | None) -> Self

Return a new TitanURI with the path replaced or cleared.

Parameters:

Name	Type	Description	Default
path	str | None	The new path, or None to clear/reset the path.	required

Returns:

Type	Description
Self	A new TitanURI instance with the updated path.

Raises:

Type	Description
URIError	If the resulting URI path is invalid.

with_port

with_port(port: int) -> Self

Return a new TitanURI with the port replaced.

Parameters:

Name	Type	Description	Default
port	int	The new port number.	required

Returns:

Type	Description
Self	A new TitanURI instance with the updated port.

Raises:

Type	Description
URIError	If the resulting URI has an invalid or empty port.

with_query

with_query(query: str | None) -> Self

Return a new TitanURI with the query parameter replaced, set or cleared.

Parameters:

Name	Type	Description	Default
query	str | None	The new query string (will be URL-encoded), or None to clear.	required

Returns:

Type	Description
Self	A new TitanURI instance with the updated query.

Raises:

Type	Description
URIError	If the resulting URI query is invalid.

with_size

with_size(size: int | None) -> Self

Return a new TitanURI with the size parameter set or removed.

Parameters:

Name	Type	Description	Default
size	int | None	The payload size in bytes, or None to remove.	required

Returns:

Type	Description
Self	A new TitanURI instance.

Raises:

Type	Description
URIError	If size is negative.

with_token

with_token(token: str | None) -> Self

Return a new TitanURI with the authorisation token parameter set or removed.

Parameters:

Name	Type	Description	Default
token	str | None	The authorisation token string, or None to remove.	required

Returns:

Type	Description
Self	A new TitanURI instance.

guess_mime_type

guess_mime_type(
    path: str | Path,
    default: str = "application/octet-stream",
) -> str

Guess the MIME type for a given file path.

Parameters:

Name	Type	Description	Default
path	str | Path	The file path or filename to inspect.	required
default	str	The fallback MIME type if detection fails.	'application/octet-stream'

Returns:

Type	Description
str	The detected MIME type string.