port70.uri

Gopher URI representation and parsing.

DEFAULT_ITEM_TYPE module-attribute

DEFAULT_ITEM_TYPE: Final[str] = '1'

The default Gopher item type (directory/gophermap).

GOPHER_DEFAULT_PORT module-attribute

GOPHER_DEFAULT_PORT: Final[int] = 70

The default TCP network port for the Gopher protocol.

GOPHER_PREFIX module-attribute

GOPHER_PREFIX: Final[str] = f'{GOPHER_SCHEME}://'

The standard prefix for Gopher URIs.

GOPHER_SCHEME module-attribute

GOPHER_SCHEME: Final[str] = 'gopher'

The default URL scheme for the Gopher protocol.

GopherURI

GopherURI(uri: str | GopherURI)

Represents a validated Gopher protocol URI following RFC 4266 / RFC 1436.

Parameters:

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

Raises:

Type	Description
URIError	If the URI is empty, the scheme is missing or is not 'gopher', 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 Gopher URI string.

bytes_left cached property

bytes_left: int

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

host property

host: str

The target hostname or IP address.

is_search property

is_search: bool

True if the item type is search ('7') or a search query is provided.

is_too_long cached property

is_too_long: bool

Is the URI too long to be valid?

item_type property

item_type: str

The Gopher item type character.

parent property

parent: Self

Return a GopherURI representing the parent directory of this URI's selector path.

path property

path: str

The resource path portion of the URI (e.g. '/1' or '/0/file.txt').

port property

port: int

The target port (defaults to GOPHER_DEFAULT_PORT).

query property

query: str | None

The query string or None.

request_bytes property

request_bytes: bytes

Return selector payload bytes sent over TCP to the Gopher server.

request_string property

request_string: str

Return the selector payload string sent over TCP to the Gopher server.

root property

root: Self

Return a GopherURI representing the root directory of this URI's host.

scheme property

scheme: str

The URI scheme (always 'gopher').

selector property

selector: str

The Gopher selector string.

without_query property

without_query: Self

Return a new GopherURI with the query parameter removed.

from_string classmethod

from_string(target: str) -> Self

Create a GopherURI from a target string or URI.

Parameters:

Name	Type	Description	Default
target	str	The target string or Gopher URI.	required

Returns:

Type	Description
Self	A new GopherURI instance.

Raises:

Type	Description
URIError	If parsing fails or required host is missing.

replace

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

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

Parameters:

Name	Type	Description	Default
host	str | _UnsetType	The new hostname, or _UNSET to keep current host.	_UNSET
port	int | _UnsetType	The new port number, or _UNSET to keep current port.	_UNSET
item_type	str | _UnsetType	The new item type character, or _UNSET to keep current.	_UNSET
selector	str | _UnsetType	The new selector, or _UNSET to keep current.	_UNSET
query	str | None | _UnsetType	The new query string, None to clear, or _UNSET to keep current.	_UNSET

Returns:

Type	Description
Self	A new GopherURI instance with updated components.

Raises:

Type	Description
URIError	If the resulting URI 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 GopherURI representing the resolved target.

Raises:

Type	Description
URIError	If resolution fails or target is invalid.

with_default_scheme classmethod

with_default_scheme(uri: str) -> Self

Add the Gopher 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 GopherURI instance with the scheme added if it was missing.

Raises:

Type	Description
URIError	If the URI is invalid or missing required components.

with_host

with_host(host: str) -> Self

Return a new GopherURI with the host replaced.

with_item_type

with_item_type(item_type: str) -> Self

Return a new GopherURI with the item type replaced.

with_port

with_port(port: int) -> Self

Return a new GopherURI with the port replaced.

with_query

with_query(query: str | None) -> Self

Return a new GopherURI with the query parameter replaced or cleared.

with_selector

with_selector(selector: str) -> Self

Return a new GopherURI with the selector replaced.