Python API v1.0

The interfaces documented here are considered stable. All other interfaces should be considered private to bugwarrior and are subject to change without warning, release notes, or semantic version bumping.

Service API

class bugwarrior.services.Client[source]

Base class for making requests to service API’s.

This class is not strictly necessary but encourages a well-structured service in which the details of making and parsing http requests is compartmentalized.

static json_response(response: Response) → Any[source]

Return json if response is OK.

class bugwarrior.services.Issue[source]

Base class for translating from foreign records to taskwarrior tasks.

The upper case attributes and abstract methods need to be defined by service implementations, while the lower case attributes and concrete methods are provided by the base class.

UDAS: dict

Set to a dictionary mapping UDA short names with type and long name.

Example:

{
    'project_id': {
        'type': 'string',
        'label': 'Project ID',
    },
    'ticket_number': {
        'type': 'number',
        'label': 'Ticket Number',
    },
}

Note: For best results, dictionary keys should be unique!

UNIQUE_KEY: tuple[str, ...]

Should be a tuple of field names (can be UDA names) that are usable for uniquely identifying an issue in the foreign system.

PRIORITY_MAP: dict

Should be a dictionary of value-to-level mappings between the foreign system and the string values ‘H’, ‘M’ or ‘L’.

record

Data retrieved from the external service.

config: ServiceConfig

An object whose attributes are this service’s configuration values.

main_config: MainSectionConfig

An object whose attributes are the Main Section configuration values.

extra

Data computed by the Service class.

abstract to_taskwarrior() → dict[str, Any][source]

Transform a foreign record into a taskwarrior dictionary.

abstract get_default_description() → str[source]

Return a default description for this task.

You should probably use build_default_description() to achieve this.

get_tags_from_labels(
labels: list[str],
toggle_option: str = 'import_labels_as_tags',
template_option: str = 'label_template',
template_variable: str = 'label',
) → list[str][source]

Transform labels into suitable taskwarrior tags, respecting configuration options.

Parameters:

  • labels – Returned from the service.

  • toggle_option – Option which, if false, would not import labels as tags.

  • template_option – Configuration to use as the field template for each label.

  • template_variable – Name to use in the field template context to refer to the label.

get_priority() → Literal['', 'L', 'M', 'H'][source]

Return the priority of this issue, falling back to default_priority configuration.

parse_date(
date: str | None,
timezone: str = 'deprecated',
) → datetime | None[source]

Parse a date string into a datetime object.

If the parsed date does not have a timezone, the UTC timezone is added.

Parameters:

date – A time string parseable by dateutil.parser.parse

build_default_description(
title: str = '',
url: str = '',
number: str | int = '',
cls: str = 'issue',
) → str[source]

Return a default description, respecting configuration options.

Parameters:

  • title – Short description of the task.

  • url – URL to the task on the service.

  • number – Number associated with the task on the service.

  • cls – The abbreviated type of task this is. Preferred options are (‘issue’, ‘pull_request’, ‘merge_request’, ‘todo’, ‘task’, ‘subtask’).

class bugwarrior.services.Service[source]

Base class for fetching issues from the service.

The upper case attributes and abstract methods need to be defined by service implementations, while the lower case attributes and concrete methods are provided by the base class.

API_VERSION: float

Which version of the API does this service implement?

ISSUE_CLASS: type[T_Issue]

Which class should this service instantiate for holding these issues?

CONFIG_SCHEMA: type[ServiceConfig]

Which class defines this service’s configuration options?

config

An object whose attributes are this service’s configuration values.

main_config

An object whose attributes are the Main Section configuration values.

get_secret(key: str, login: str = 'nousername') → str[source]

Get a secret value, potentially from an oracle.

The secret key need not be a password, per se.

Parameters:

  • key – Name of the configuration field of the given secret.

  • login – Username associated with the password in a keyring, if applicable.

get_issue_for_record(
record: dict[str, Any],
extra: dict[str, Any] | None = None,
) → T_Issue[source]

Instantiate and return an issue for the given record.

Parameters:

  • record – Foreign record.

  • extra – Computed data which is not directly from the service.

build_annotations(
annotations: Iterable[tuple[str, str]],
url: str | None = None,
) → list[str][source]

Format annotations, respecting configuration values.

Parameters:

  • annotations – Comments from service.

  • url – Url to prepend to the annotations.

abstract issues() → Iterator[T_Issue][source]

A generator yielding Issue instances representing issues from a remote service.

Each item in the list should be a dict that looks something like this:

{
    "description": "Some description of the issue",
    "project": "some_project",
    "priority": "H",
    "annotations": [
        "This is an annotation",
        "This is another annotation",
    ]
}

The description can be ‘anything’ but must be consistent and unique for issues you’re pulling from a remote service. You can and should use the .description(...) method to help format your descriptions.

The project should be a string and may be anything you like.

The priority should be one of “H”, “M”, or “L”.

abstract static get_keyring_service(
config: ServiceConfig,
) → str[source]

Return the keyring name for this service.

Config API

class bugwarrior.config.BugwarriorData[source]

Local data storage.

This exposes taskwarrior’s data.location configuration value, as well as an interface to the bugwarrior.data file which serves as an arbitrary key-value store.

path

Taskwarrior’s data.location configuration value. If necessary, services can manage their own files here.

get_data() → dict[str, Any][source]

Return all data from the bugwarrior.data file.

get(key: str) → Any[source]

Return a value stored in the bugwarrior.data file.

set(key: str, value: Any) → None[source]

Set a value in the bugwarrior.data file.

class bugwarrior.config.MainSectionConfig[source]

The Main Section configuration, plus computed attributes:

interactive: bool

DEPRECATED

property data: BugwarriorData

Local data storage.

class bugwarrior.config.ServiceConfig[source]

Pydantic base class for service configurations.