dotcomboom Pituophis

Pituophis is a Python 3 library for building Gopher clients and servers.


  • Make and send Gopher requests with the Request class
  • URL parsing with pituophis.parse_url()
  • Parse and iterate through Gopher menus with
  • Host Gopher servers on Python 3.7+, accepting requests asynchronously (using the same Request class)
  • Serve directories, files, and gophermaps out of the box from a publish directory ('pub/' by default) with the default handler
  • Use either a custom handler altogether or a handler to use when the default handler encounters a 404 for dynamic functionality

How to Install

At a prompt, run pip3 install pituophis or pip install pituophis depending on your setup. You'll be able to import the package with `import pituophis`.

Server Quick Start

If you want to host a Pituophis-based Gopher server, put this code in a file:

import pituophis
pituophis.serve('', 7070, pub_dir='pub/', tls=False)  # typical Gopher port is 70 is the hostname as advertised to the client, and 7070 is the port. pub/ is the publish directory relative to the script.

Here's a basic alt handler, if you're familiar with Python scripting and would like to add more interactivity to your server:

def alt(request):
    if request.path == '/test':
        return [pituophis.Item(text='test!')]

You can return a list of Item objects, bytes, or text. To use your alt handler, add the argument alt_handler=alt to your serve() like this:

pituophis.serve("", 7070, pub_dir='pub/', alt_handler=alt, tls=False)

Gophermap Editor

Writing a Gophermap, a simplified form of a Gopher menu is pretty easy: just stick a file called gophermap in a folder within your publish directory and use the straight-forward menu syntax. This little webapp can help you get to grips with it (note that this uses jQuery). Copy the Gophermap code into your file.


An interactive demo of Pituophis' client features is provided in the form of TreeGopher, a graphical Gopher client in <250 lines of code. It uses Pituophis, PySimpleGUI, and Pyperclip. It can browse Gopher in a hierarchical structure (similarly to WSGopher32, Cyberdog, and Little Gopher Client), read text files, download and save binary files (writing in chunks using Request().stream(), and running on another thread), recognize URL: links and use search services.

Made with Pituophis

These are my other personal projects that use Pituophis:

  • Gopherlens - HTTP to Gopher proxy
  • Gophew - Gopher crawler and search-enabled server

More places using Pituophis:

If you use Pituophis in your project, contact me and I'd be happy to put it on this page.

XXIIVV Webring