Package: ignition-gemini
Ignition: Python3 Gemini Protocol Client Transport LibraryIgnition is a simple but powerful transport library for Python3 clients using the recently designedGemini protocol. This project intends to implement all of thetransport specifications(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 thatrequestsis for HTTP andgopherlibis 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 StatusIgnition is currently in prerelease.  You can use Ignition today at your own risk, please monitor this repository for changes until version 1.0 is released.  Please be advised that there may be breaking changes in the API until that time.You can see ignition in action atgemini.cbrews.xyz.Installation⚠ Ignition currently supports Python versions 3.7 - 3.11.Ignition can be installed viaPIP.  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 avirtual environmentpipinstallignition-geminiIf you prefer to install from source, you can clone and install the repository:gitclonehttps://github.com/cbrews/ignition.gitcdignition
pipinstall.Simple UsageThe most basic usage of Ignition allows the user to create a request and get a response back from a remote Gemini capsule:importignition# Fetch capsule contentresponse=ignition.request('//geminiprotocol.net')# Get status from remote capsuleprint(response.status)# Get response information from remote capsuleprint(response.data())sourceInallcases, 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 currently 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 perRFC-3986Optional 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 willnotbe 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.⚠ These features are not currently supported but may be supported in the future:Non-verified certificate schemeImproved TOFU scenariosAdvanced UsageMore advanced request usage:importignitionresponse=ignition.request('/software',referer='//geminiprotocol.net:1965')print("Got back response%sfrom%s"%(response.status,response.url))# Got back a response 20 from gemini://geminiprotocol.net/softwareifnotresponse.success():print("There was an error on the response.")else:print(response.data())Passing a referer:importignitionresponse1=ignition.request('//geminiprotocol.net')response2=ignition.request('software',referer=response1.url)print(response2)sourceMore advanced response validation:importignitionurl='//geminiprotocol.net'response=ignition.request(url)ifresponse.is_a(ignition.SuccessResponse):print('Success!')print(response.data())elifresponse.is_a(ignition.InputResponse):print('Needs additional input:%s'%(response.data()))elifresponse.is_a(ignition.RedirectResponse):print('Received response, redirect to:%s'%(response.data()))elifresponse.is_a(ignition.TempFailureResponse):print('Error from server:%s'%(response.data()))elifresponse.is_a(ignition.PermFailureResponse):print('Error from server:%s'%(response.data()))elifresponse.is_a(ignition.ClientCertRequiredResponse):print('Client certificate required.%s'%(response.data()))elifresponse.is_a(ignition.ErrorResponse):print('There was an error on the request:%s'%(response.data()))sourceFinally, the module exposesDEBUGlevel logging via standard python capabilities.  If you are having trouble with the requests, enable debug-level logging with:importlogginglogging.basicConfig(level=logging.DEBUG)API DocumentationFull API documentation for Ignition is availablehere.DevelopersWant to help contribute to Ignition?  See thedeveloper documentationfor contribution guidelines, build processes, and testing.The developer documentation is still being completed, if you have specific questions, please open tickets within this project.LicenseIgnition is licensed underMozilla Public License 2.0.Copyright 2020-2022 byChris Brousseau.Thank yousolderpunkfor leading the design of theGemini protocol, without which this project would not have been possible.Sean Conmanfor writing theGemini torture tests, which were instrumental in initial client testing.Michael Lazarfor his work onJetforce, which helped testing along the way.🔭 Happy exploring!