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

GmCapsule

Navigation

Related Topics