Package: gemeaux
Gemeaux: a Python Gemini ServerTheGemini protocolis an ongoing initiative to build a clutter-free content-focused Internet browsing,à laGopher, but modernized. It focuses on Privacy (TLS + no user tracking) and eliminates the fluff around the modern web: cookies, ads, overweight Javascript apps, browser incompatibilities, etc.It has been designed for enabling a developer to build a client or a server within a few hours of work. I have been able to serve Gemini static content after two afternoons, so I guess I'm an average developer. But after that, I've tried to improve it, make it more flexible and extensible.So, here it is: theGemeauxserver.IMPORTANT NOTE: since this project is still in its earliest stages, it's worth saying that this softwareIS DEFINITELY NOT READY FOR PRODUCTION— and would probably never will ;o).ClientsA quick word about Gemini protocol. Since it's a different protocol from HTTP, or Gopher, or FTP, etc., it means that you'll have to drop your beloved Web Browser to access Gemini content. Hopefully, several clients are available.A list of clients on the canonical Gemini SpaceA curated list of clients on "awesome Gemini"Download and install a couple of clients, pick one that fits your needs, or if you feel like it, build one yourself, and you'll be ready to spacewalk the Gemini ecosystem.For development purposes, I'd recommendbollux, a browser made for bash, because it displays helpful debug messages (and it's as fast as you can dream).RequirementsGemeauxis built aroundthe standard Python 3.6+ libraryand syntax. There areno external dependencies.Automated tests are launched using Python 3.6, 3.7 and 3.8, so the internals ofGemeauxare safe with these versions of Python.You'll also needopensslto generate certificates.QuickstartInstall via PyPITo install the latest release ofgemeauxpackage, inside a virtualenv, or in a safe environment, run the following:pipinstallgemeauxDeveloper modegitclonehttps://github.com/brunobord/gemeaux.git# You may also want to use this source: git@github.com:brunobord/gemeaux.gitcdgemeaux/
pipinstall-e.Generate certificatesSince TLS is mandatory, you'll have to generate your own SSL certificate files. Use the following command to generate self-signed certificate files, targeting a localhost/developer mode:makecertThis command will generate two files:cert.pemandkey.pem.Again, this will probably not be safe for production.UsageThe "hello world" of thisproof of conceptwould be to serve a directory containing anindex.gmifile.For example, theindex.gmican look like this:# Hello World!

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.Then you'll create a python file (e.g.:app.py) containing the following:fromgemeauximportApp,StaticHandlerif__name__=="__main__":urls={"":StaticHandler(static_dir="path/to/your/directory/"),}app=App(urls)app.run()Note: Thestatic_dirargument can be a relative or an absolute path.Then you'll run your program using Python 3+:pythonapp.pyYou can then point your client atgemini://localhost/and you'll see the content of your home page.By default, the application will listen at port1965on yourlocalhost(127.0.0.1) host, and will use the previously generatedcert.pemandkey.pemfiles.In order to open your server to "the world", you can change the--ipoption like this:pythonapp.py--ip0.0.0.0BIG WARNING: opening your server to external connections isDEFINITELY NOT A GOOD IDEA, since this softwareIS NOT PRODUCTION-READY.You can change the default configuration values using the optional arguments. For more details, run:pythonapp.py--helpAdvanced usageTheurlsconfiguration is at the core of the application workflow. By combining the availableHandlerandResponseclasses, you have the ability to create more complex Gemini spaces.You may read the example application, in theexample_app.pyfile if you want to see an advanced usage of handlers & responses.Several classes are provided in this library:HandlersMost of the time, when working withHandlerbasic classes, you'll have to implement/override two methods:Handler.__init__(*args, **kwargs): The class constructor will acceptargsandkwargsfor providing parameters.Handler.get_response(*args, *kwargs): Based on the parameters and your current context, you would generate a Gemini-compatible response, either based on theResponseclasses provided, or ones you can build yourself.StaticHandlerThis handler is used for serving a static directory and its subdirectories.How to instantiate:StaticHandler(static_dir,directory_listing=True,index_file="index.gmi")static_dir: the path (relative to your program or absolute) of the root directory to serve.directory_listing(default:True): if set toTrue, in case there's no "index file" in a directory, the application will display the directory listing. If set toFalse, and if there's still no index file in this directory, it'll return aNotFoundResponseto the client.index_file(default:"index.gmi"): when the client tries to reach a directory, it's this filename that would be searched to be rendered as the "homepage".Note: If your client is trying to reach a subdirectory like this:gemini://localhost/subdirectory(without the trailing slash), the client will receive a Redirection Response targettinggemini://localhost/subdirectory/(with the trailing slash).TemplateHandlerThis handler provides methods to render Gemini content, mixing a text template and context variables.The constructor has no specific arguments, but accepts*argsand**kwargs. You'll have to overwrite/override two methods in order to correctly mix the template content with the context variables.To retrieve the template file, you can overwrite/override theget_template_file()method:TemplateHandler.get_template_file()Alternatively, you may assign it a statictemplate_fileattribute, like this:classMyTemplateHandler(TemplateHandler):template_file="/path/to/template.txt"The template file name doesn't require a specific file extension. By default,TemplateHandlerinstances will use thestring.Templatemodule from the standard libraryto render content.Note: we know that this "template engine" is a bit too minimalist for advanced purposes ; but as this project mantra is "no external dependencies". Still, this project is a Python project ; so you can plug your favorite template engine and serve dynamic content the way you want.Example template:I am a template file. Refresh me to see what time it is: $datetimeTo generate your context variable(s), you'll have to overwrite/override theget_context()method:classDatetimeTemplateHandler(TemplateHandler):template_file="/path/to/template.txt"defget_context(self,*args,**kwargs):return{"datetime":datetime.datetime.now()}Thisget_context()method should return a dictionary. When accessed, the$datetimevariable will be replaced by its value from the context dictionary.Known bugs & limitationsThis project is mostly for education purposes, although it can possibly be used through a local network, serving Gemini content. There are important steps & bugs to fix before becoming a more solid alternative to other Gemini server software.The internals ofGemeauxare being tested on Python3.6+, but not the mainloop mechanics.The vast majority of Gemini Standard responses are not implemented.The Response documentation is missing, along with docstrings.Performances are probably very low, there might be room for optimisation.What's in the name?"Gémeaux"is the French word for"Gemini". And incidentally, I was born a Gemini.Disclaimer: I don't believe in astrology.Other projectsJetforceis a Python-based Gemini server, using the Twisted framework.GeGoBiuses a single Python file ; it's a dual-protocol server, for both Gopher & Gemini.LicenseGemeauxserver is distributed as Free Software under the terms of the MIT License. See the contents of theLICENSEfile for more details.