API documentation

This page lists the public clients and lower-level helpers exposed by the atlassian package.

Most scripts should import one of the product clients from atlassian:

from atlassian import Jira, Bitbucket, Confluence

Use atlassian.client.AtlassianAPI directly only when you need to call an endpoint that does not yet have a convenience method.

atlassian.jira module

class atlassian.jira.Jira(url: str, username: str | None = None, password: str | None = None, timeout: int = 60, session: Session | None = None, token: str | None = None, verify: bool | str = True, proxies: dict | None = None)

Bases: AtlassianAPI

Client for Jira REST API operations.

Use this class for issue lookup, issue updates, JQL searches, comments, watchers, transitions, projects, and versions. Responses from read methods are usually nested SimpleNamespace objects; methods that mutate Jira return decoded JSON dictionaries or None for empty responses.

See also

Jira REST API Documentation

add_issue_comment(issue_key: str, content: str | None = None) → dict | None

Add a plain text comment to an issue.

Parameters:

  • issue_key (str) – The key of the issue to add a comment to.

  • content (str, optional) – The content of the comment.

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

add_issue_watcher(issue_key: str, watcher: str) → dict | None

Add a user as an issue watcher.

Parameters:

  • issue_key (str) – The key of the issue to add a watcher to.

  • watcher (str) – The username of the watcher.

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

assign_issue(issue_key: str, assignee: str | None = None) → dict | None

Assign an issue to a user or unassign it.

Parameters:

  • issue_key (str) – The key of the issue to assign.

  • assignee (str, optional) – Username to assign. When omitted, -1 is sent to unassign the issue.

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

create_issue(fields: dict, update: dict | None = None) → dict | None

Create an issue or sub-task from a Jira fields payload.

Parameters:

  • fields (dict) – Jira fields payload. Common required keys are project, summary, and issuetype.

  • update (dict, optional) – Optional Jira update payload, for example to add worklog data while creating the issue.

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

create_sub_task(project_key: str | None = None, parent_issue_key: str | None = None, summary: str | None = None, fix_version: str | None = None, assignee: str | None = None, description: str | None = None, labels: list[str] | None = None, team: str | None = None, issue_type: int = 20) → dict | None

Create a sub-task with the legacy project-specific payload.

Deprecated since version Use: create_issue() instead. create_sub_task() contains hard-coded private custom fields (customfield_13430, customfield_11360) that are not portable across Jira projects and will be removed in a future version.

Parameters:

  • project_key (str) – The key of the project.

  • parent_issue_key (str) – The key of the parent issue.

  • summary (str) – The summary of the issue.

  • fix_version (str) – The fix version of the issue.

  • assignee (str) – The assignee of the issue.

  • description (str) – The description of the issue.

  • labels (list[str], optional) – A list of labels for the issue.

  • team (str, optional) – The team of the issue.

  • issue_type (int, optional) – The issue type ID (default is 20).

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

create_task(project_key: str | None = None, summary: str | None = None, assignee: str | None = None, owner: str | None = None, labels: list[str] | None = None, components: list[str] | None = None, issue_type: int = 10) → dict | None

Create a task with the legacy project-specific payload.

Deprecated since version Use: create_issue() instead. create_task() contains hard-coded private custom fields (customfield_11386) that are not portable across Jira projects and will be removed in a future version.

Parameters:

  • project_key (str) – The key of the project.

  • summary (str) – The summary of the issue.

  • assignee (str) – The assignee of the issue.

  • owner (str) – The owner of the issue.

  • labels (list[str], optional) – A list of labels for the issue.

  • components (list[str], optional) – A list of components for the issue.

  • issue_type (int, optional) – The issue type ID (default is 10).

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

create_version(project_key: str, name: str, description: str | None = None, released: bool = False, start_date: str | None = None, release_date: str | None = None) → dict | None

Create a version in a Jira project.

Parameters:

  • project_key (str) – The key of the project.

  • name (str) – The name of the version.

  • description (str, optional) – An optional description for the version.

  • released (bool, optional) – Whether the version has been released (default False).

  • start_date (str, optional) – The start date in YYYY-MM-DD format (optional).

  • release_date (str, optional) – The release date in YYYY-MM-DD format (optional).

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

delete_issue(issue_key: str) → dict | None

Delete an issue by key.

Parameters:

issue_key (str) – The key of the issue to delete.

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

delete_issue_comment(issue_key: str, comment_id: str) → dict | None

Delete a comment from an issue by comment ID.

Parameters:

  • issue_key (str) – The key of the issue.

  • comment_id (str) – The ID of the comment to delete.

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

