wasat.uri

Gemini 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 default URL scheme for the Gemini protocol.

GeminiURI

GeminiURI(uri: str | GeminiURI)

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.

MAXIMUM_LENGTH class-attribute instance-attribute

MAXIMUM_LENGTH: Final[int] = 1024

The maximum length of a Gemini URI string.

bytes_left cached property

bytes_left: int

The number of left left before reaching the maximum URI length.

host property

host: str

The target hostname.

is_too_long cached property

is_too_long: bool

Is the URI too long to be valid?

parent property

parent: Self

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

Note

Any query will be removed.

path property

path: str

The resource path (defaults to '/').

port property

port: int

The target port (defaults to GEMINI_DEFAULT_PORT).

query property

query: str | None

The query string or None.

root property

root: Self

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

Note

Any query will be removed.

scheme property

scheme: str

The URI scheme (always 'gemini').

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.

__len__

__len__() -> int

Return the length of the string representation 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 (e.g., if the replaced host or port is invalid).

resolve

resolve(relative_uri: str) -> Self

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
Self	A new GeminiURI 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.

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.