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
development-tools.mddocs/
Development Tools
Comprehensive CI/CD and test management tools including Bamboo for build automation and X-Ray for test execution and reporting. Enables integration of Atlassian development tools into automated workflows and quality assurance processes.
Bamboo - CI/CD Build Management
Bamboo REST API client providing complete build pipeline management, plan execution, and artifact handling for continuous integration and deployment workflows.
Initialization
class Bamboo(AtlassianRestAPI):
def __init__(self, url: str, username: str = None, password: str = None,
token: str = None, **kwargs):
"""
Initialize Bamboo client.
Parameters:
- url (str): Base URL of Bamboo instance
- username (str, optional): Username for authentication
- password (str, optional): Password or API token
- token (str, optional): Bearer token for authentication
"""Build Management
def get_builds(self, project_key: Optional[str] = None,
plan_key: Optional[str] = None,
start: int = 0, limit: int = 25) -> T_resp_json:
"""
Get builds with optional filtering.
Parameters:
- project_key: Filter by project key
- plan_key: Filter by plan key
- start: Starting index for pagination
- limit: Maximum results to return
Returns:
dict: Build list with status and timing information
"""
def get_build(self, build_key: str) -> T_resp_json:
"""
Get build details.
Parameters:
- build_key: Build key (e.g., "PROJ-PLAN-123")
Returns:
dict: Build information with logs and artifacts
"""
def start_build(self, plan_key: str, **kwargs) -> T_resp_json:
"""
Start build execution.
Parameters:
- plan_key: Plan key to execute
- **kwargs: Additional build parameters
Returns:
dict: Started build information
"""
def stop_build(self, build_key: str) -> T_resp_json:
"""
Stop running build.
Parameters:
- build_key: Build key to stop
Returns:
dict: Stop operation result
"""
def get_build_status(self, build_key: str) -> T_resp_json:
"""
Get build status.
Parameters:
- build_key: Build key
Returns:
dict: Current build status and progress
"""Plan Management
def get_plans(self, project_key: Optional[str] = None,
start: int = 0, limit: int = 25) -> T_resp_json:
"""
Get build plans.
Parameters:
- project_key: Filter by project
- start: Starting index
- limit: Maximum results
Returns:
dict: Plans list with configuration
"""
def get_plan(self, plan_key: str) -> T_resp_json:
"""
Get plan details.
Parameters:
- plan_key: Plan key
Returns:
dict: Plan configuration and branches
"""
def create_plan(self, project_key: str, plan_name: str, plan_key: str,
description: Optional[str] = None) -> T_resp_json:
"""
Create build plan.
Parameters:
- project_key: Project key
- plan_name: Plan display name
- plan_key: Unique plan key
- description: Plan description
Returns:
dict: Created plan data
"""
def clone_plan(self, plan_key: str, new_plan_key: str,
new_plan_name: str) -> T_resp_json:
"""
Clone existing plan.
Parameters:
- plan_key: Source plan key
- new_plan_key: New plan key
- new_plan_name: New plan name
Returns:
dict: Cloned plan information
"""
def enable_plan(self, plan_key: str) -> T_resp_json:
"""
Enable build plan.
Parameters:
- plan_key: Plan key to enable
Returns:
dict: Operation result
"""
def disable_plan(self, plan_key: str) -> T_resp_json:
"""
Disable build plan.
Parameters:
- plan_key: Plan key to disable
Returns:
dict: Operation result
"""Results and Artifacts
def get_results(self, plan_key: str, build_number: Optional[int] = None,
start: int = 0, limit: int = 25) -> T_resp_json:
"""
Get build results.
Parameters:
- plan_key: Plan key
- build_number: Specific build number
- start: Starting index
- limit: Maximum results
Returns:
dict: Build results with test outcomes
"""
def get_latest_results(self, plan_key: str) -> T_resp_json:
"""
Get latest build results.
Parameters:
- plan_key: Plan key
Returns:
dict: Most recent build results
"""
def get_artifacts(self, build_key: str) -> T_resp_json:
"""
Get build artifacts.
Parameters:
- build_key: Build key
Returns:
dict: Artifacts list with download URLs
"""
def download_artifact(self, build_key: str, artifact_name: str) -> bytes:
"""
Download build artifact.
Parameters:
- build_key: Build key
- artifact_name: Artifact name
Returns:
bytes: Artifact content
"""X-Ray - Test Management
X-Ray REST API client providing comprehensive test management including test execution, result reporting, and test plan organization for quality assurance workflows.
Initialization
class Xray(AtlassianRestAPI):
def __init__(self, url: str, username: str = None, password: str = None,
token: str = None, cloud: bool = None, **kwargs):
"""
Initialize X-Ray client.
Parameters:
- url (str): Base URL of Jira instance with X-Ray
- username (str, optional): Username for authentication
- password (str, optional): Password or API token
- token (str, optional): Bearer token for authentication
- cloud (bool, optional): True for Cloud, False for Server/DC
"""Test Management
def get_tests(self, project_key: str, test_type: Optional[str] = None,
start: int = 0, limit: int = 50) -> T_resp_json:
"""
Get tests from project.
Parameters:
- project_key: Project key
- test_type: Filter by test type ("Manual", "Cucumber", "Generic")
- start: Starting index
- limit: Maximum results
Returns:
dict: Tests list with details
"""
def get_test(self, test_key: str) -> T_resp_json:
"""
Get test details.
Parameters:
- test_key: Test issue key
Returns:
dict: Test information with steps and conditions
"""
def create_test(self, project_key: str, summary: str, test_type: str,
description: Optional[str] = None,
steps: Optional[List[dict]] = None) -> T_resp_json:
"""
Create test case.
Parameters:
- project_key: Project key
- summary: Test summary
- test_type: Test type ("Manual", "Cucumber", "Generic")
- description: Test description
- steps: Test steps for manual tests
Returns:
dict: Created test data
"""
def update_test(self, test_key: str, summary: Optional[str] = None,
description: Optional[str] = None,
steps: Optional[List[dict]] = None) -> T_resp_json:
"""
Update test case.
Parameters:
- test_key: Test issue key
- summary: New summary
- description: New description
- steps: Updated test steps
Returns:
dict: Updated test data
"""Test Execution
def get_test_runs(self, test_key: str, start: int = 0,
limit: int = 50) -> T_resp_json:
"""
Get test execution history.
Parameters:
- test_key: Test issue key
- start: Starting index
- limit: Maximum results
Returns:
dict: Test runs with results and timestamps
"""
def get_test_runs_in_context(self, test_key: str, test_exec_key: str,
start: int = 0, limit: int = 50) -> T_resp_json:
"""
Get test runs within specific execution context.
Parameters:
- test_key: Test issue key
- test_exec_key: Test execution issue key
- start: Starting index
- limit: Maximum results
Returns:
dict: Contextual test runs
"""
def create_test_execution(self, project_key: str, summary: str,
test_keys: List[str],
test_plan_key: Optional[str] = None) -> T_resp_json:
"""
Create test execution.
Parameters:
- project_key: Project key
- summary: Execution summary
- test_keys: List of test issue keys to execute
- test_plan_key: Associated test plan key
Returns:
dict: Created test execution data
"""
def update_test_run_status(self, test_exec_key: str, test_key: str,
status: str, comment: Optional[str] = None,
defects: Optional[List[str]] = None) -> T_resp_json:
"""
Update test run status.
Parameters:
- test_exec_key: Test execution key
- test_key: Test key
- status: Test status ("PASS", "FAIL", "EXECUTING", "TODO", "ABORTED")
- comment: Execution comment
- defects: Associated defect keys
Returns:
dict: Updated test run result
"""Test Plans
def get_test_plans(self, project_key: str, start: int = 0,
limit: int = 50) -> T_resp_json:
"""
Get test plans from project.
Parameters:
- project_key: Project key
- start: Starting index
- limit: Maximum results
Returns:
dict: Test plans list
"""
def get_test_plan(self, test_plan_key: str) -> T_resp_json:
"""
Get test plan details.
Parameters:
- test_plan_key: Test plan issue key
Returns:
dict: Test plan with associated tests and executions
"""
def create_test_plan(self, project_key: str, summary: str,
description: Optional[str] = None) -> T_resp_json:
"""
Create test plan.
Parameters:
- project_key: Project key
- summary: Test plan summary
- description: Test plan description
Returns:
dict: Created test plan data
"""
def associate_test_to_test_plan(self, test_plan_key: str,
test_keys: List[str]) -> T_resp_json:
"""
Associate tests with test plan.
Parameters:
- test_plan_key: Test plan issue key
- test_keys: List of test issue keys
Returns:
dict: Association result
"""Import and Export
def import_execution_results(self, execution_results: dict,
project_key: Optional[str] = None,
test_plan_key: Optional[str] = None) -> T_resp_json:
"""
Import test execution results.
Parameters:
- execution_results: Results data in X-Ray format
- project_key: Target project key
- test_plan_key: Associated test plan
Returns:
dict: Import results with created issues
"""
def export_test_results(self, test_exec_key: str,
format: str = "json") -> Union[dict, str]:
"""
Export test execution results.
Parameters:
- test_exec_key: Test execution key
- format: Export format ("json", "xml", "junit")
Returns:
dict or str: Exported results in requested format
"""
def import_cucumber_tests(self, project_key: str, file_content: str,
update_repository: bool = False) -> T_resp_json:
"""
Import Cucumber feature files.
Parameters:
- project_key: Project key
- file_content: Cucumber feature file content
- update_repository: Update existing tests
Returns:
dict: Import results with created/updated tests
"""Usage Examples
Bamboo Build Automation
from atlassian import Bamboo
bamboo = Bamboo(
url="https://bamboo.company.com",
username="username",
password="password"
)
# Get build plans
plans = bamboo.get_plans(project_key="PROJ")
# Start build
build = bamboo.start_build("PROJ-PLAN")
# Monitor build progress
build_status = bamboo.get_build_status(build["buildResultKey"])
# Get build results when complete
if build_status["state"] == "Successful":
results = bamboo.get_results("PROJ-PLAN")
artifacts = bamboo.get_artifacts(build["buildResultKey"])
# Download artifacts
for artifact in artifacts["artifacts"]["artifact"]:
content = bamboo.download_artifact(
build["buildResultKey"],
artifact["name"]
)
with open(artifact["name"], "wb") as f:
f.write(content)X-Ray Test Management
from atlassian import Xray
xray = Xray(
url="https://your-domain.atlassian.net",
username="email@example.com",
password="api-token"
)
# Create test case
test = xray.create_test(
project_key="PROJ",
summary="User login functionality",
test_type="Manual",
description="Verify user can log in with valid credentials",
steps=[
{
"step": "Navigate to login page",
"data": "",
"result": "Login page displays"
},
{
"step": "Enter valid username and password",
"data": "user@example.com, password123",
"result": "Credentials accepted"
}
]
)
# Create test plan
test_plan = xray.create_test_plan(
project_key="PROJ",
summary="Sprint 1 Test Plan",
description="Test plan for sprint 1 features"
)
# Associate test with plan
xray.associate_test_to_test_plan(
test_plan["key"],
[test["key"]]
)
# Create and execute test
test_execution = xray.create_test_execution(
project_key="PROJ",
summary="Sprint 1 Test Execution",
test_keys=[test["key"]],
test_plan_key=test_plan["key"]
)
# Update test results
xray.update_test_run_status(
test_execution["key"],
test["key"],
status="PASS",
comment="All test steps passed successfully"
)CI/CD Integration
# Automated test execution with Bamboo and X-Ray integration
def run_automated_tests(project_key, plan_key):
# Start Bamboo build
build = bamboo.start_build(plan_key)
# Wait for build completion
while True:
status = bamboo.get_build_status(build["buildResultKey"])
if status["state"] in ["Successful", "Failed"]:
break
time.sleep(30)
# Create X-Ray test execution
test_execution = xray.create_test_execution(
project_key=project_key,
summary=f"Automated Test Run - Build {build['buildNumber']}",
test_keys=get_automated_test_keys(project_key)
)
# Import test results from build artifacts
if status["state"] == "Successful":
artifacts = bamboo.get_artifacts(build["buildResultKey"])
for artifact in artifacts["artifacts"]["artifact"]:
if artifact["name"].endswith("test-results.json"):
results_content = bamboo.download_artifact(
build["buildResultKey"],
artifact["name"]
)
results = json.loads(results_content)
xray.import_execution_results(
results,
project_key=project_key
)Error Handling
from atlassian.errors import ApiError, ApiNotFoundError
try:
build = bamboo.start_build("INVALID-PLAN")
except ApiNotFoundError:
print("Build plan not found")
except ApiError as e:
print(f"Build failed to start: {e}")Types
from atlassian.typehints import T_id, T_resp_json
from typing import List, Dict, Optional, Union
# Bamboo types
PlanKey = str
BuildKey = str
BuildState = str # "Successful", "Failed", "In Progress"
# X-Ray types
TestKey = str
TestType = str # "Manual", "Cucumber", "Generic"
TestStatus = str # "PASS", "FAIL", "EXECUTING", "TODO", "ABORTED"
TestExecutionKey = str
TestPlanKey = strInstall with Tessl CLI
npx tessl i tessl/pypi-atlassian-python-api