atlassian-python-api

Atlassian Python REST API wrapper

1,333

657

1,333

264

View on GitHub

Top Related Projects

jira

1,939

Python Jira library. Development chat available on https://matrix.to/#/#pycontribs:matrix.org

python-gitlab

2,231

A python wrapper for the GitLab API.

PyGithub

6,901

Typed interactions with the GitHub API v3

requests

52,086

A simple, yet elegant, HTTP library.

Quick Overview

The atlassian-python-api is a Python library that provides a simple and intuitive way to interact with various Atlassian products' APIs, including Jira, Confluence, Bitbucket, and more. It simplifies the process of integrating Atlassian tools into Python applications, automating tasks, and managing Atlassian resources programmatically.

Pros

Comprehensive coverage of multiple Atlassian products in a single library
Well-documented with clear examples and API references
Actively maintained with regular updates and community support
Simplifies complex API interactions with easy-to-use Python methods

Cons

May require frequent updates to keep up with changes in Atlassian products' APIs
Some advanced features of Atlassian products might not be fully covered
Learning curve for users unfamiliar with Atlassian products' terminology and concepts
Dependency on Atlassian's API stability and availability

Code Examples

Connecting to Jira and creating an issue:

from atlassian import Jira

jira = Jira(
    url='https://your-domain.atlassian.net',
    username='your-email@example.com',
    password='your-api-token'
)

new_issue = jira.create_issue(
    project='PROJECT_KEY',
    issuetype='Task',
    summary='New task created via API',
    description='This is a test task created using the atlassian-python-api library.'
)
print(f"New issue created: {new_issue['key']}")

Retrieving a page from Confluence:

from atlassian import Confluence

confluence = Confluence(
    url='https://your-domain.atlassian.net',
    username='your-email@example.com',
    password='your-api-token'
)

page_id = '123456'
page = confluence.get_page_by_id(page_id)
print(f"Page title: {page['title']}")
print(f"Page content: {page['body']['storage']['value']}")

Listing repositories in Bitbucket:

from atlassian import Bitbucket

bitbucket = Bitbucket(
    url='https://your-domain.atlassian.net',
    username='your-email@example.com',
    password='your-api-token'
)

project_key = 'PROJECT_KEY'
repos = bitbucket.repo_list(project_key)
for repo in repos:
    print(f"Repository: {repo['name']}")

Getting Started

To get started with the atlassian-python-api:

Install the library using pip:
```
pip install atlassian-python-api
```

Import the desired Atlassian product class:

from atlassian import Jira  # or Confluence, Bitbucket, etc.

Create an instance of the class with your Atlassian domain and credentials:

jira = Jira(
    url='https://your-domain.atlassian.net',
    username='your-email@example.com',
    password='your-api-token'
)

Start using the available methods to interact with the Atlassian product's API:
```
issues = jira.jql('project = PROJECT_KEY')
```

Remember to replace the URL, username, and password with your actual Atlassian account details and use an API token instead of your account password for enhanced security.

Competitor Comparisons

jira

1,939

Python Jira library. Development chat available on https://matrix.to/#/#pycontribs:matrix.org

Pros of jira

More focused and specialized for Jira interactions
Simpler API with fewer dependencies
Better documentation and examples for Jira-specific tasks

Cons of jira

Limited to Jira functionality only
Less frequent updates and maintenance
Smaller community and fewer contributors

Code Comparison

jira:

from jira import JIRA

jira = JIRA('https://jira.example.com', basic_auth=('username', 'password'))
issue = jira.create_issue(project='PROJ', summary='New issue', issuetype={'name': 'Bug'})

atlassian-python-api:

from atlassian import Jira

jira = Jira(url='https://jira.example.com', username='username', password='password')
issue = jira.create_issue(fields={'project': {'key': 'PROJ'}, 'summary': 'New issue', 'issuetype': {'name': 'Bug'}})

The jira library offers a more straightforward approach for creating issues, while atlassian-python-api provides a more flexible but slightly more verbose method. The atlassian-python-api covers a broader range of Atlassian products, making it a better choice for projects involving multiple Atlassian tools. However, for Jira-specific tasks, the jira library may be more intuitive and easier to use.

copilot-docs

23,230

Documentation for GitHub Copilot

Pros of copilot-docs

