Plugin API

The following documents a draft API to be implemented by plugins. These functions will be called by the reference checker. While plugins may keep state internally, it is expected that any state they do keep is not required to be persistent.

DocumentIdentifier(doctype, subject, datetime, digests):

Represents a document that is expected to exist.

Attributes:

doctype

The type of the document.

subject

The subject of the document. This is usually a string containing an opaque identifier. Examples include the fingerprint of a relay for a server descriptor, or the hostname of an OnionPerf vantage point.

datetime

A datetime related to the document. The exact meaning of this will be document dependent. Example include the published time for a server descriptor, or the valid-after time for a network status consensus.

digests

A dict containing mappings of DigestHash to tuple`s. Each tuple contains a :py:class:`str representation of the digest and a stem.descriptor.DigestEncoding.

class ExamplePlugin

expectations()

Returns

A list of DocumentIdentifier for documents that are expected to be available for fetching.

fetch(docid)

Fetches a document from a remote location.

Parameters

docid (DocumentIdentifier) – Identifier for the document to be fetched.

parse(document)

Parses a retrieved document for any documents that are referenced and should be fetched.

Parameters

document (DocumentIdentifier) – A retrieved document.

Returns

A list of DocumentIdentifier for documents that are expected to be available for fetching.