djblets.integrations.integration¶

Base support for creating service integrations.

class Integration(integration_mgr: IntegrationManager)[source]¶

Bases: object

Base class for an integration.

Integrations are pluggable components that interface the application with a third-party service, notifying the service or triggering actions on certain events, or fetching data from the service. They can be registered by the consuming application or through extensions.

Unlike an extension, an integration can contain multiple configurations active at one time. An example would be when you want multiple, distinct configurations for posting messages to different channels on a chat service.

There’s one Integration instance for each class, and it typically operates by responding to events and communicating with another service, making use of the state stored in one or more BaseIntegrationConfig instances, which it can query. This allows hook registration and other logic to be shared across all configurations of an instance.

Integrations can make use of extension hooks, binding the lifecycle of that hook’s registration to the lifecycle of that particular integration, making it very easy to tie an integration into any part of the application.

integration_id: Optional[str] = None¶

The unique identifier of the integration.

This identifier cannot collide with other integrations, and thus should contain some unique information, such as a vendor name.

If not set, this will default to the full class path for the integration subclass.

name: Optional[StrOrPromise] = None¶

The display name of the integration.

description: Optional[StrOrPromise] = None¶

A short description of this integration, in plain text format.

icon_static_urls: Dict[str, str] = {}¶

Static paths for the integration’s icon.

This is a dictionary that maps icon resolution indicators to URLs or relative static media paths. It must contain a 1x key, and can contain 2x, 3x, and other sizes. For now, only 1x and 2x are used.

Each value must be a URL reachable by the browser, whether an absolute URL or a path relative to the root of the web server.

The base 1x icon itself is expected to be 48x48. The other sizes are expected to be multiples of this size.

If the paths need to be computed (through a call to static() or get_static_url(), it is best to declare this as a method and use cached_property().

Example

def get_icon_urls(self):
    return {
        '1x': self.extension.get_static_url('logo.png'),
        '2x': self.extension.get_static_url('logo@2x.png'),
    }

default_settings: Dict[str, object] = {}¶

Default settings for any configurations on this extension.

If a setting hasn’t been explicitly saved in a configuration, it will use the default from here, if available.

config_form_cls¶

The form class for handling integration configuration.

alias of IntegrationConfigForm

config_template_name: Optional[str] = None¶

The template name used for the configuration page.

__init__(integration_mgr: IntegrationManager) → None[source]¶

Construct the integration.

Implementations of an integration should generally not override this. Instead, they should implement initialize().

Parameters:

integration_mgr (djblets.integrations.manager.IntegrationManager) – The integration manager that manages this integration.

integration_mgr: IntegrationManager¶

The integration manager that’s managing this integration.

hooks: Set[ExtensionHook]¶

The hooks currently registered by the integration.

enabled: bool¶

Whether the extension is currently enabled.

property id: Optional[str][source]¶

The ID of the integration.

This is an alias around integration_id, meant to provide compatibility with an extension’s id attribute.

enable_integration() → None[source]¶

Enable this integration.

This will initialize the integration, if not already enabled, allowing it to listen to signals and register hooks.

disable_integration() → None[source]¶

Disable this integration.

This will shut down the integration, if not already disabled, cleaning up any signal handlers or hooks it registered.

initialize() → None[source]¶

Initialize the integration.

Integration implementation subclasses must override this to provide any initialization needed for the integration, including signal and hook registration.

This should only be called from enable_integration().

shutdown() → None[source]¶

Shut down the integration.

Integration implementation subclasses can override this to perform any cleanup work for the integration. It will be called when shutting down the integration.

By default, this doesn’t do anything. Subclasses do not need to call the parent method.

shutdown_hooks() → None[source]¶

Shut down all the hooks for the integration.

By default, this is called when calling shutdown().

__annotations__ = {'config_form_cls': 'Type[IntegrationConfigForm]', 'config_template_name': 'Optional[str]', 'default_settings': 'Dict[str, object]', 'description': 'Optional[StrOrPromise]', 'enabled': 'bool', 'hooks': 'Set[ExtensionHook]', 'icon_static_urls': 'Dict[str, str]', 'integration_id': 'Optional[str]', 'integration_mgr': 'IntegrationManager', 'name': 'Optional[StrOrPromise]'}¶

get_configs(**filter_kwargs) → Sequence[BaseIntegrationConfig][source]¶

Return configurations matching the given filters.

By default, all enabled configurations will be returned for this integration. This can be filtered down by specifying fields in the model and their values through keyword arguments.

Each set of results for a unique combination of integration class and filter arguments will be cached locally, to speed up further lookups.

Parameters:

**filter_kwargs (dict, optional) – Keyword arguments to filter by. Each must match a field and value on the model.

Returns:

A list of enabled integration configurations matching the query.

Return type:

list of djblets.integrations.models.BaseIntegrationConfig

create_config(save: bool = False, **kwargs) → BaseIntegrationConfig[source]¶

Create a configuration for this integration.

This will create a brand new configuration for this integration, with fields populated by the provided keyword arguments. The object created will be based on the djblets.integrations.manager.IntegrationManager.config_model attribute.

By default, this configuration won’t be automatically saved to the database. The caller can pass save=True to change this behavior. Otherwise, it’s the caller’s responsibility to save the configuration.

Subclasses can override this to provide additional defaults or state.

Parameters:

• save (bool, optional) – Whether to immediately save the new configuration. Defaults to False.

• **kwargs (dict) – Values for fields on the configuration model.

Returns:

The new integration configuration instance.

Return type:

djblets.integrations.models.BaseIntegrationConfig

IntegrationClassType¶

A type alias for an integration class.

New in version 3.3.

alias of Type[Integration]