# Ignition: Python3 Gemini Protocol Client Transport Library
Ignition is a simple but powerful transport library for Python3 clients using the recently designed [Gemini protocol](https://geminiprotocol.net/). This project intends to implement all of the [transport specifications](https://geminiprotocol.net/docs/specification.gmi) (sections 1-4) of the Gemini protocol and provide an easy-to-use interface, so as to act as a building block in a larger application.
If you're building a Python3 application that uses Gemini, Ignition is your gateway to the stars, in very much the same way that [requests](https://requests.readthedocs.io/en/master/) is for HTTP and **gopherlib** is for Gopher.
In order to provide a best-in-class interface, this library does not implement the other parts of a typical client (including user interface and/or command line interface), and instead focuses on providing a robust programmatic API interface. This project also assumes that different user interfaces will have different requirements for their display of text/gemini files (.gmi), and/or other mime-types, and as such considers this portion of the specification beyond the scope of this project.
In addition, in order to provide stability and simplicity, minimal third-party dependencies are required for Ignition.
## Project Status
[](https://github.com/cbrews/ignition/actions/workflows/ci-v2.yml)
Ignition is no longer being updated.
## Installation
⚠ Ignition supports Python versions 3.7 - 3.12.
Ignition can be installed via [PIP](https://pypi.org/project/ignition-gemini/). You should install it in alignment with your current development process; if you do not have a build process yet, I recommend you install within a [virtual environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/)
```bash
pip install ignition-gemini
```
If you prefer to install from source, you can clone and install the repository:
```bash
git clone https://github.com/cbrews/ignition.git
cd ignition
pip install .
```
## Simple Usage
The most basic usage of Ignition allows the user to create a request and get a response back from a remote Gemini capsule:
```python
import ignition
# Fetch capsule content
response = ignition.request('//geminiprotocol.net')
# Get status from remote capsule
print(response.status)
# Get response information from remote capsule
print(response.data())
```
[source](examples/simple_usage.py)
In **all** cases, Ignition assumes that the specified endpoint and protocol will respond over the Gemini protocol, so even if you provide a different protocol or port, it will assume that the endpoint is a Gemini capsule.
## Key Features
✅ Ignition supports the following features:
* Basic request/response connectivity to a Gemini-enabled server.
* Basic URL parsing mechanics to allow for specifying protocol, host, port, path, and query params, as per [RFC-3986](https://tools.ietf.org/html/rfc3986)
* Optional referer URL handling. Ignition allows the user to pass a path & referer URL and can construct the new path, to simplifying the resolution of links on a Gemini capsule page.
* Basic decoding of body responses on successful (20) response from Gemini servers.
* Trust-on-first-use certificate verification handling scheme using key signatures.
* Fully-featured response objects for each response type.
* Standardized & robust, human-readable error management.
* Custom error handling for networking failure cases beyond the scope of the protocol.
❌ The following Gemini features will *not* be supported by Ignition:
* Behavioral processing/handling of specific response types from Gemini capsules, including:
* Generation of client certificates & automatic resubmission.
* Automatic redirection following on 3x responses.
* Advanced body response rendering and/or display of text/gemini mime types.
* Command line or GUI interface.
* Advanced session & history management.
* Support for other protocols.
* Non-verified certificate scheme
* Improved TOFU scenarios
## Advanced Usage
More advanced request usage:
```python
import ignition
response = ignition.request('/software', referer='//geminiprotocol.net:1965')
print("Got back response %s from %s" % (response.status, response.url))
# Got back a response 20 from gemini://geminiprotocol.net/software
if not response.success():
print("There was an error on the response.")
else:
print(response.data())
```
Passing a referer:
```python
import ignition
response1 = ignition.request('//geminiprotocol.net')
response2 = ignition.request('software', referer=response1.url)
print(response2)
```
[source](examples/using_referer.py)
More advanced response validation:
```python
import ignition
url = '//geminiprotocol.net'
response = ignition.request(url)
if response.is_a(ignition.SuccessResponse):
print('Success!')
print(response.data())
elif response.is_a(ignition.InputResponse):
print('Needs additional input: %s' % (response.data()))
elif response.is_a(ignition.RedirectResponse):
print('Received response, redirect to: %s' % (response.data()))
elif response.is_a(ignition.TempFailureResponse):
print('Error from server: %s' % (response.data()))
elif response.is_a(ignition.PermFailureResponse):
print('Error from server: %s' % (response.data()))
elif response.is_a(ignition.ClientCertRequiredResponse):
print('Client certificate required. %s' % (response.data()))
elif response.is_a(ignition.ErrorResponse):
print('There was an error on the request: %s' % (response.data()))
```
[source](examples/advanced_usage.py)
Finally, the module exposes `DEBUG` level logging via standard python capabilities. If you are having trouble with the requests, enable debug-level logging with:
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```
## API Documentation
Full API documentation for Ignition is available [here](./docs/api.md).
## Developers
Ignition is no longer accepting contributions. Please feel free to fork this repository.
## License
Ignition is licensed under [Mozilla Public License 2.0](https://www.mozilla.org/en-US/MPL/).
Copyright 2020-2024 by [Chris Brousseau](https://github.com/cbrews).
## Thank you
* *solderpunk* for leading the design of the [Gemini protocol](https://geminiprotocol.net/docs/specification.html), without which this project would not have been possible.
* *Sean Conman* for writing the [Gemini torture tests](gemini://gemini.conman.org/test/torture), which were instrumental in initial client testing.
* *Michael Lazar* for his work on [Jetforce](https://github.com/michael-lazar/jetforce), which helped testing along the way.
🔭 Happy exploring!
Raw data
{
"_id": null,
"home_page": null,
"name": "ignition-gemini",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "client, gemini, networking, request, socket",
"author": null,
"author_email": "Chris Brousseau <cbrews@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/dd/c1/e20a471e78640857f8fa80ed31d2ffaf6541301fec0ce403717425c87e58/ignition_gemini-1.0.0.tar.gz",
"platform": null,
"description": "# Ignition: Python3 Gemini Protocol Client Transport Library\n\n\n\nIgnition is a simple but powerful transport library for Python3 clients using the recently designed [Gemini protocol](https://geminiprotocol.net/). This project intends to implement all of the [transport specifications](https://geminiprotocol.net/docs/specification.gmi) (sections 1-4) of the Gemini protocol and provide an easy-to-use interface, so as to act as a building block in a larger application.\n\nIf you're building a Python3 application that uses Gemini, Ignition is your gateway to the stars, in very much the same way that [requests](https://requests.readthedocs.io/en/master/) is for HTTP and **gopherlib** is for Gopher.\n\nIn order to provide a best-in-class interface, this library does not implement the other parts of a typical client (including user interface and/or command line interface), and instead focuses on providing a robust programmatic API interface. This project also assumes that different user interfaces will have different requirements for their display of text/gemini files (.gmi), and/or other mime-types, and as such considers this portion of the specification beyond the scope of this project.\n\nIn addition, in order to provide stability and simplicity, minimal third-party dependencies are required for Ignition.\n\n## Project Status\n\n[](https://github.com/cbrews/ignition/actions/workflows/ci-v2.yml)\n\n\n\n\n\nIgnition is no longer being updated.\n\n## Installation\n\u26a0 Ignition supports Python versions 3.7 - 3.12.\n\nIgnition can be installed via [PIP](https://pypi.org/project/ignition-gemini/). You should install it in alignment with your current development process; if you do not have a build process yet, I recommend you install within a [virtual environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/)\n\n```bash\npip install ignition-gemini\n```\n\nIf you prefer to install from source, you can clone and install the repository:\n\n```bash\ngit clone https://github.com/cbrews/ignition.git\ncd ignition\npip install .\n```\n\n## Simple Usage\nThe most basic usage of Ignition allows the user to create a request and get a response back from a remote Gemini capsule:\n```python\nimport ignition\n\n# Fetch capsule content\nresponse = ignition.request('//geminiprotocol.net')\n\n# Get status from remote capsule\nprint(response.status)\n\n# Get response information from remote capsule\nprint(response.data())\n```\n[source](examples/simple_usage.py)\n\nIn **all** cases, Ignition assumes that the specified endpoint and protocol will respond over the Gemini protocol, so even if you provide a different protocol or port, it will assume that the endpoint is a Gemini capsule.\n\n## Key Features\n\n\n\n\u2705 Ignition supports the following features:\n* Basic request/response connectivity to a Gemini-enabled server.\n* Basic URL parsing mechanics to allow for specifying protocol, host, port, path, and query params, as per [RFC-3986](https://tools.ietf.org/html/rfc3986)\n* Optional referer URL handling. Ignition allows the user to pass a path & referer URL and can construct the new path, to simplifying the resolution of links on a Gemini capsule page.\n* Basic decoding of body responses on successful (20) response from Gemini servers.\n* Trust-on-first-use certificate verification handling scheme using key signatures.\n* Fully-featured response objects for each response type.\n* Standardized & robust, human-readable error management.\n* Custom error handling for networking failure cases beyond the scope of the protocol.\n\n\u274c The following Gemini features will *not* be supported by Ignition:\n* Behavioral processing/handling of specific response types from Gemini capsules, including:\n * Generation of client certificates & automatic resubmission.\n * Automatic redirection following on 3x responses.\n* Advanced body response rendering and/or display of text/gemini mime types.\n* Command line or GUI interface.\n* Advanced session & history management.\n* Support for other protocols.\n* Non-verified certificate scheme\n* Improved TOFU scenarios\n\n## Advanced Usage\nMore advanced request usage:\n\n```python\nimport ignition\n\nresponse = ignition.request('/software', referer='//geminiprotocol.net:1965')\n\nprint(\"Got back response %s from %s\" % (response.status, response.url))\n# Got back a response 20 from gemini://geminiprotocol.net/software\n\nif not response.success():\n print(\"There was an error on the response.\")\nelse:\n print(response.data())\n```\n\nPassing a referer:\n```python\nimport ignition\n\nresponse1 = ignition.request('//geminiprotocol.net')\nresponse2 = ignition.request('software', referer=response1.url)\n\nprint(response2)\n```\n[source](examples/using_referer.py)\n\nMore advanced response validation:\n```python\nimport ignition\n\nurl = '//geminiprotocol.net'\nresponse = ignition.request(url)\n\nif response.is_a(ignition.SuccessResponse):\n print('Success!')\n print(response.data())\n\nelif response.is_a(ignition.InputResponse):\n print('Needs additional input: %s' % (response.data()))\n\nelif response.is_a(ignition.RedirectResponse):\n print('Received response, redirect to: %s' % (response.data()))\n\nelif response.is_a(ignition.TempFailureResponse):\n print('Error from server: %s' % (response.data()))\n\nelif response.is_a(ignition.PermFailureResponse):\n print('Error from server: %s' % (response.data()))\n\nelif response.is_a(ignition.ClientCertRequiredResponse):\n print('Client certificate required. %s' % (response.data()))\n\nelif response.is_a(ignition.ErrorResponse):\n print('There was an error on the request: %s' % (response.data()))\n```\n[source](examples/advanced_usage.py)\n\nFinally, the module exposes `DEBUG` level logging via standard python capabilities. If you are having trouble with the requests, enable debug-level logging with:\n\n```python\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n```\n\n## API Documentation\nFull API documentation for Ignition is available [here](./docs/api.md).\n\n## Developers\n\n\n\nIgnition is no longer accepting contributions. Please feel free to fork this repository.\n\n## License\nIgnition is licensed under [Mozilla Public License 2.0](https://www.mozilla.org/en-US/MPL/).\n\nCopyright 2020-2024 by [Chris Brousseau](https://github.com/cbrews).\n\n## Thank you\n* *solderpunk* for leading the design of the [Gemini protocol](https://geminiprotocol.net/docs/specification.html), without which this project would not have been possible.\n* *Sean Conman* for writing the [Gemini torture tests](gemini://gemini.conman.org/test/torture), which were instrumental in initial client testing.\n* *Michael Lazar* for his work on [Jetforce](https://github.com/michael-lazar/jetforce), which helped testing along the way.\n\n\ud83d\udd2d Happy exploring!\n",
"bugtrack_url": null,
"license": "MPL 2.0",
"summary": "ignition - Gemini Protocol Client Transport Library",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/cbrews/ignition"
},
"split_keywords": [
"client",
" gemini",
" networking",
" request",
" socket"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a5973a5c67b6c46518f2ed63b6637630fa54ecf23d3b247acc997240331c4d50",
"md5": "443967652917c973f32560b6d7e4fff6",
"sha256": "84e67a3f11b374b27fdd6779daeaf8ca81effd96eacdda22397fea16d80ec9ca"
},
"downloads": -1,
"filename": "ignition_gemini-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "443967652917c973f32560b6d7e4fff6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 102601,
"upload_time": "2024-04-20T17:04:36",
"upload_time_iso_8601": "2024-04-20T17:04:36.594920Z",
"url": "https://files.pythonhosted.org/packages/a5/97/3a5c67b6c46518f2ed63b6637630fa54ecf23d3b247acc997240331c4d50/ignition_gemini-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ddc1e20a471e78640857f8fa80ed31d2ffaf6541301fec0ce403717425c87e58",
"md5": "4c98c4f78736c6adcc39c1806409078d",
"sha256": "a3ab2655d921d100b73cd146c050bd089de3e5a18d2f518a2ee934c80333ee1e"
},
"downloads": -1,
"filename": "ignition_gemini-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "4c98c4f78736c6adcc39c1806409078d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 88558,
"upload_time": "2024-04-20T17:04:38",
"upload_time_iso_8601": "2024-04-20T17:04:38.650358Z",
"url": "https://files.pythonhosted.org/packages/dd/c1/e20a471e78640857f8fa80ed31d2ffaf6541301fec0ce403717425c87e58/ignition_gemini-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-20 17:04:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cbrews",
"github_project": "ignition",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "ignition-gemini"
}
JSON
