wasat.client

Gemini Protocol async client implementation.

Client

Client(
    *,
    verify_mode: Literal["ca", "tofu", "off"] = "ca",
    trust_store: TrustStore | None = None,
    trust_store_path: str | Path | None = None,
    client_cert: str | Path | None = None,
    client_key: str | Path | None = None,
    on_new_certificate: NewCertCallback | None = None,
    follow_redirects: bool = True,
    max_redirects: int = 5,
    connect_timeout: float = 10.0,
    read_timeout: float = 30.0,
    ssl_context: SSLContext | None = None,
)

Asynchronous Gemini Protocol Client.

Parameters:

Name	Type	Description	Default
verify_mode	Literal['ca', 'tofu', 'off']	The certificate verification mode: - 'ca': Trust certificates signed by system CAs. - 'tofu': Trust-On-First-Use validation. - 'off': Disable certificate verification (insecure).	'ca'
trust_store	TrustStore | None	Custom TrustStore instance for TOFU mode.	None
trust_store_path	str | Path | None	Filepath for the default FileTrustStore in TOFU mode.	None
client_cert	str | Path | None	Path to client TLS certificate (for client auth).	None
client_key	str | Path | None	Path to client TLS private key (optional if in cert file).	None
on_new_certificate	NewCertCallback | None	Async callback called when a new certificate is encountered in TOFU mode. Must return True to accept, False to reject.	None
follow_redirects	bool	If True, automatically follow redirects.	True
max_redirects	int	Maximum number of redirects to follow.	5
connect_timeout	float	Timeout in seconds for establishing a connection.	10.0
read_timeout	float	Timeout in seconds for reading the response line.	30.0
ssl_context	SSLContext | None	Pre-configured ssl.SSLContext. Overrides verify_mode/cert config.	None

request async

request(uri: str | GeminiURI) -> Response

Perform a Gemini request and return the response.

Automatically handles redirection if configured.

Parameters:

Name	Type	Description	Default
uri	str | GeminiURI	The target URI as a string or GeminiURI object.	required

Returns:

Type	Description
Response	The final Gemini Response object.

Raises:

Type	Description
URIError	If the URI is invalid.
ConnectionError	If network connection fails or times out.
SecurityError	If TLS/certificate check fails.
ProtocolError	If the server response violates the Gemini protocol.
RedirectError	If redirect limits are exceeded or loops are detected.

WrappedStreamReader

WrappedStreamReader(
    reader: StreamReader, writer: StreamWriter
)

Wraps StreamReader to ensure the StreamWriter is closed upon reaching EOF or on error.

Parameters:

Name	Type	Description	Default
reader	StreamReader	The stream reader to wrap.	required
writer	StreamWriter	The stream writer to close on EOF or error.	required

close async

close() -> None

Close the writer transport.

read async

read(n: int = -1) -> bytes

Read data from the stream, closing the connection at EOF.

Parameters:

Name	Type	Description	Default
n	int	Number of bytes to read, or -1 to read until EOF.	-1

Returns:

Type	Description
bytes	The read bytes.

Raises:

Type	Description
Exception	Any exception raised by the underlying reader.