This is a tutorial for the Gopher library I wrote called Pituophis, and is current as of version 0.95. While the API is more or less finalized, it may still be subject to change.

Setting up a server

Installing Pituophis

If you haven't already, install Pituophis by running pip3 install pituophis, or the equivalent for your Python 3 setup. You will most likely need Python 3.7 or later, because of its usage of asynchronous socket connections.

The base script

First, you'll need to crack open whatever comfortable environment you have and create a new Python file. Save it to a new directory, and then create a new one named "pub" inside of the same directory.

This is what should go in the file:

import pituophis

pituophis.serve('127.0.0.1', 70, pub_dir='pub/')

For a Gopher server that will serve files from the pub directory, that's it! Pituophis will also send the gophermap file in each directory if it's available. To run the server just save and then start the script. If you're using a port that is below 1024 (as port 70 is) you may need to run it with elevated privileges .

The host, which is 127.0.0.1 in the example, should be changed to whatever host clients will be connecting on. If you're only going to use the server on your machine, it's fine to leave it that, but if you're running it on a private or public IP address or domain name change it to that.

Alt handlers

Pituophis also lets you use an alt handler, a function that will take in requests and then spit out what to send back. If Pituophis, for example, notices that a path does not exist in the publish directory, it will hand off the request to the alt handler.

To use an alt handler, first define it and set it to be used:

import pituophis

def alt(request):
    return False

pituophis.serve('127.0.0.1', 70, pub_dir='pub/', alt_handler=alt)

The alt handler can return False if it can't do anything with the request, so Pituophis will send back an error as usual.

This example uses the alt handler to send back a menu displaying the request's attributes and a couple selectors:

import pituophis

def alt(request):
    if (request.path == '/stats'):
        menu = [
            pituophis.Selector(text="Path: " + request.path),
            pituophis.Selector(text="Query: " + request.query),
            pituophis.Selector(text="Host: " + request.host),
            pituophis.Selector(text="Port: " + str(request.port)),
            pituophis.Selector(text="Client: " + request.client),
            pituophis.Selector(),
            pituophis.Selector(itype="I", text="View server.png", path="/server.png", host=request.host, port=request.port),
            pituophis.Selector(itype="0", text="View some text", path="/txt", host=request.host, port=request.port)
        ]
        return menu
    return False

pituophis.serve('127.0.0.1', 70, pub_dir='pub/', alt_handler=alt)

Remember, if a directory or file called stats exists in the publish directory, the alt handler will not run, and that static file will be sent instead.