atlassian-python-api Documentation

When choosing between Cloud and Server implementations, note the following technical differences in how the API behaves and how resources are identified:

The Bitbucket Cloud module provides an object-oriented interface for navigating the hierarchy: workspaces -> projects -> repositories -> deployment_environments/issues/pipelines.

Common patterns:

• Navigation: Use .get(slug_or_key) to drill down into specific resources.
• Iteration: Use .each() to retrieve lists of resources (e.g., workplace.projects.each()).
• Resource Management: Once you have a resource object (like a repository), you can access its sub-resources directly (e.g., repository.hooks.each()).

Install the library using pip to begin using the Atlassian Python API wrappers.

pip install atlassian-python-api

You can install the library from PyPI using pip, or install it from source.

From PyPI:

$ pip install atlassian-python-api

From Source:

1. Git clone the repository.
2. Install required packages using:

   pip install -r requirements.txt

   or using pipenv:

   pipenv install && pipenv install --dev

For services supporting OAuth, pass an oauth_dict containing the necessary credentials to the constructor. The dictionary must include access_token, access_token_secret, consumer_key, and key_cert.

oauth_dict = {
    'access_token': 'access_token',
    'access_token_secret': 'access_token_secret',
    'consumer_key': 'consumer_key',
    'key_cert': 'key_cert'}

jira = Jira(
    url='http://localhost:8080',
    oauth=oauth_dict)

confluence = Confluence(
    url='http://localhost:8090',
    oauth=oauth_dict)

bitbucket = Bitbucket(
    url='http://localhost:7990',
    oauth=oauth_dict)

service_desk = ServiceDesk(
    url='http://localhost:8080',
    oauth=oauth_dict)

xray = Xray(
    url='http://localhost:8080',
    oauth=oauth_dict)

You can install the library directly from the GitHub repository using pip to test the latest development version.

python3 -m pip install git+https://github.com/atlassian-api/atlassian-python-api.git

When using Tempo Cloud, you can specify a regional endpoint depending on your data residency requirements. Use the url parameter in the TempoCloud constructor to select your region:

• Europe: https://api.eu.tempo.io
• Americas: https://api.us.tempo.io
• Global: https://api.tempo.io

# For European clients
tempo_eu = TempoCloud(
    url="https://api.eu.tempo.io",
    token="your-tempo-api-token"
)

# For American clients
tempo_us = TempoCloud(
    url="https://api.us.tempo.io",
    token="your-tempo-api-token"
)

To use OAuth 2.0 with Bitbucket Cloud, use the atlassian.bitbucket.Cloud class. The oauth2 parameter expects a dictionary containing client_id and a token dictionary. The token dictionary must contain at least access_token and token_type.

from atlassian.bitbucket import Cloud

# token is a dictionary and must at least contain "access_token"
# and "token_type".
oauth2_dict = {
    "client_id": client_id,
    "token": token}

bitbucket_cloud = Cloud(
    oauth2=oauth2_dict)

The Tempo clients include error handling for common HTTP status codes. You can catch exceptions and inspect the error message to handle specific failure scenarios like authentication issues, permission denials, or rate limiting.

try:
    accounts = tempo.get_accounts()
except Exception as e:
    if "401" in str(e):
        print("Authentication failed. Check your API token.")
    elif "403" in str(e):
        print("Access denied. Check your permissions.")
    elif "404" in str(e):
        print("Resource not found.")
    elif "429" in str(e):
        print("Rate limited. Wait before retrying.")
    else:
        print(f"Unexpected error: {e}")

To help reviewers and log-viewers, all commit headers must include a relevant Service Name prefix in brackets.

Correct Examples:

• [Jira] Issues Move to Sprint
• [Confluence] update_page_property method
• Jira: review user module (Note: Brackets are preferred for consistency)

Incorrect Example:

• Addition of parameters for start & limit in the function of get_all_project_issues (This lacks a service prefix and is too verbose for a header).

[Jira] Project Issues parameter addition for start and limit