agunua


Nameagunua JSON
Version 1.7.1 PyPI version JSON
download
home_pagehttps://framagit.org/bortzmeyer/agunua/
SummaryA library for the development of Gemini clients
upload_time2022-12-16 15:21:25
maintainer
docs_urlNone
authorStéphane Bortzmeyer
requires_python>=3.7
licenseGPL
keywords gemini
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Agunua

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

## Installation

You need Python 3, [netaddr](https://github.com/netaddr/netaddr),
[PySocks](https://github.com/Anorov/PySocks) and [PyOpenSSL](https://www.pyopenssl.org/).  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 load
* `insecure`: accept invalid certificates (signed by unknown CA, for
  instance)
* `tofu`: performs TOFU (Trust On First Use) validation. It is a
  string, not a boolean. If empty, we disable TOFU. Otherwise, it is
  the directory of TOFU data.
* `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
* `ignore_missing_tls_close`: ignore the lack of a proper TLS close (may lead to truncation attacks but many Gemini servers don't send it)
* `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_content`is 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](https://www.rfc-editor.org/info/bcp47)
* `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`: [DEPRECATED See https://framagit.org/bortzmeyer/agunua/-/issues/50] 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.
* `possible_truncation_issue`: set to True if we got a TLS error which may indicate that the data were truncated.
* The rest is related to certificates:
* `issuer`: the CA (Certificate Authority)
* `subject`: the name in the certificate (X.509 calls it "subject")
* `expired`: the certificate has expired
* `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

For an example, 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](https://framagit.org/bortzmeyer/manisha/) and in the [Lupa crawler](https://framagit.org/bortzmeyer/lupa/).

### Command-line client

`agunua` is a simple Gemini command-line client, a bit like curl. See
[its documentation](agunua.md). Most parameters of the library
`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.

### Download an entire capsule

Another command-line client, `geminitrack`, allows you to retrieve an entire capsule, for instance for backups. See [its documentation](geminitrack.md).

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

## Recent changes

See the file CHANGES.

## 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://github.com/cbrews/ignition Modelled on the `requests` library so very convenient for programmers
* https://git.carcosa.net/jmcbray/gusmobile/ Good code
* https://git.sr.ht/~fkfd/picross 
* https://github.com/apellis/pygemini No longer maintained





            

Raw data

            {
    "_id": null,
    "home_page": "https://framagit.org/bortzmeyer/agunua/",
    "name": "agunua",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": "",
    "keywords": "Gemini",
    "author": "St\u00e9phane Bortzmeyer",
    "author_email": "stephane+framagit@bortzmeyer.org",
    "download_url": "https://files.pythonhosted.org/packages/a3/cb/8ca8553b128f72cf4eb2d8adf8667d22b54ae430460a6138e4563d460508/agunua-1.7.1.tar.gz",
    "platform": null,
    "description": "# Agunua\n\nAgunua is a Python library for the development of Gemini clients.\n\n## Installation\n\nYou need Python 3, [netaddr](https://github.com/netaddr/netaddr),\n[PySocks](https://github.com/Anorov/PySocks) and [PyOpenSSL](https://www.pyopenssl.org/).  You\ncan install the dependencies with pip `pip3 install agunua`. \n\n## Usage\n\n```\nimport Agunua\n...\nu = Agunua.GeminiUri(url)\nprint(u)\n```\n\nParameters in the `GeminiUri()` constructor (you can find their\ndefault values at the beginning of the file `Agunua/__init__.py`):\n\n* `url`: the URL to load\n* `insecure`: accept invalid certificates (signed by unknown CA, for\n  instance)\n* `tofu`: performs TOFU (Trust On First Use) validation. It is a\n  string, not a boolean. If empty, we disable TOFU. Otherwise, it is\n  the directory of TOFU data.\n* `accept_expired`: accept expired certificates (`insecure = True` is\n  not sufficient for that)\n* `get_content`: retrieve the actual resource (default is to get\n  metadata only)\n* `parse_content`: if it is gemtext (text/gemini), parse and extract\n  links\n* `maxlines`: if it is text, maximum number of lines retrieved. Set to\n  None if you don't want a limit\n* `maxsize`: maximum size in bytes to retrieve. Set to\n  None if you don't want a limit\n* `binary`: (automatic if the content is text). Retrieve as binary\n  content, don't play with end-of-lines\n* `follow_redirect`: automatically follow Gemini redirections\n* `redirect_depth`: maximum number of redirections followed\n* `ignore_missing_tls_close`: ignore the lack of a proper TLS close (may lead to truncation attacks but many Gemini servers don't send it)\n* `iri`: handle IRI (URI in Unicode)\n* `force_ipv4`: use the IPv4 protocol only\n* `force_ipv6`: use the IPv6 protocol only\n* `send_sni`: send the TLS Server Name Indication \n* `connect_to`: use the host name in the URI for the Gemini request but\n  connect only to this host (name or address). Useful when the host is\n  multihomed.\n* `clientcert`: the filename of a client certificate that will be sent\n  to the server.\n* `clientkey`: the filename of the private key of the above\n  certificate.\n* `use_socks`: use a SOCKS5 proxy (for instance for `.onion`\n  capsules). The value must be a tuple (socks proxy name, socks proxy port).\n\nIf the URL is invalid (wrong syntax), you won't get a `GeminiUri`\nobject. If you get one, it does not mean the resource has been\nretrieved successfully. See the attribute `network_success` for that,\nand then the attribute `status_code` (that you have to interpret\nyourself, in most cases).\n\nAttributes of `GeminiUri` objects (not all of them will always be\npresent; for instance, if you did not ask to get content, you won't\nhave an attribute `size`; if the status code is not 20 - OK - you\nwon't get a mediatype; etc):\n\n* `network_success`: resource was retrieved successfully\n* `status_code`: if retrieved successfully, the Gemini two-digit\n  status code\n* `error`: if `network_success` is false, this is the reason\n* `ip_address`: IP address used for the retrieval (except is SOCKS was used)\n* `meta`: the `meta` field of the Gemini protocol. It depends on the\n status code. Read the Gemini specification for detail.\n* `binary`: if you asked for binary access, it will be True. If you\n  asked for text access (binary=False in the constructor) and asked to\n  ge the content (get_content=True), it will be set to False if\n  decoding went well and True if the decoding failed, for instance\n  because the file did not match the announced \"charset\".\n* `links`: an array of the links found in the document (if you've set\n  `parse_content`)\n* `payload`: the content\n* `size`: the size of the payload. Since Gemini does not have a way to\n  indicate at the beginning the payload size, this will be obtained\n  only if `get_content`is true, and it will be limited by the\n  parameter `maxsize`\n* `mediatype`: the media type (MIME type) of the resource, such as\n`text/gemini` or `image/jpeg`\n* `lang`: the human language of the resource, as standardized in [BCP 47](https://www.rfc-editor.org/info/bcp47)\n* `charset`: actually the encoding of the resource such as UTF-8 or US-ASCII\n* `tls_version`: the TLS version, for instance, \"TLSv1.3\"\n* `no_shutdown`: [DEPRECATED See https://framagit.org/bortzmeyer/agunua/-/issues/50] 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.\n* `possible_truncation_issue`: set to True if we got a TLS error which may indicate that the data were truncated.\n* The rest is related to certificates:\n* `issuer`: the CA (Certificate Authority)\n* `subject`: the name in the certificate (X.509 calls it \"subject\")\n* `expired`: the certificate has expired\n* `cert_not_after`: expiration date\n* `cert_not_before`: inception date\n* `cert_algo`: algorithm used by the CA\n* `cert_key_type`: algorithm of the public key\n* `keystring`: the public key\n* `cert_key_size`: size of the public key\n\nFor an example, 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](https://framagit.org/bortzmeyer/manisha/) and in the [Lupa crawler](https://framagit.org/bortzmeyer/lupa/).\n\n### Command-line client\n\n`agunua` is a simple Gemini command-line client, a bit like curl. See\n[its documentation](agunua.md). Most parameters of the library\n`GeminiUri()` constructor can be set via options. Important: the\ndefault value is not always the same with the command-line tool. For\ninstance, it defaults to actually retrieving the content.\n\n### Download an entire capsule\n\nAnother command-line client, `geminitrack`, allows you to retrieve an entire capsule, for instance for backups. See [its documentation](geminitrack.md).\n\n## Name\n\nAgunua is a melanesian serpent god. Caduceus would have been better\nfor a Python + Gemini project since there are two snakes on a caduceus\nbut it was already used.\n\n## License\n\nGPL. See LICENSE.\n\n## Recent changes\n\nSee the file CHANGES.\n\n## Authors\n\nSt\u00e9phane Bortzmeyer <stephane+framagit@bortzmeyer.org>.\n\n## Reference site\n\nhttps://framagit.org/bortzmeyer/agunua/ Use the Gitlab issue tracker to\nreport bugs or wishes. But you can of course also access it with\ngemini at gemini://gemini.bortzmeyer.org/software/agunua/\n\n## Other Gemini clients in Python \n\n* https://tildegit.org/solderpunk/gemini-demo-1 Very simple but working client\n* https://github.com/cbrews/ignition Modelled on the `requests` library so very convenient for programmers\n* https://git.carcosa.net/jmcbray/gusmobile/ Good code\n* https://git.sr.ht/~fkfd/picross \n* https://github.com/apellis/pygemini No longer maintained\n\n\n\n\n",
    "bugtrack_url": null,
    "license": "GPL",
    "summary": "A library for the development of Gemini clients",
    "version": "1.7.1",
    "split_keywords": [
        "gemini"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "53c0c6c8f1e5fa429fd7cbd2c76d672e",
                "sha256": "987a17acca642c38d573c4e012d6517e15de7140714a18b5e257ab728ff0ec30"
            },
            "downloads": -1,
            "filename": "agunua-1.7.1.tar.gz",
            "has_sig": true,
            "md5_digest": "53c0c6c8f1e5fa429fd7cbd2c76d672e",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 31107,
            "upload_time": "2022-12-16T15:21:25",
            "upload_time_iso_8601": "2022-12-16T15:21:25.639881Z",
            "url": "https://files.pythonhosted.org/packages/a3/cb/8ca8553b128f72cf4eb2d8adf8667d22b54ae430460a6138e4563d460508/agunua-1.7.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2022-12-16 15:21:25",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "lcname": "agunua"
}
        
Elapsed time: 0.01878s