https://github.com/cbrews/ignition
Gemini Protocol Client for Python Developers
https://github.com/cbrews/ignition
client gemini gemini-protocol libraries library python python3
Last synced: 6 months ago
JSON representation
Gemini Protocol Client for Python Developers
- Host: GitHub
- URL: https://github.com/cbrews/ignition
- Owner: cbrews
- License: mpl-2.0
- Archived: true
- Created: 2020-11-09T04:37:13.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-04-20T17:03:00.000Z (about 2 years ago)
- Last Synced: 2025-04-11T13:10:41.794Z (about 1 year ago)
- Topics: client, gemini, gemini-protocol, libraries, library, python, python3
- Language: Python
- Homepage:
- Size: 484 KB
- Stars: 35
- Watchers: 1
- Forks: 5
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-gemini - ignition - Gemini client transport/request library for python3. (Programming / Graphical)
README
# 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!