Delete an issue link by link ID.

get_dev_status(issue_id: str, app_type: str = 'stash', data_type: str = 'repository') → SimpleNamespace | str | None

Return linked development status for an issue.

Parameters:

  • issue_id (str) – The ID of the issue to get development status for.

  • app_type (str, optional) – The type of application (default is “stash”).

  • data_type (str, optional) – The type of data (default is “repository”).

Returns:

Development status data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_issue_comments(issue_key: str) → SimpleNamespace | str | None

Return comments for an issue.

Parameters:

issue_key (str) – The key of the issue.

Returns:

Comment data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_issue_watchers(issue_key: str) → SimpleNamespace | str | None

Return watchers for an issue.

Parameters:

issue_key (str) – The key of the issue.

Returns:

Watcher data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_project(project_key: str) → SimpleNamespace | str | None

Return a Jira project by project key.

Parameters:

project_key (str) – The key of the project to retrieve.

Returns:

Project data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_project_components(project_id: str) → SimpleNamespace | str | None

Return components configured for a Jira project.

Parameters:

project_id (str) – The ID of the project to get components for.

Returns:

Project components, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_projects() → SimpleNamespace | str | None

Return projects visible to the current user.

Returns:

Project list, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_transitions(issue_id: str) → SimpleNamespace | str | None

Return transitions available for an issue to the current user.

Parameters:

issue_id (str) – The ID of the issue to get transitions for.

Returns:

Transition data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_versions(project_key: str) → SimpleNamespace | str | None

Return versions configured for a Jira project.

Parameters:

project_key (str) – The key of the project.

Returns:

Version data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

issue(issue_key: str) → SimpleNamespace | str | None

Return a Jira issue by key.

Parameters:

issue_key (str) – The key of the issue to retrieve.

Returns:

Issue data with fields accessible through dot notation, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

issue_changelog(issue_key: str) → SimpleNamespace | str | None

Return an issue with changelog data expanded.

Parameters:

issue_key (str) – The key of the issue to retrieve the changelog for.

Returns:

Issue data including changelog and summary fields, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

issue_transition(issue_key: str, transition_id: str | None = None) → dict | None

Move an issue through a Jira workflow transition.

Transition IDs vary by project and workflow. Call get_transitions() first to list the transitions available to the current user, then pass the selected transition ID here.

Parameters:

  • issue_key (str) – The key of the issue to transition.

  • transition_id (str, optional) – The ID of the transition to perform.

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

Link two issues with a Jira issue-link relationship.

Parameters:

  • type_name (str, optional) – The type of the link (e.g., “Dependence”, “Blocking”).

  • inward_issue (str, optional) – The key of the inward issue.

  • outward_issue (str, optional) – The key of the outward issue.

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

jira.link_issue_as(type_name='Dependence', inward_issue="TEST-1", outward_issue='TEST-2')
search_issue_with_jql(jql: str, max_result: int = 1000, fields: list[str] | None = None) → list

Search issues using JQL.

Parameters:

  • jql (str) – The JQL query string.

  • max_result (int, optional) – Page size requested from Jira for each API call.

  • fields (list[str], optional) – List of field names to return for each issue. When None (the default), all fields are returned. Pass an explicit list to restrict the response, for example ["summary", "status", "assignee"].

Returns:

Issues matching the query.

Return type:

list

update_custom_field(issue_key: str, field_id: str, *field_args: object) → dict | None

Update a Jira custom field.

Parameters:

  • issue_key (str) – The key of the issue to update.

  • field_id (str) – The ID of the custom field to update.

  • field_args (tuple) – One value to set directly, or two values to set a nested object such as {"name": "value"}.

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

Raises:

AttributeError – If more than two field_args are provided.

update_field(issue_key: str, field_name: str, add: str | None = None, remove: str | None = None) → dict | None

Add and/or remove named values from an issue field.

Parameters:

  • issue_key (str) – The key of the issue to update.

  • field_name (str) – Jira field name or custom field ID to update.

  • add (str, optional) – Value name to add to the field.

  • remove (str, optional) – Value name to remove from the field.

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

update_issue_comment(issue_key: str, comment_id: str, content: str) → dict | None

Replace the body of an existing issue comment.

Parameters:

  • issue_key (str) – The key of the issue.

  • comment_id (str) – The ID of the comment to update.

  • content (str) – The new content of the comment.

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

update_issue_component(issue_key: str, add_components: list[str] | None = None, remove_components: list[str] | None = None) → dict | None

Add and/or remove components on an issue by component name.

Parameters:

  • issue_key (str) – The key of the issue to update.

  • add_components (list[str], optional) – Component names to add.

  • remove_components (list[str], optional) – Component names to remove.

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

update_issue_description(issue_key: str, new_description: str) → dict | None

Replace an issue description.

Parameters:

  • issue_key (str) – The key of the issue to update.

  • new_description (str) – The new description for the issue.

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

update_issue_label(issue_key: str, add_labels: list[str] | None = None, remove_labels: list[str] | None = None) → dict | None

Add and/or remove labels on an issue.

Parameters:

  • issue_key (str) – The key of the issue to update.

  • add_labels (list[str], optional) – Labels to add to the issue.

  • remove_labels (list[str], optional) – Labels to remove from the issue.

Returns:

Decoded API response, or None when Jira returns no body.

Return type:

dict or None

user(username: str) → SimpleNamespace | str | None

Return Jira user information by username.

Parameters:

username (str) – The username of the user to retrieve.

Returns:

User data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

atlassian.bitbucket module

class atlassian.bitbucket.Bitbucket(url: str, username: str | None = None, password: str | None = None, timeout: int = 60, session: Session | None = None, token: str | None = None, verify: bool | str = True, proxies: dict | None = None)

Bases: AtlassianAPI

Client for Bitbucket Server/Data Center REST API operations.

Use this class for project repositories, branches, commits, pull requests, comments, build status, users, and tags. Methods that list Bitbucket resources automatically follow paginated values responses.

See also

Bitbucket REST API Documentation

add_pull_request_comment(project_key: str, repo_slug: str, pr_id: int, comment: str) → dict | None

Add a general comment to a pull request.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

  • comment (str) – The comment text.

Returns:

Decoded API response, or None when Bitbucket returns no body.

Return type:

dict or None

add_pull_request_inline_comment(project_key: str, repo_slug: str, pr_id: int, comment: str, path: str, line: int, line_type: str = 'CONTEXT', file_type: str = 'TO', src_path: str | None = None) → dict | None

Add an inline comment to a file and line in a pull request diff.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

  • comment (str) – The comment text.

  • path (str) – The path of the file to comment on (relative to the repo root).

  • line (int) – The line number in the file to comment on.

  • line_type (str) – Diff line type: CONTEXT, ADDED, or REMOVED.

  • file_type (str) – Diff side: FROM or TO.

  • src_path (str, optional) – The path of the file in the source commit (for renames).

Returns:

Decoded API response, or None when Bitbucket returns no body.

Return type:

dict or None

convert_comment_to_task(project_key: str, repo_slug: str, pr_id: int, comment: str) → dict | None

Convert a pull request comment into a blocker task.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

  • comment (str) – Comment text to search for.

Returns:

Decoded API response, or None when no matching comment is found or Bitbucket returns no body.

Return type:

dict or None

convert_task_to_comment(project_key: str, repo_slug: str, pr_id: int, comment: str) → dict | None

Convert a blocker task back to a regular pull request comment.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

  • comment (str) – Comment text to search for.

Returns:

Decoded API response, or None when no matching comment is found or Bitbucket returns no body.

Return type:

dict or None

create_branch(project_key: str, repo_slug: str, branch_name: str, start_point: str) → dict | None

Create a branch from an existing branch or commit.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • branch_name (str) – The name of the new branch.

  • start_point (str) – Source branch name or commit hash.

Returns:

Decoded API response, or None when Bitbucket returns no body.

Return type:

dict or None

create_pull_request(project_key: str, repo_slug: str, title: str, from_branch: str, to_branch: str, description: str | None = None, reviewers: list[str] | None = None) → dict | None

Create a pull request.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • title (str) – The title of the pull request.

  • from_branch (str) – The source branch name.

  • to_branch (str) – The destination branch name.

  • description (str, optional) – An optional description for the pull request.

  • reviewers (list[str], optional) – Optional reviewer user slugs.

Returns:

Decoded API response, or None when Bitbucket returns no body.

Return type:

dict or None

create_tag(project_key: str, repo_slug: str, tag_name: str, start_point: str, message: str | None = None) → dict | None

Create a lightweight or annotated tag in a repository.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • tag_name (str) – The name of the tag to create.

  • start_point (str) – The commit SHA or branch name to tag.

  • message (str, optional) – Optional message for an annotated tag.

Returns:

Decoded API response, or None when Bitbucket returns no body.

Return type:

dict or None

decline_pull_request(project_key: str, repo_slug: str, pr_id: int, pr_version: int) → dict | None

Decline a pull request.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

  • pr_version (int) – Current pull request version required by Bitbucket optimistic locking.

Returns:

Decoded API response, or None when Bitbucket returns no body.

Return type:

dict or None

delete_branch(project_key: str, repo_slug: str, branch_name: str, end_point: str) → dict | None

Delete a branch from a repository.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • branch_name (str) – The name of the branch to delete.

  • end_point (str) – Current commit hash for the branch deletion request.

Returns:

Decoded API response, or None when Bitbucket returns no body.

Return type:

dict or None

delete_pull_request_comment(project_key: str, repo_slug: str, pr_id: int, comment: str) → dict | None

Find a pull request comment by exact text and delete it.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

  • comment (str) – The comment text to be deleted.

Returns:

Decoded API response, or None when no matching comment is found or Bitbucket returns no body.

Return type:

dict or None

get_branch_commits(project_key: str, repo_slug: str, branch_name: str, start: int = 0, limit: int | None = None) → list

Return commits reachable from a branch.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • branch_name (str) – The name of the branch.

  • start (int, optional) – The starting index for pagination (optional).

  • limit (int, optional) – The maximum number of results to return (optional).

Returns:

Commit objects from the paginated values response.

Return type:

list

get_branch_committer_info(project_key: str, repo_slug: str, branch_name: str, start: int = 0, limit: int | None = None) → list

Return committers for commits reachable from a branch.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • branch_name (str) – The name of the branch.

  • start (int, optional) – The starting index for pagination (optional).

  • limit (int, optional) – The maximum number of results to return (optional).

Returns:

Committer objects extracted from branch commits.

Return type:

list

get_build_status(commit_id: str) → SimpleNamespace | str | None

Return build status for a commit.

Parameters:

commit_id (str) – The ID of the commit.

Returns:

Build status data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_file_change_history(project_key: str, repo_slug: str, branch_name: str, file_path: str, start: int = 0, limit: int | None = None) → list

Return commit history for a file on a branch.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • branch_name (str) – The name of the branch.

  • file_path (str) – The path of the file.

  • start (int, optional) – The starting index for pagination (optional).

  • limit (int, optional) – The maximum number of results to return (optional).

Returns:

Commit history objects from the paginated values response.

Return type:

list

get_file_content(project_key: str, repo_slug: str, branch_name: str, file_path: str) → SimpleNamespace | str | None

Return raw file content from a branch.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • branch_name (str) – The name of the branch.

  • file_path (str) – The path of the file.

Returns:

Raw file content, parsed JSON if Bitbucket returns JSON, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_merged_branch(project_key: str, repo_slug: str, start: int = 0, limit: int | None = None) → list[str]

Return branch names that Bitbucket marks as merged.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • start (int, optional) – The starting index for pagination (optional).

  • limit (int, optional) – The maximum number of results to return (optional).

Returns:

Merged branch display names.

Return type:

list

get_project_repo(project_key: str, start: int = 0, limit: int | None = None) → list

Return repositories in a Bitbucket project.

Parameters:

  • project_key (str) – The key of the project.

  • start (int, optional) – The starting index for pagination (optional).

  • limit (int, optional) – The maximum number of results to return (optional).

Returns:

Repository objects from the paginated values response.

Return type:

list

get_project_repo_name(project_key: str) → list[str]

Return repository names for a Bitbucket project.

Parameters:

project_key (str) – The key of the project.

Returns:

Repository names.

Return type:

list

get_pull_request(project_key: str, repo_slug: str, pr_state: str = 'ALL', start: int = 0, limit: int | None = None) → list

Return pull requests for a repository.

Common pr_state values include ALL, OPEN, MERGED, and DECLINED. :param project_key: The key of the project. :type project_key: str :param repo_slug: The slug of the repository. :type repo_slug: str :param pr_state: The state of the pull request (default: ALL). :type pr_state: str, optional :param start: The starting index for pagination (optional). :type start: int, optional :param limit: The maximum number of results to return (optional). :type limit: int, optional :return: Pull request objects from the paginated values response. :rtype: list

get_pull_request_activities(project_key: str, repo_slug: str, pr_id: int, start: int = 0, limit: int | None = None) → list

Return activity entries for a pull request.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

  • start (int, optional) – The starting index for pagination (optional).

  • limit (int, optional) – The maximum number of results to return (optional).

Returns:

Activity objects from the paginated values response.

Return type:

list

get_pull_request_comments(project_key: str, repo_slug: str, pr_id: int) → SimpleNamespace | str | None

Return comments for a pull request.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

Returns:

Comment data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_pull_request_commits(project_key: str, repo_slug: str, pr_id: int) → SimpleNamespace | str | None

Return commits in a pull request.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

Returns:

Commit data as a SimpleNamespace, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace | str | None

get_pull_request_destination_branch_name(project_key: str, repo_slug: str, pr_id: int, limit: int = 0) → str | None

Return the destination branch name for a pull request.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

Returns:

Destination branch name, or None when the pull request is not found in the searched pages.

Return type:

str or None

get_pull_request_diff(project_key: str, repo_slug: str, pr_id: int) → SimpleNamespace | str | None

Return the structured diff for a pull request.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

Returns:

Diff data as a SimpleNamespace, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace | str | None

get_pull_request_id(project_key: str, repo_slug: str, pr_state: str = 'OPEN', start: int = 0, limit: int | None = None) → list[int]

Return pull request IDs for a repository and state.

Common pr_state values include OPEN, ALL, MERGED, and DECLINED. :param project_key: The key of the project. :type project_key: str :param repo_slug: The slug of the repository. :type repo_slug: str :param pr_state: The state of the pull request (default: OPEN). :type pr_state: str, optional :param start: The starting index for pagination (optional). :type start: int, optional :param limit: The maximum number of results to return (optional). :type limit: int, optional :return: Pull request IDs. :rtype: list

get_pull_request_jira_key(project_key: str, repo_slug: str, pr_id: int) → str | None

Extract a Jira issue key from a pull request source branch name.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

Returns:

First PROJECT-123 style key in the source branch, or None when no key is found.

Return type:

str or None

get_pull_request_merge(project_key: str, repo_slug: str, pr_id: int) → SimpleNamespace | str | None

Return mergeability information for a pull request.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

Returns:

Merge data as a SimpleNamespace, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace | str | None

get_pull_request_overview(project_key: str, repo_slug: str, pr_id: int) → SimpleNamespace | str | None

Return pull request metadata.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

Returns:

Pull request metadata as a SimpleNamespace, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace | str | None

get_pull_request_patch(project_key: str, repo_slug: str, pr_id: int) → SimpleNamespace | str | None

Return the raw patch for a pull request.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

Returns:

Raw patch text, parsed JSON if Bitbucket returns JSON, or None for an empty body.

Return type:

SimpleNamespace | str | None

get_pull_request_raw_diff(project_key: str, repo_slug: str, pr_id: int) → SimpleNamespace | str | None

Return the raw unified diff for a pull request.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

Returns:

Raw diff text, parsed JSON if Bitbucket returns JSON, or None for an empty body.

Return type:

SimpleNamespace | str | None

get_pull_request_source_branch_name(project_key: str, repo_slug: str, pr_id: int, limit: int = 0) → str | None

Return the source branch name for a pull request.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

Returns:

Source branch name, or None when the pull request is not found in the searched pages.

Return type:

str or None

get_repo_branch(project_key: str, repo_slug: str, start: int = 0, limit: int | None = None) → list

Return branches in a repository.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • start (int, optional) – The starting index for pagination (optional).

  • limit (int, optional) – The maximum number of results to return (optional).

Returns:

Branch objects from the paginated values response.

Return type:

list

get_repo_info(project_key: str, repo_slug: str) → SimpleNamespace | str | None

Return metadata for a repository.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

Returns:

Repository data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_tags(project_key: str, repo_slug: str, start: int = 0, limit: int | None = None) → list

Return tags for a repository.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • start (int, optional) – The starting index for pagination (optional).

  • limit (int, optional) – The maximum number of results to return (optional).

Returns:

Tag objects from the paginated values response.

Return type:

list

get_user(user_slug: str) → SimpleNamespace | str | None

Return Bitbucket user information by user slug.

Parameters:

user_slug (str) – The slug of the user.

Returns:

User data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

merge_pull_request(project_key: str, repo_slug: str, pr_id: int, pr_version: int) → dict | None

Merge a pull request.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

  • pr_version (int) – Current pull request version required by Bitbucket optimistic locking.

Returns:

Decoded API response, or None when Bitbucket returns no body.

Return type:

dict or None

reopen_pull_request_comment(project_key: str, repo_slug: str, pr_id: int, comment: str) → dict | None

Reopen a resolved pull request comment task.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

  • comment (str) – Comment text to search for.

Returns:

Decoded API response, or None when no matching comment is found or Bitbucket returns no body.

Return type:

dict or None

resolve_pull_request_comment(project_key: str, repo_slug: str, pr_id: int, comment: str) → dict | None

Mark a pull request comment task as resolved.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

  • comment (str) – Comment text to search for.

Returns:

Decoded API response, or None when no matching comment is found or Bitbucket returns no body.

