API reference

These classes and functions are available to extension modules by importing gmcapsule.

Config(config_path)

Server configuration.

Capsule(cfg)

Server instance.

Cache()

Response cache base class.

gemini.Request([identity, scheme, hostname, ...])

Request received from a client.

gemini.Identity(cert)

Client certificate.

Classes

Config

class gmcapsule.Config(config_path)

Server configuration.

Parameters

config_path (str) – Path of a config INI file to load.

ini

Contents of the config INI file. Extension modules can use this to access additional custom config parameters. See configparser for details.

Type

configparser.ConfigParser

hostnames()
Returns

All the configured hostnames. The first listed hostname is considered the default to be used when a hostname is not otherwise specified.

Return type

list(str)

port()
Returns

Listening IP port of the server.

Return type

int

prefixed_sections(prefix)

Find all sections in the config INI file whose name begins with the given prefix.

Parameters

prefix (str) – Name prefix, e.g., cgi..

Returns

Mapping of section names (with the prefix removed) to the corresponding INI sections (configparser.SectionProxy). An empty dictionary is returned if there are no sections matching the prefix.

Return type

dict

root_dir()
Returns

Content root directory for serving static files. The hostname is always automatically appended to this as a subdirectory.

Return type

pathlib.Path

section(name)

Find a section in the config INI file.

Parameters

name (str) – Name of the section.

Returns

INI section.

Return type

configparser.SectionProxy

Raises

KeyError – The section was not found.

Capsule

class gmcapsule.Capsule(cfg)

Server instance.

The server is initialized as specified in the configuration. Extension modules are loaded and initialized.

After constructing and setting up Capsule, call the run() method to begin accepting incoming connections.

Parameters

cfg (Config) – Server configuration.

add(path, entrypoint, hostname=None, protocol='gemini')

Register a URL entry point.

Extension modules must call this to become visible in the server’s path hierarchy. Entry points are looked up in the order the modules were loaded, with earlier modules getting precedence.

Parameters
  • path (str) – URL path. Must begin with a slash (/). Asterisk wildcards (*) are supported. Note that if the path /* is registered, it will match any requested URL.

  • entrypoint (callable) – Function or other callable object that gets called when a request is processed with a matching URL path. A Request is passed in as the only argument.

  • hostname (str) – Hostname for the entry point. If omitted, the entry point applies to all configured hostnames.

  • protocol (str) – Protocol for the entry point.

add_cache(cache)

Install a cache.

All installed caches will attempt to save and load content until one succeeds. The caches installed first get precedence.

Parameters

cache (Cache) – Cache instance.

static config()
Returns

Server configuration.

Return type

Config

run()

Start worker threads and begin accepting incoming connections. The server will run until stopped with a KeyboardInterrupt (^C).

Cache

class gmcapsule.Cache

Response cache base class.

Derived classes are expected to override the save() and try_load() methods to save and load response content as appropriate.

The server will not try to load or save cached content when a request includes a query string or a client certificate is provided. When multiple Cache objects have been installed, the save/load operation is attempted on each in turn until one cache succeeds in saving or loading content.

The mapping from URLs to cache paths is:

gemini://example.com/path/file.gmi
 ↓
/example.com/path/file.gmi
save(path, media_type, content)

Save content to the cache.

Parameters
  • path (str) – URL path being loaded with the hostname prepended as the top-level directory.

  • media_type (str) – MIME type, e.g., “text/plain”.

  • content (bytes) – Content to save.

Returns

True if successfully saved.

Return type

bool

try_load(path)

Load content from the cache.

Parameters

path (str) – URL path being loaded with the hostname prepended as the top-level directory.

Returns

Content MIME type and data. Returns (None, None) if nothing is cached for the given path.

Return type

tuple(str, bytes)

Request

class gmcapsule.gemini.Request(identity=None, scheme='gemini', hostname='', path='', query='', remote_address=None, content_token=None, content_mime=None, content=None)

Request received from a client.

Request objects are used to pass information to entry points handlers. One does not need to construct them directly.

remote_address

IP address of the client.

Type

str

scheme

Request protocol scheme. Either gemini or titan.

Type

str

identity

Client certificate. May be None.

Type

gmcapsule.gemini.Identity

hostname

Hostname.

Type

str

path

URL path. Always begins with a /.

Type

str

query

Encoded query string. You can use urllib.parse.unquote() to decode the percent-coding.

Type

str

content_token

Encoded token specified in Titan URLs. May be None.

Type

str

content_mime

MIME type specified in Titan URls. May be None.

Type

str

content

Content uploaded by the client in a Titan request. May be None.

Type

bytes

Identity

class gmcapsule.gemini.Identity(cert)

Client certificate.

Functions

gmcapsule.get_mime_type(path)

Determine the MIME type of a file. A handful of common file extensions are detected as special cases, such as “.gmi” and “.txt”. Other files are detected with Python’s mimetypes standard library module, and as a final fallback, the file command line utility.

Parameters

path (str) – File path.

Returns

Detected MIME type, for example, “image/jpeg”. Returns “application/octet-stream” if the correct type could not be determined.

Return type

str

gmcapsule.markdown_to_gemini(src)

Convert a Markdown document to Gemtext. Only basic Markdown features are supported, such as headings, unordered and ordered lists (without changing any numbering present in the source), blockquotes, and paragraph and line breaks.

Parameters

src (str) – Markdown source text.

Returns

Corresponding text/gemini source.

Return type

str