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.
-
async
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).
-
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.