A library for the development of Gemini clients
Project description
Agunua
Agunua is a Python library for the development of Gemini clients.
Installation
You need Python 3, netaddr and PyOpenSSL. You
can install the dependencies with pip pip3 install agunua
.
Usage
import Agunua
...
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 loadinsecure
: accept invalid certificates (signed by unknown CA, for instance)tofu
: performs TOFU (Trust On First Use) validationaccept_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 linksmaxlines
: if it is text, maximum number of lines retrieved. Set to None if you don't want a limitmaxsize
: maximum size in bytes to retrieve. Set to None if you don't want a limitbinary
: (automatic if the content is text). Retrieve as binary content, don't play with end-of-linesfollow-redirect
: automatically follow Gemini redirectionsredirect_depth
: maximum number of redirections followediri
: handle IRI (URI in Unicode)force_ipv4
: use the IPv4 protocol onlyforce_ipv6
: use the IPv6 protocol onlyconnect_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.
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 successfullystatus_code
: if retrieved successfully, the Gemini two-digit status codeerror
: ifnetwork_success
is false, this is the reasonip_address
: IP address used for the retrievalmeta
: themeta
field of the Gemini protocol. It depends on the status code. Read the Gemini specification for detail.links
: an array of the links found in the document (if you've setparse_content
)payload
: the contentsize
: 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 ifget_content
is true, and it will be limited by the parametermaxsize
mediatype
: the media type (MIME type) of the resource, such astext/gemini
orimage/jpeg
lang
: the human language of the resource, as standardized in BCP 47charset
: actually the encoding of the resource such as UTF-8 or US-ASCII- 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 datecert_not_before
: inception datecert_algo
: algorithm used by the CAcert_key_type
: algorithm of the public keykeystring
: the public keycert_key_size
: size of the public key
See sample-client.py
. Agunua is used in the Manisha monitoring
tool and in the Lupa crawler.
Command-line client
agunua
is a simple Gemini command-line client, a bit like
curl. You can just call:
agunua YOUR-URL
And you will get its content. Most parameters of the GeminiUri()
constructor can be set via options. Important: the default value is
not always the same with the command-line tool. For instance, it
defaults to actually retrieving the content. Here are the options:
--maximum-time
: maximum time in seconds before giving in if the server does not respond--insecure
: do not check the certificate--no-tofu
: do not perform TOFU (Trust On First Use) validation--accept-expired-certificate
: even with--insecure
, expired certificates are not accepted unless you use also this option--not-follow-redirect
: by default, the tool follows Gemini redirections but you can use this option to avoid it--verbose
: more talkative--display-links
: instead of displaying the content, display the links it contains--maxlines
: maximum number of lines to retrieve (for text files). Set to 0 for "no limit"--maxsize
: maximum amount of bytes to retrieve. Set to 0 for "no limit"--connect-to
: connect to this specific host (name or IP address) not to the one mentioned in the URL--binary
: even if this is a text file, download as binary--force-ipv4
: use only the IPv4 protocol--force-ipv6
: use only the IPv6 protocol
Name
Agunua is a melanesian serpent god. Caduceus would have been better for a Python + Gemini project since there are two snakes on a caduceus but it was already used.
License
GPL. See LICENSE.
Authors
Stéphane Bortzmeyer stephane+framagit@bortzmeyer.org.
Reference site
https://framagit.org/bortzmeyer/agunua/ Use the Gitlab issue tracker to report bugs or wishes. But you can of course also access it with gemini at gemini://gemini.bortzmeyer.org/software/agunua/
Other Gemini clients in Python
- https://tildegit.org/solderpunk/gemini-demo-1 Very simple but working client
- https://git.carcosa.net/jmcbray/gusmobile/ Good code
- https://git.sr.ht/~fkfd/picross
- https://github.com/apellis/pygemini No longer maintained
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.