Focuses on AI-assisted coding documentation, providing valuable insights for developers using GitHub Copilot
Regularly updated with new features and best practices for AI-powered code generation
Includes comprehensive guides and examples for various programming languages and scenarios

Cons of copilot-docs

Limited scope, primarily focused on GitHub Copilot rather than a broader range of APIs
May not provide direct API access or integration capabilities
Less suitable for developers working with Atlassian products or requiring Atlassian-specific functionality

Code comparison

atlassian-python-api:

from atlassian import Jira

jira = Jira(url="https://jira.example.com", username="user", password="pass")
issue = jira.issue("PROJ-123")

copilot-docs:

# No direct API access, but provides guidance on using Copilot
# Example of a Copilot-generated code snippet:
def calculate_fibonacci(n):
    if n <= 1:
        return n
    return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)

The atlassian-python-api repository offers direct API access to Atlassian products, while copilot-docs focuses on documentation and best practices for using GitHub Copilot. The code examples reflect this difference, with atlassian-python-api demonstrating API usage and copilot-docs showcasing AI-generated code snippets.

python-gitlab

2,231

A python wrapper for the GitLab API.

Pros of python-gitlab

More focused and specialized for GitLab API interactions
Extensive documentation and examples for various GitLab-specific features
Active development with frequent updates and community contributions

Cons of python-gitlab

Limited to GitLab only, not suitable for other Atlassian products
May have a steeper learning curve for users not familiar with GitLab's API structure

Code Comparison

python-gitlab:

import gitlab

gl = gitlab.Gitlab('https://gitlab.com', private_token='your_token')
project = gl.projects.get('username/project')
issues = project.issues.list()

atlassian-python-api:

from atlassian import Bitbucket

bitbucket = Bitbucket(
    url='https://bitbucket.org',
    username='your_username',
    password='your_password'
)
repo = bitbucket.repo_browse('project_key', 'repo_slug')

The code examples demonstrate the different approaches to authentication and repository access. python-gitlab uses a more GitLab-specific structure, while atlassian-python-api provides a more generalized approach for Atlassian products.

PyGithub

6,901

Typed interactions with the GitHub API v3

Pros of PyGithub

More comprehensive coverage of GitHub API endpoints
Larger community and more frequent updates
Better documentation and examples

Cons of PyGithub

Focused solely on GitHub, not suitable for other Atlassian products
Can be more complex to use for simple tasks
Larger package size and potentially slower performance

Code Comparison

PyGithub:

from github import Github

g = Github("access_token")
repo = g.get_repo("PyGithub/PyGithub")
issues = repo.get_issues(state="open")

atlassian-python-api:

from atlassian import Bitbucket

bitbucket = Bitbucket(
    url='https://your-domain.atlassian.net',
    username='email@example.com',
    password='api_token'
)
issues = bitbucket.get_issues('project_key', 'repository_slug')

The code examples demonstrate the different approaches to authentication and retrieving issues. PyGithub is more GitHub-specific, while atlassian-python-api provides a unified interface for various Atlassian products, including Bitbucket.

PyGithub is ideal for projects exclusively working with GitHub, offering deeper integration and more GitHub-specific features. atlassian-python-api is better suited for projects that need to interact with multiple Atlassian products or require a more streamlined approach to working with Atlassian services.

requests

52,086

A simple, yet elegant, HTTP library.

Pros of requests

Widely adopted and well-maintained HTTP library for Python
Extensive documentation and community support
Supports a wide range of HTTP operations and features

Cons of requests

Not specifically designed for Atlassian products
Requires more manual configuration for Atlassian API interactions
May need additional libraries for certain Atlassian-specific functionalities

Code comparison

requests:

import requests

response = requests.get('https://api.atlassian.com/endpoint', 
                        auth=('username', 'password'))
data = response.json()

atlassian-python-api:

from atlassian import Jira

jira = Jira(url='https://your-domain.atlassian.net', 
            username='your-username', 
            password='your-password')
issue = jira.issue('PROJ-123')

The atlassian-python-api provides a more streamlined approach for interacting with Atlassian products, offering pre-configured methods for common operations. In contrast, requests offers a more general-purpose HTTP client, requiring manual configuration for specific Atlassian API endpoints and authentication.

