Reference Documentation

Models

Plugin authors implement Proxy Models and decorate them with Class Decorators.

class metagov.core.models.Community(id, slug, readable_name)
Parameters

  • id (AutoField) – Id

  • slug (SlugField) – Slug. Unique slug identifier for the community

  • readable_name (CharField) – Readable name. Human-readable name for the community

get_plugin(plugin_name, community_platform_id=None, id=None)

Get plugin proxy instance

enable_plugin(plugin_name, plugin_config=None)

Enable or update plugin

disable_plugin(plugin_name, community_platform_id=None, id=None)

Disable plugin

perform_action(plugin_name, action_id, parameters=None, jsonschema_validation=True, community_platform_id=None)

Perform an action in the community


class metagov.core.models.Plugin(*args, **kwargs)

Represents an instance of an activated plugin.

Parameters

  • id (AutoField) – Id

  • name (CharField) – Name. Name of the plugin

  • community (ForeignKey to Community) – Community. Community that this plugin instance belongs to

  • config (JSONField) – Config. Configuration for this plugin instance

  • community_platform_id (CharField) – Community platform id. Optional identifier for this instance. If multiple instances are allowed per community, this field must be set to a unique value for each instance.

  • state (OneToOneField to DataStore) – State. Datastore to persist any state

auth_type = 'none'

If this plugin makes authenticated requests to an external platform, this field declares how the authentication occurs (API key or OAUTH). (Optional)

config_schema = {}

JSON schema for the config object. If set, config will be validated against the schema when the plugin is enabled. (Optional)

community_platform_id_key = None

Key on the config that represents a unique community identifier on the platform. If set, this config value will be automatically used as the ‘community_platform_id.’ (Optional)

initialize()

Initialize the plugin. Invoked once, directly after the plugin instance is created.

start_process(process_name, callback_url=None, **kwargs)

Start a new GovernanceProcess

send_event_to_driver(event_type: str, data: dict, initiator: dict)

Send an event to the driver

add_linked_account(*, platform_identifier, external_id=None, custom_data=None, link_type=None, link_quality=None)

Given a platform identifier, creates or updates a linked account. Also creates a metagov id for the user if no external_id is passed in.


class metagov.core.models.GovernanceProcess(*args, **kwargs)

Represents an instance of a governance process.

Parameters

  • id (AutoField) – Id

  • name (CharField) – Name

  • url (CharField) – Url. URL of the vote or process

  • callback_url (CharField) – Callback url. Callback URL to notify when the process is updated

  • status (CharField) – Status

  • plugin (ForeignKey to Plugin) – Plugin. Plugin instance that this process belongs to

  • state (OneToOneField to DataStore) – State. Datastore to persist any internal state

  • errors (JSONField) – Errors. Errors to serialize and send back to driver

  • outcome (JSONField) – Outcome. Outcome to serialize and send back to driver

start(parameters)

(REQUIRED) Start the governance process.

Most implementations of this function will:

  • Make a request to start a governance process in an external system

  • Store any data in outcome that should be returned to the Driver. For example, the URL for a voting process in another system.

  • Store any internal state in state

  • If process was started successfully, set status to pending.

  • If process failed to start, raise an exception of type PluginErrorInternal.

  • Call self.save() to persist changes.

close()

(OPTIONAL) Close the governance process.

Most implementations of this function will:

  • Make a request to close the governance process in an external system

  • If the process was closed successfully, set status to completed and set the outcome.

  • If the process failed to close, set errors or raise an exception of type PluginErrorInternal.

  • Call self.save() to persist changes.

receive_webhook(request)

(OPTIONAL) Receive an incoming webhook from an external system. This is the preferred way to update the process state.

Most implementations of this function will:

  • Check if the webhook request pertains to this process.

  • Update state, status, outcome, and/or errors as needed.

  • Call self.save() to persist changes.

update()

(OPTIONAL) Update the process outcome. This function will be invoked repeatedly from a scheduled task. It’s only necessary to implement this function if you can’t use webhooks to update the process state.

Implementations of this function might:

  • Make a request to get the current status from an external system. OR,

  • Check if a closing condition has has been met. For example, if a voting process should be closed after a specified amount of time.

  • Update state, status, outcome, and/or errors as needed.

  • Call self.save() to persist changes.


Decorators

Add decorators to register classes and functions with metagov core.

Class Decorators

metagov.core.plugin_manager.Registry.plugin(cls)

Use this decorator on a subclass of Plugin to register it as a plugin.

metagov.core.plugin_manager.Registry.governance_process(cls)

Use this decorator on a subclass of GovernanceProcess to register it as a governance process.

Function Decorators

metagov.core.plugin_manager.Registry.action(slug, description, input_schema=None, output_schema=None, is_public=False)

Use this decorator on a method of a registered Plugin to register an action endpoint.

Metagov will expose the decorated function at endpoint /action/<plugin-name>.<slug>

Parameters

  • slug (str) – action slug

  • description (str) – action description

  • input_schema (obj) – jsonschema defining the input parameter object, optional

  • output_schema (obj) – jsonschema defining the response object, optional

metagov.core.plugin_manager.Registry.event_producer_task(event_schemas=[])

Use this decorator on a method of a registered Plugin to register a task that sends Events to the Driver.

metagov.core.plugin_manager.Registry.webhook_receiver(event_schemas=[])

Use this decorator on a method of a registered Plugin to register a webhook receiver. Webhook requests recieved for this plugin instance will be passed to the registered method.