Return type:

dict or None

review_pull_request(project_key: str, repo_slug: str, pr_id: int, user_slug: str, status: str = 'APPROVED') → dict | None

Set a user’s review status on a pull request.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

  • user_slug (str) – The slug of the user.

  • status (str, optional) – Review status. Common values are APPROVED, UNAPPROVED, and NEEDS_WORK.

Returns:

Decoded API response, or None when Bitbucket returns no body.

Return type:

dict or None

update_build_status(commit_id: str, build_state: str, data_key: str, build_name: str, build_url: str, description: str = 'ManuallyCheckBuildPass') → dict | None

Create or update Bitbucket build status for a commit.

Parameters:

  • commit_id (str) – The ID of the commit.

  • build_state (str) – Build state, for example SUCCESSFUL or FAILED.

  • data_key (str) – Stable key identifying this build status.

  • build_name (str) – The name of the build.

  • build_url (str) – The URL of the build.

  • description (str) – The description of the build.

Returns:

Decoded API response, or None when Bitbucket returns no body.

Return type:

dict or None

update_pull_request_comment(project_key: str, repo_slug: str, pr_id: int, old_comment: str, new_comment: str) → dict | None

Find a pull request comment by text and replace it.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

  • old_comment (str) – Existing comment text to search for.

  • new_comment (str) – The new comment text.

Returns:

Decoded API response, or None when no matching comment is found or Bitbucket returns no body.

Return type:

dict or None

update_pull_request_description(project_key: str, repo_slug: str, pr_id: int, new_description: str) → dict | None

Replace a pull request description.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

  • new_description (str) – The new description for the pull request.

Returns:

Decoded API response, or None when the pull request cannot be loaded or Bitbucket returns no body.

Return type:

dict or None

update_pull_request_destination(project_key: str, repo_slug: str, pr_id: int, new_destination: str) → dict | None

Change the destination branch of a pull request.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

  • new_destination (str) – The new destination branch for the pull request.

Returns:

Decoded API response, or None when the pull request cannot be loaded or Bitbucket returns no body.

Return type:

dict or None

update_pull_request_reviewers(project_key: str, repo_slug: str, pr_id: int, reviewers: list) → dict | None

Replace the reviewer list for a pull request.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

  • reviewers (list) – Reviewer payload expected by Bitbucket.

Returns:

Decoded API response, or None when the pull request cannot be loaded or Bitbucket returns no body.

Return type:

dict or None

update_pull_request_title(project_key: str, repo_slug: str, pr_id: int, new_title: str) → dict | None

Replace a pull request title.

Parameters:

  • project_key (str) – The key of the project.

  • repo_slug (str) – The slug of the repository.

  • pr_id (int) – The ID of the pull request.

  • new_title (str) – The new title for the pull request.

Returns:

Decoded API response, or None when the pull request cannot be loaded or Bitbucket returns no body.

Return type:

dict or None

atlassian.confluence module

class atlassian.confluence.Confluence(url: str, username: str | None = None, password: str | None = None, timeout: int = 60, session: Session | None = None, token: str | None = None, verify: bool | str = True, proxies: dict | None = None)

Bases: AtlassianAPI

Client for Confluence REST API operations.

Use this class for pages, spaces, content search, child pages, attachments, and labels. Read methods return nested SimpleNamespace objects when the API returns JSON, raw text for non-JSON responses, or None for empty responses.

See also

Confluence REST API Documentation

add_comment(page_id: int, body: str) → dict | None

Add a comment to a page.

Parameters:

  • page_id (int) – The ID of the page to comment on.

  • body (str) – Comment body in Confluence storage format.

Returns:

Decoded API response, or None when Confluence returns no body.

Return type:

dict or None

add_label(page_id: int, label: str) → dict | None

Add a global label to a content item.

Parameters:

  • page_id (int) – The ID of the content.

  • label (str) – The label name to add.

Returns:

Decoded API response, or None when Confluence returns no body.

Return type:

dict or None

create_content(title: str, space_key: str, body_value: str, ancestors_id: int | None = None, type: str = 'page') → dict | None

Create a Confluence page or another content type.

Parameters:

  • title (str) – The title of the content.

  • space_key (str) – The key of the space where the content will be created.

  • body_value (str) – Body content in Confluence storage format.

  • ancestors_id (int, optional) – Parent content ID. When provided, the new page is created as a child of that content.

  • type (str) – Content type, for example page.

Returns:

Decoded API response, or None when Confluence returns no body.

Return type:

dict or None

delete_content(page_id: int) → dict | None

Delete content from Confluence by content ID.