While requests is more versatile for general HTTP requests, atlassian-python-api simplifies Atlassian-specific tasks with its tailored methods and abstractions. The choice between the two depends on the scope of the project and the level of Atlassian integration required.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

============================ Atlassian Python API wrapper

What is it?

The atlassian-python-api library provides a simple and convenient way to interact with Atlassian products (such as Jira Service management, Jira Software, Confluence, Bitbucket and apps Insight, X-Ray) using Python. It is based on the official REST APIs of these products, as well as additional private methods and protocols (such as xml+rpc and raw HTTP requests). This library can be used to automate tasks, integrate with other tools and systems, and build custom applications that interact with Atlassian products. It supports a wide range of Atlassian products, including Jira, Confluence, Bitbucket, StatusPage and others, and is compatible with both Atlassian Server and Cloud instances.

Overall, the atlassian-python-api is a useful tool for Python developers who want to work with Atlassian products. It is well-documented and actively maintained, and provides a convenient way to access the full range of functionality offered by the Atlassian REST APIs.

Documentation

Documentation_

.. _Documentation: https://atlassian-python-api.readthedocs.io

How to Install?

From PyPI

.. code-block:: console

$ pip install atlassian-python-api

From Source

Git clone repository
Use :code:pip install -r requirements.txt to install the required packages
or :code:pipenv install && pipenv install --dev

Examples

More examples in :code:examples/ directory.

Here's a short example of how to create a Confluence page:

.. code-block:: python

from atlassian import Confluence

confluence = Confluence(
    url='http://localhost:8090',
    username='admin',
    password='admin')

status = confluence.create_page(
    space='DEMO',
    title='This is the title',
    body='This is the body. You can use <strong>HTML tags</strong>!')

print(status)

Please, note Confluence Cloud need to be used via token parameter. And here's another example of how to get issues from Jira using JQL Query:

.. code-block:: python

from atlassian import Jira

jira = Jira(
    url='http://localhost:8080',
    username='admin',
    password='admin')
JQL = 'project = DEMO AND status IN ("To Do", "In Progress") ORDER BY issuekey'
data = jira.jql(JQL)
print(data)

Also, you can use the Bitbucket module e.g. for getting project list

.. code-block:: python

from atlassian import Bitbucket

bitbucket = Bitbucket(
        url='http://localhost:7990',
        username='admin',
        password='admin')

data = bitbucket.project_list()
print(data)

Now you can use the Jira Service Desk module. See docs. Example to get your requests:

.. code-block:: python

from atlassian import ServiceDesk

sd = ServiceDesk(
        url='http://localhost:7990',
        username='admin',
        password='admin')

data = sd.get_my_customer_requests()
print(data)

Using Insight (CMDB Tool for Jira):

.. code-block:: python

from atlassian import Insight

insight = Insight(
        url='http://localhost:7990',
        username='admin',
        password='admin')

data = insight.get_object(88)
print(data)

Using Xray (Test Management tool for Jira):

.. code-block:: python

from atlassian import Xray

xr = Xray(
       url='http://localhost:7990',
        username='admin',
        password='admin')

data = xr.get_tests('TEST-001')
print(data)

Using Bamboo:

.. code-block:: python

from atlassian import Bamboo

bamboo = Bamboo(
        url='http://localhost:6990/bamboo/',
        token="<TOKEN>")

data = bamboo.get_elastic_configurations()
print(data)

If you want to see the response in pretty print format JSON. Feel free for use construction like:

.. code-block:: python

from pprint import pprint
# you code here
# and then print using pprint(result) instead of print(result)
pprint(response)

How to contribute?

First of all, I am happy for any PR requests. Let's fork and provide your changes :) See the Contribution Guidelines for this project_ for details on how to make changes to this library.

Credits

In addition to all the contributors we would like to thank these vendors:

Atlassian_ for developing such a powerful ecosystem.
JetBrains_ for providing us with free licenses of PyCharm_
Microsoft_ for providing us with free licenses of VSCode_
GitHub_ for hosting our repository and continuous integration

.. _Atlassian: https://www.atlassian.com/ .. _JetBrains: http://www.jetbrains.com .. _PyCharm: http://www.jetbrains.com/pycharm/ .. _GitHub: https://github.com/ .. _Microsoft: https://github.com/Microsoft/vscode/ .. _VSCode: https://code.visualstudio.com/

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot