port79.uri

Finger URI representation and parsing based on RFC 1288.

FINGER_DEFAULT_PORT module-attribute

FINGER_DEFAULT_PORT: Final[int] = 79

The default TCP network port for the Finger protocol.

FINGER_PREFIX module-attribute

FINGER_PREFIX: Final[str] = f'{FINGER_SCHEME}://'

The standard prefix for Finger URIs.

FINGER_SCHEME module-attribute

FINGER_SCHEME: Final[str] = 'finger'

The default URL scheme for the Finger protocol.

FingerURI

FingerURI(uri: str | FingerURI)

Represents a validated Finger protocol URI.

Parameters:

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

Raises:

Type	Description
URIError	If the URI is empty, 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 Finger URI string.

bytes_left cached property

bytes_left: int

The number of characters remaining before reaching maximum URI length.

host property

host: str

The target hostname or IP address.

is_forwarding_query property

is_forwarding_query: bool

Whether this query involves remote host forwarding.

is_system_query property

is_system_query: bool

Whether this is a system-wide query for logged-in users.

is_too_long cached property

is_too_long: bool

Whether the URI string length exceeds the maximum allowed length.

is_user_query property

is_user_query: bool

Whether this is a query for a specific user.

is_verbose property

is_verbose: bool

Whether the /W verbose switch is requested.

path property

path: str

The path portion of the URI.

port property

port: int

The target TCP port (defaults to 79).

query property

query: str | None

The raw query parameter string of the URI, or None.

query_kind property

query_kind: QueryKind

The QueryKind enumeration value representing this query type.

raw_query property

raw_query: str

The formatted Finger command string including CRLF sequence.

scheme property

scheme: str

The URI scheme (always 'finger').

target_host property

target_host: str | None

The remote target host for forwarding queries, if applicable.

username property

username: str | None

The username being queried, or None for a system query.

__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.

from_string classmethod

from_string(target: str) -> Self

Create a FingerURI from a target string or URI.

Parameters:

Name	Type	Description	Default
target	str	The target string (e.g., 'davep@plan.cat' or 'finger://plan.cat/davep').	required

Returns:

Type	Description
Self	A new FingerURI instance.

Raises:

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

replace

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

Create a new FingerURI 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
username	str | None | _UnsetType	The new username, None to clear, or _UNSET to keep current.	_UNSET
target_host	str | None | _UnsetType	The new target host for forwarding, None to clear, or _UNSET.	_UNSET
is_verbose	bool | _UnsetType	The new verbose status, or _UNSET to keep current.	_UNSET
path	str | None | _UnsetType	The new path, or _UNSET to derive from username/verbose.	_UNSET
query	str | None | _UnsetType	The new query string, or _UNSET to derive from verbose.	_UNSET

Returns:

Type	Description
Self	A new FingerURI instance with updated components.

Raises:

Type	Description
URIError	If the resulting URI components are invalid.

with_default_scheme classmethod

with_default_scheme(uri: str) -> Self

Add the Finger 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 FingerURI instance with the scheme added if missing.

Raises:

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

with_host

with_host(host: str) -> Self

Return a new FingerURI with the host replaced.

Parameters:

Name	Type	Description	Default
host	str	The new target hostname.	required

Returns:

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

Raises:

Type	Description
URIError	If the resulting host is invalid or empty.

with_port

with_port(port: int) -> Self

Return a new FingerURI with the port replaced.

Parameters:

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

Returns:

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

Raises:

Type	Description
URIError	If the resulting port is invalid.

with_username

with_username(username: str | None) -> Self

Return a new FingerURI with the username replaced or cleared.

Parameters:

Name	Type	Description	Default
username	str | None	The new username, or None to convert to a system query.	required

Returns:

Type	Description
Self	A new FingerURI instance with the updated username.

with_verbose

with_verbose(verbose: bool = True) -> Self

Return a new FingerURI with the verbose switch updated.

Parameters:

Name	Type	Description	Default
verbose	bool	True to enable verbose mode, False to disable.	True

Returns:

Type	Description
Self	A new FingerURI instance with updated verbose setting.