tessl/pypi-atlassian-python-api
Python Atlassian REST API Wrapper providing comprehensive access to Jira, Confluence, Bitbucket, and other Atlassian products
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
bitbucket.mddocs/
Bitbucket API
Comprehensive Bitbucket REST API client providing access to repository management, pull requests, user administration, and project operations. Supports both Bitbucket Cloud and Server/Data Center platforms with 150+ public methods covering the complete Git repository lifecycle.
Initialization
class Bitbucket(AtlassianRestAPI):
def __init__(self, url: str, username: str = None, password: str = None,
token: str = None, cloud: bool = None, **kwargs):
"""
Initialize Bitbucket client.
Parameters:
- url (str): Base URL of Bitbucket instance
- username (str, optional): Username for authentication
- password (str, optional): Password or app password
- token (str, optional): Bearer token for authentication
- cloud (bool, optional): True for Cloud, False for Server/DC
"""Capabilities
Repository Management
Core functionality for creating, managing, and configuring Git repositories with comprehensive metadata and settings control.
def get_repositories(self, project_key: Optional[str] = None, start: int = 0,
limit: int = 25) -> T_resp_json:
"""
Get repositories, optionally filtered by project.
Parameters:
- project_key: Filter by project key
- start: Starting index for pagination
- limit: Maximum results to return
Returns:
dict: Repository list with metadata
"""
def get_repository(self, project_key: str, repository_slug: str) -> T_resp_json:
"""
Get repository details.
Parameters:
- project_key: Project key
- repository_slug: Repository slug/name
Returns:
dict: Repository information with clone URLs and settings
"""
def create_repository(self, project_key: str, repository_name: str,
scm_id: str = "git", forkable: bool = True,
public: bool = False) -> T_resp_json:
"""
Create new repository.
Parameters:
- project_key: Project key where repository will be created
- repository_name: Repository name
- scm_id: SCM type (default "git")
- forkable: Allow forking
- public: Make repository public
Returns:
dict: Created repository data with clone URLs
"""
def delete_repository(self, project_key: str, repository_slug: str) -> bool:
"""
Delete repository.
Parameters:
- project_key: Project key
- repository_slug: Repository slug
Returns:
bool: True if deletion successful
"""
def fork_repository(self, project_key: str, repository_slug: str,
new_project_key: str, new_repository_name: str) -> T_resp_json:
"""
Fork repository to another project.
Parameters:
- project_key: Source project key
- repository_slug: Source repository slug
- new_project_key: Target project key
- new_repository_name: New repository name
Returns:
dict: Forked repository data
"""Branch Management
def get_branches(self, project_key: str, repository_slug: str,
base: Optional[str] = None, details: bool = True,
filter_text: Optional[str] = None, start: int = 0,
limit: int = 25) -> T_resp_json:
"""
Get repository branches.
Parameters:
- project_key: Project key
- repository_slug: Repository slug
- base: Base branch for comparison
- details: Include detailed branch information
- filter_text: Filter branches by text
- start: Starting index
- limit: Maximum results
Returns:
dict: Branches list with commit info
"""
def create_branch(self, project_key: str, repository_slug: str,
name: str, start_point: str, message: Optional[str] = None) -> T_resp_json:
"""
Create new branch.
Parameters:
- project_key: Project key
- repository_slug: Repository slug
- name: New branch name
- start_point: Starting commit hash or branch name
- message: Commit message for branch creation
Returns:
dict: Created branch information
"""
def delete_branch(self, project_key: str, repository_slug: str,
name: str, end_point: str) -> bool:
"""
Delete branch.
Parameters:
- project_key: Project key
- repository_slug: Repository slug
- name: Branch name to delete
- end_point: End point commit hash
Returns:
bool: True if deletion successful
"""
def set_default_branch(self, project_key: str, repository_slug: str,
ref: str) -> T_resp_json:
"""
Set default branch.
Parameters:
- project_key: Project key
- repository_slug: Repository slug
- ref: Branch reference to set as default
Returns:
dict: Updated default branch information
"""Pull Request Management
def get_pull_requests(self, project_key: str, repository_slug: str,
state: str = "OPEN", order: str = "NEWEST",
start: int = 0, limit: int = 25) -> T_resp_json:
"""
Get pull requests.
Parameters:
- project_key: Project key
- repository_slug: Repository slug
- state: PR state ("OPEN", "MERGED", "DECLINED", "ALL")
- order: Sort order ("NEWEST", "OLDEST")
- start: Starting index
- limit: Maximum results
Returns:
dict: Pull requests list with details
"""
def get_pull_request(self, project_key: str, repository_slug: str,
pull_request_id: int) -> T_resp_json:
"""
Get pull request details.
Parameters:
- project_key: Project key
- repository_slug: Repository slug
- pull_request_id: Pull request ID
Returns:
dict: Pull request information with participants and reviewers
"""
def create_pull_request(self, project_key: str, repository_slug: str,
title: str, description: str, from_ref: str,
to_ref: str, reviewers: Optional[List[str]] = None) -> T_resp_json:
"""
Create pull request.
Parameters:
- project_key: Project key
- repository_slug: Repository slug
- title: Pull request title
- description: Pull request description
- from_ref: Source branch reference
- to_ref: Target branch reference
- reviewers: List of reviewer usernames
Returns:
dict: Created pull request data
"""
def update_pull_request(self, project_key: str, repository_slug: str,
pull_request_id: int, title: str, description: str,
version: int) -> T_resp_json:
"""
Update pull request.
Parameters:
- project_key: Project key
- repository_slug: Repository slug
- pull_request_id: Pull request ID
- title: New title
- description: New description
- version: Current version (for optimistic locking)
Returns:
dict: Updated pull request data
"""
def merge_pull_request(self, project_key: str, repository_slug: str,
pull_request_id: int, version: int) -> T_resp_json:
"""
Merge pull request.
Parameters:
- project_key: Project key
- repository_slug: Repository slug
- pull_request_id: Pull request ID
- version: Current version
Returns:
dict: Merge result information
"""
def decline_pull_request(self, project_key: str, repository_slug: str,
pull_request_id: int, version: int) -> T_resp_json:
"""
Decline pull request.
Parameters:
- project_key: Project key
- repository_slug: Repository slug
- pull_request_id: Pull request ID
- version: Current version
Returns:
dict: Declined pull request data
"""User and Group Management
def get_users(self, filter_text: Optional[str] = None, start: int = 0,
limit: int = 25) -> T_resp_json:
"""
Get users.
Parameters:
- filter_text: Filter users by text
- start: Starting index
- limit: Maximum results
Returns:
dict: Users list with profile information
"""
def get_user(self, username: str) -> T_resp_json:
"""
Get user details.
Parameters:
- username: Username to retrieve
Returns:
dict: User profile information
"""
def create_user(self, username: str, password: str, display_name: str,
email_address: str) -> T_resp_json:
"""
Create user (Server/DC only).
Parameters:
- username: Unique username
- password: User password
- display_name: Display name
- email_address: Email address
Returns:
dict: Created user data
"""
def get_groups(self, filter_text: Optional[str] = None, start: int = 0,
limit: int = 25) -> T_resp_json:
"""
Get groups.
Parameters:
- filter_text: Filter groups by text
- start: Starting index
- limit: Maximum results
Returns:
dict: Groups list
"""
def group_members(self, group_name: str, start: int = 0, limit: int = 25) -> T_resp_json:
"""
Get group members.
Parameters:
- group_name: Group name
- start: Starting index
- limit: Maximum results
Returns:
dict: Group members list
"""
def add_user_to_group(self, username: str, group_name: str) -> T_resp_json:
"""
Add user to group.
Parameters:
- username: Username to add
- group_name: Target group name
Returns:
dict: Operation result
"""Project Management
def project_list(self, start: int = 0, limit: int = 25) -> T_resp_json:
"""
Get all projects.
Parameters:
- start: Starting index
- limit: Maximum results
Returns:
dict: Projects list with metadata
"""
def get_project(self, project_key: str) -> T_resp_json:
"""
Get project details.
Parameters:
- project_key: Project key
Returns:
dict: Project information with repositories and permissions
"""
def create_project(self, project_key: str, project_name: str,
description: Optional[str] = None) -> T_resp_json:
"""
Create project.
Parameters:
- project_key: Unique project key
- project_name: Project display name
- description: Project description
Returns:
dict: Created project data
"""
def all_project_administrators(self, project_key: str) -> List[dict]:
"""
Get project administrators.
Parameters:
- project_key: Project key
Returns:
List[dict]: Project administrators list
"""
def get_project_users(self, project_key: str, filter_text: Optional[str] = None,
start: int = 0, limit: int = 25) -> T_resp_json:
"""
Get project users.
Parameters:
- project_key: Project key
- filter_text: Filter users by text
- start: Starting index
- limit: Maximum results
Returns:
dict: Project users with permissions
"""Webhook Management
def get_webhooks(self, project_key: str, repository_slug: str) -> List[dict]:
"""
Get repository webhooks.
Parameters:
- project_key: Project key
- repository_slug: Repository slug
Returns:
List[dict]: Configured webhooks
"""
def create_webhook(self, project_key: str, repository_slug: str,
name: str, url: str, events: List[str],
active: bool = True) -> T_resp_json:
"""
Create webhook.
Parameters:
- project_key: Project key
- repository_slug: Repository slug
- name: Webhook name
- url: Webhook URL
- events: List of events to trigger on
- active: Enable webhook immediately
Returns:
dict: Created webhook data
"""
def update_webhook(self, project_key: str, repository_slug: str,
webhook_id: str, name: str, url: str, events: List[str],
active: bool = True) -> T_resp_json:
"""
Update webhook.
Parameters:
- project_key: Project key
- repository_slug: Repository slug
- webhook_id: Webhook ID to update
- name: New webhook name
- url: New webhook URL
- events: New events list
- active: Enable/disable webhook
Returns:
dict: Updated webhook data
"""
def delete_webhook(self, project_key: str, repository_slug: str,
webhook_id: str) -> bool:
"""
Delete webhook.
Parameters:
- project_key: Project key
- repository_slug: Repository slug
- webhook_id: Webhook ID to delete
Returns:
bool: True if deletion successful
"""System Administration
def get_system_information(self) -> T_resp_json:
"""
Get system information.
Returns:
dict: System version and build information
"""
def reindex(self) -> T_resp_json:
"""
Trigger system reindex.
Returns:
dict: Reindex status
"""
def check_reindexing_status(self) -> T_resp_json:
"""
Check reindexing status.
Returns:
dict: Current reindex progress
"""
def get_license_information(self) -> T_resp_json:
"""
Get license information.
Returns:
dict: License details and user counts
"""Usage Examples
Repository Operations
from atlassian import Bitbucket
bitbucket = Bitbucket(
url="https://bitbucket.your-company.com",
username="username",
password="password"
)
# Create repository
repo = bitbucket.create_repository(
project_key="PROJ",
repository_name="my-new-repo",
public=False
)
# Get repository info
repo_info = bitbucket.get_repository("PROJ", "my-new-repo")
# Get all repositories
repos = bitbucket.get_repositories(project_key="PROJ")Branch Management
# Get branches
branches = bitbucket.get_branches("PROJ", "my-repo")
# Create feature branch
feature_branch = bitbucket.create_branch(
"PROJ", "my-repo",
name="feature/new-feature",
start_point="refs/heads/develop"
)
# Set default branch
bitbucket.set_default_branch(
"PROJ", "my-repo",
ref="refs/heads/main"
)Pull Request Workflow
# Create pull request
pr = bitbucket.create_pull_request(
project_key="PROJ",
repository_slug="my-repo",
title="Add new feature",
description="This PR adds the new feature requested in PROJ-123",
from_ref="refs/heads/feature/new-feature",
to_ref="refs/heads/develop",
reviewers=["john.doe", "jane.smith"]
)
# Get pull requests
prs = bitbucket.get_pull_requests(
"PROJ", "my-repo",
state="OPEN"
)
# Merge pull request
merge_result = bitbucket.merge_pull_request(
"PROJ", "my-repo",
pull_request_id=pr["id"],
version=pr["version"]
)User and Project Management
# Get users
users = bitbucket.get_users(filter_text="john")
# Create project
project = bitbucket.create_project(
project_key="NEWPROJ",
project_name="New Project",
description="Project for new initiative"
)
# Get project details
project_info = bitbucket.get_project("PROJ")
admins = bitbucket.all_project_administrators("PROJ")Webhook Configuration
# Create webhook for CI/CD
webhook = bitbucket.create_webhook(
project_key="PROJ",
repository_slug="my-repo",
name="CI Build Trigger",
url="https://ci.company.com/bitbucket-webhook",
events=["repo:refs_changed", "pr:opened", "pr:merged"],
active=True
)
# Get webhooks
webhooks = bitbucket.get_webhooks("PROJ", "my-repo")Error Handling
from atlassian.errors import ApiNotFoundError, ApiPermissionError
try:
repo = bitbucket.get_repository("INVALID", "nonexistent")
except ApiNotFoundError:
print("Repository not found")
except ApiPermissionError:
print("Permission denied")Types
from atlassian.typehints import T_id, T_resp_json
from typing import List, Dict, Optional
# Common parameter types
ProjectKey = str
RepositorySlug = str
BranchName = str
PullRequestState = str # "OPEN", "MERGED", "DECLINED", "ALL"
WebhookEvent = str # "repo:refs_changed", "pr:opened", etc.Install with Tessl CLI
npx tessl i tessl/pypi-atlassian-python-api