API documentation

gopher_server.application

class gopher_server.application.Application(handler: <InterfaceClass gopher_server.handlers.IHandler>)

Core of the Gopher server application.

This class is responsible for the basic semantics of the Gopher protocol, including decoding the selector line and encoding the response.

Note

The bytes<->string conversion uses UTF-8, but the Gopher RFC specifies ASCII encoding. Some clients may have issues if you use characters outside the ASCII range.

async dispatch(hostname: str, port: int, selector: bytes) → bytes

Dispatches a request.

This is called by a listener, and in turn calls the Application’s handler. The hostname and port are passed through in a Request object so that handlers which generate a menu can include the right values for local selectors.

gopher_server.handlers

interface gopher_server.handlers.IHandler

Interface for handler classes.

A handler is called by the Application, and is responsible for generating the response to a request (comparable to the view layer in web frameworks).

handle(self, request)

Receives a Request object, and returns the response as either a string (for text responses), bytes (for binary responses), or a Menu object. May also raise NotFound.

class gopher_server.handlers.DirectoryHandler(base_path: str, generate_menus=False)

Serves files from a directory, as specified by base_path.

If the selector matches the name of a directory, this will look for a file called index in that directory and serve that.

Setting the generate_menus argument to True will instead serve an automatically generated menu listing all the files in the directory. This uses the filetype library for type detection, which you can install using the automenu extras:

pip install gopher_server[automenu]

If filetype is not installed then all file entries will have type 0 (text).

class gopher_server.handlers.PatternHandler

Uses regular expression matching to map selectors to view functions.

View functions can be registered by decorating them with the register method. Requests with a selector matching the regex pattern will then call that function. For example:

@handler.register("hello/.+")
def hello(request):
    return "hello %s" % request.selector[6:]

Named capturing groups will be passed to the function as keyword arguments:

@handler.register("hello/(?P<name>.+)")
def hello(request, name):
    return "hello %s" % name

Note

Patterns are compared in the order in which they were registered, so if the selector matches multiple patterns then the one which was registered first will “win”.

register(pattern: str)

Decorator to register a view function.

class gopher_server.handlers.Request(hostname: str, port: int, selector: str)
class gopher_server.handlers.NotFound

gopher_server.listeners

async gopher_server.listeners.tcp_listener(application: gopher_server.application.Application, hostname: str, host: str, port: int)

Basic unencrypted TCP listener.

async gopher_server.listeners.tcp_tls_listener(application: gopher_server.application.Application, hostname: str, host: str, port: int, certificate_path: str, private_key_path: str, password: str = None)

Gopher-over-TLS listener.

async gopher_server.listeners.quic_listener(application: gopher_server.application.Application, hostname: str, host: str, port: int, certificate_path: str, private_key_path: str, password: str = None, quic_configuration_args: dict = None)

Gopher-over-QUIC listener.

quic_listener uses the aioquic library to provide the QUIC connection. To install aioquic you should install gopher_server with the quic extras:

pip install gopher_server[quic]

It uses a QuicConfiguration object to configure the connection, and keyword arguments for this can be passed via the quic_connection_args parameter.

The life-cycle of a QUIC connection is slightly different to a traditional TCP connection due to the use of QUIC streams. Gopher-over-TCP only supports one request per connection, however quic_listener supports one request per stream, allowing clients to re-use the connection by creating a new stream for each request.

gopher_server.menu

class gopher_server.menu.Menu

Convenience class for building menus.

This is a list wrapper which serialises and concatenates any MenuItems, InfoMenuItems and strings contained within.

serialize() → str

Serialise and concatenate the contained items.

class gopher_server.menu.MenuItem(type: str, name: str, selector: str, host: str, port: int)

A menu item of any kind.

serialize() → str

Serialise the menu item to a string.

class gopher_server.menu.InfoMenuItem(name: str)

An information (i) menu item.

This automatically fills the selector, hostname and port columns with dummy values.

serialize() → str

Serialise the menu item to a string.