This page permanently redirects to gemini://gemini.bortzmeyer.org/software/agunua/.

Agunua

Agunua is a Python library for the development of Gemini clients.

Installation

You need Python 3, PySocks, PyOpenSSL and netaddr. You can install the dependencies with pip pip3 install agunua.

=> PyOpenSSL | PySocks | netaddr

Usage

u = agunua.GeminiUri(url)
print(u)

Parameters in the GeminiUri() constructor (you can find their

default values at the beginning of the file Agunua/__init__.py):

• url: the URL to load
• insecure: accept invalid certificates (signed by unknown CA, for instance)
• tofu: performs TOFU (Trust On First Use) validation
• accept_expired: accept expired certificates (insecure = True is not sufficient for that)
• get_content: retrieve the actual resource (default is to get metadata only)
• parse_content: if it is gemtext (text/gemini), parse and extract links
• maxlines: if it is text, maximum number of lines retrieved. Set to None if you don't want a limit
• maxsize: maximum size in bytes to retrieve. Set to None if you don't want a limit
• binary: (automatic if the content is text). Retrieve as binary content, don't play with end-of-lines
• follow-redirect: automatically follow Gemini redirections
• redirect_depth: maximum number of redirections followed
• iri: handle IRI (URI in Unicode)
• force_ipv4: use the IPv4 protocol only
• force_ipv6: use the IPv6 protocol only
• send_sni: send the TLS Server Name Indication
• connect_to: use the host name in the URI for the Gemini request but connect only to this host (name or address). Useful when the host is multihomed.
• clientcert: the filename of a client certificate that will be sent to the server.
• clientkey: the filename of the private key of the above certificate.
• use_socks: use a SOCKS5 proxy (for instance for .onion capsules). The value must be a tuple (socks proxy name, socks proxy port).

If the URL is invalid (wrong syntax), you won't get a GeminiUri object. If you get one, it does not mean the resource has been retrieved successfully. See the attribute network_success for that, and then the attribute status_code (that you have to interpret yourself, in most cases).

Attributes of GeminiUri objects (not all of them will always be present; for instance, if you did not ask to get content, you won't have an attribute size; if the status code is not 20 - OK - you won't get a mediatype; etc):

• network_success: resource was retrieved successfully
• status_code: if retrieved successfully, the Gemini two-digit status code
• error: if network_success is false, this is the reason
• ip_address: IP address used for the retrieval (except is SOCKS was used)
• meta: the meta field of the Gemini protocol. It depends on the status code. Read the Gemini specification for detail.
• binary: if you asked for binary access, it will be True. If you asked for text access (binary=False in the constructor) and asked to ge the content (get_content=True), it will be set to False if decoding went well and True if the decoding failed, for instance because the file did not match the announced "charset".
• links: an array of the links found in the document (if you've set parse_content)
• payload: the content
• size: the size of the payload. Since Gemini does not have a way to indicate at the beginning the payload size, this will be obtained only if get_contentis true, and it will be limited by the parameter maxsize
• mediatype: the media type (MIME type) of the resource, such as text/gemini or image/jpeg
• lang: the human language of the resource, as standardized in BCP 47
• charset: actually the encoding of the resource such as UTF-8 or US-ASCII
• tls_version: the TLS version, for instance, "TLSv1.3"
• no_shutdown: set to True if the server did not properly close the TLS session. It may mean that the content was truncated. Meaningful only with get_content=True and if you asked for the whole file.
• The rest is related to certificates:
• issuer: the CA (Certificate Authority)
• subject: the name in the certificate (X.509 calls it "subject")
• cert_not_after: expiration date
• cert_not_before: inception date
• cert_algo: algorithm used by the CA
• cert_key_type: algorithm of the public key
• keystring: the public key
• cert_key_size: size of the public key

=> BCP 47 (RFC on codes for languages)

See sample-client.py. (In the source code, the test suite under tests/ is also a good way to learn about how to use the library.) Agunua is used in the Manisha monitoring tool and in the Lupa crawler.

=> Manisha | Lupa

Command-line client