Parameters:

page_id (int) – The ID of the content to delete.

Returns:

Decoded API response, or None when Confluence returns no body.

Return type:

dict or None

get_attachments(page_id: int) → SimpleNamespace | str | None

Return attachments for a page.

Parameters:

page_id (int) – The ID of the page.

Returns:

Attachment data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_child_pages(page_id: int, start: int = 0, limit: int = 25) → SimpleNamespace | str | None

Return child pages for a parent page.

Parameters:

  • page_id (int) – The ID of the parent page.

  • start (int, optional) – The starting index for pagination (default 0).

  • limit (int, optional) – The maximum number of results to return (default 25).

Returns:

Child page data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_comments(page_id: int) → SimpleNamespace | str | None

Return comments for a page.

Parameters:

page_id (int) – The ID of the page.

Returns:

Comment data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_content() → SimpleNamespace | str | None

Return content visible to the current user.

Returns:

Content data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_content_by_id(page_id: int) → SimpleNamespace | str | None

Return content by content ID.

Parameters:

page_id (int) – The ID of the content to retrieve.

Returns:

Content data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_content_by_space(space_key: str, content_type: str = 'page', start: int = 0, limit: int = 25) → SimpleNamespace | str | None

Return pages or blog posts in a Confluence space.

Parameters:

  • space_key (str) – The key of the space.

  • content_type (str, optional) – The type of content to retrieve (“page” or “blogpost”). Defaults to “page”.

  • start (int, optional) – The starting index for pagination (default 0).

  • limit (int, optional) – The maximum number of results to return (default 25).

Returns:

Content list data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_content_history(page_id: int) → SimpleNamespace | str | None

Return version history for a content item.

Parameters:

page_id (int) – The ID of the content to retrieve the history for.

Returns:

History data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_labels(page_id: int) → SimpleNamespace | str | None

Return labels for a content item.

Parameters:

page_id (int) – The ID of the content.

Returns:

Label data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_page_by_title(space_key: str, title: str) → SimpleNamespace | str | None

Return a page by its title within a space.

Parameters:

  • space_key (str) – The key of the space to search in.

  • title (str) – The exact title of the page.

Returns:

Content data for the matching page, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_space(space_key: str) → SimpleNamespace | str | None

Return a Confluence space by space key.

Parameters:

space_key (str) – The key of the space to retrieve.

Returns:

Space data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

get_spaces(start: int = 0, limit: int = 25) → SimpleNamespace | str | None

Return Confluence spaces visible to the current user.

Parameters:

  • start (int, optional) – The starting index for pagination (default 0).

  • limit (int, optional) – The maximum number of spaces to return (default 25).

Returns:

Space data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

remove_label(page_id: int, label: str) → dict | None

Remove a label from a content item.

Parameters:

  • page_id (int) – The ID of the content.

  • label (str) – The label name to remove.

Returns:

Decoded API response, or None when Confluence returns no body.

Return type:

dict or None

search_content(cql: str, start: int = 0, limit: int = 25) → SimpleNamespace | str | None

Search content with Confluence Query Language (CQL).

Parameters:

  • cql (str) – The CQL query string.

  • start (int, optional) – The starting index for pagination (default 0).

  • limit (int, optional) – The maximum number of results to return (default 25).

Returns:

Search result data, raw response text for non-JSON responses, or None for an empty body.

Return type:

SimpleNamespace or str or None

update_content(page_id: int, title: str, body_value: str, type: str = 'page', version: int | None = None) → dict | None

Update an existing Confluence content item.

The Confluence API requires that the version number supplied is exactly the current version incremented by one. When version is not provided this method fetches the current version automatically.

Parameters:

  • page_id (int) – The ID of the content to update.

  • title (str) – The new title of the content.

  • body_value (str) – New body content in Confluence storage format.

  • type (str) – Content type, for example page.

  • version (int, optional) – Version number to submit. When omitted, the current version is retrieved from the API and incremented by one.

Returns:

Decoded API response, or None when Confluence returns no body.

Return type:

dict or None

upload_attachment(page_id: int, filename: str, file_data: bytes, content_type: str = 'application/octet-stream') → dict | None

Upload a file as an attachment to a page.

Parameters:

  • page_id (int) – The ID of the page to attach the file to.

  • filename (str) – The name of the attachment file.

  • file_data (bytes) – The binary content of the file to upload.

  • content_type (str, optional) – The MIME type of the file (default application/octet-stream).

Returns:

Decoded API response, or None when Confluence returns no body.

Return type:

dict or None

atlassian.client module

class atlassian.client.AtlassianAPI(url: str, username: str | None = None, password: str | None = None, timeout: int = 60, session: Session | None = None, token: str | None = None, verify: bool | str = True, proxies: dict | None = None)

Bases: object

Base HTTP client shared by Jira, Bitbucket, and Confluence clients.

The client stores a requests.Session, applies either basic auth or a bearer token, appends endpoint paths to the configured base URL, and raises atlassian.error.APIError for HTTP 4xx and 5xx responses.

get() parses JSON into nested SimpleNamespace objects. Mutating helpers return decoded JSON dictionaries when available.

close() → None

Close the underlying requests.Session.

default_headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
delete(path: str, data: dict | None = None, json: object | None = None, params: dict | None = None) → dict | None

Send a DELETE request.

Parameters:

  • path (str) – Endpoint path appended to the base URL.

  • data (dict or None) – Optional request body data.

  • json (object or None) – JSON payload to send in the request body.

  • params (dict or None) – Query string parameters.

Returns:

Decoded JSON response, or None for empty/non-JSON responses.

Return type:

dict or None

Raises:

APIError – If the response status code is 4xx or 5xx.

get(path: str, data: dict | None = None, params: dict | None = None) → SimpleNamespace | str | None

Send a GET request and parse the response for script-friendly use.

Parameters:

  • path (str) – Endpoint path appended to the base URL.

  • data (dict or None) – Optional request body data.

  • params (dict or None) – Query string parameters.

Returns:

A nested SimpleNamespace for JSON responses, raw text when JSON parsing fails, or None for empty responses.

Return type:

SimpleNamespace or str or None

Raises:

APIError – If the response status code is 4xx or 5xx.

post(path: str, data: dict | None = None, json: object | None = None, params: dict | None = None) → dict | None

Send a POST request.

Parameters:

  • path (str) – Endpoint path appended to the base URL.

  • data (dict or None) – Optional request body data.

  • json (object or None) – JSON payload to send in the request body.

  • params (dict or None) – Query string parameters.

Returns:

Decoded JSON response, or None for empty/non-JSON responses.

Return type:

dict or None

Raises:

APIError – If the response status code is 4xx or 5xx.

put(path: str, data: dict | None = None, json: object | None = None, params: dict | None = None) → dict | None

Send a PUT request.

Parameters:

  • path (str) – Endpoint path appended to the base URL.

  • data (dict or None) – Optional request body data.

  • json (object or None) – JSON payload to send in the request body.

  • params (dict or None) – Query string parameters.

Returns:

Decoded JSON response, or None for empty/non-JSON responses.

Return type:

dict or None

Raises:

APIError – If the response status code is 4xx or 5xx.

request(method: str = 'GET', path: str = '', data: dict | None = None, json: object | None = None, params: dict | None = None) → Response

Send an HTTP request through the configured session.

Parameters:

  • method (str) – The HTTP method (e.g., “GET”, “POST”, “PUT”, “DELETE”).

  • path (str) – Endpoint path appended to self.url. Include the leading slash, for example /rest/api/2/project.

  • data (dict or None) – Form data or bytes to send in the request body.

  • json (object or None) – JSON payload to send in the request body.

  • params (dict or None) – Query string parameters.

Returns:

The HTTP response object.

Return type:

requests.Response

Raises:

APIError – If the response status code is 4xx or 5xx.

atlassian.error module

HTTP error helpers used by the Atlassian clients.

AtlassianAPI.request() raises APIError for HTTP 4xx and 5xx responses. The exception keeps the status code and the response text so callers can log or branch on the failure.

HTTP response code reference: https://developer.atlassian.com/server/confluence/http-response-code-definitions/

exception atlassian.error.APIError(code: int | None = None, message: str | None = None)

Bases: Exception

Exception raised when an Atlassian REST API request fails.

Parameters:

  • code (int, optional) – The HTTP status code of the error.

  • message (str, optional) – Response body or custom error message. If omitted, a default message is selected from the status code.

atlassian.logger module

Logging helpers for the Atlassian clients.

atlassian.logger.get_console_handler()

Create a console log handler that writes to stdout.

Returns:

Configured stream handler.

Return type:

StreamHandler

atlassian.logger.get_file_handler()

Create a rotating file log handler.

The caller is responsible for ensuring that the logs directory exists before attaching this handler.

Returns:

Configured rotating file handler.

Return type:

RotatingFileHandler

atlassian.logger.get_logger(name)

Return a package logger with the project formatter attached.

Parameters:

name (str) – Logger name, usually __name__.

Returns:

Configured logger instance.

Return type:

Logger