jira

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

1,939

859

1,939

191

View on GitHub

Top Related Projects

jira-cli

3,863

🔥 Feature-rich interactive Jira command line.

Quick Overview

pycontribs/jira is a Python library that provides a simple and intuitive way to interact with Jira, Atlassian's issue tracking and project management software. It allows developers to programmatically create, update, and query Jira issues, projects, and other resources through a high-level API.

Pros

Easy-to-use API that abstracts away the complexities of Jira's REST API
Supports both Jira Cloud and Jira Server instances
Comprehensive documentation and examples
Active community and regular updates

Cons

Limited support for some advanced Jira features
Performance can be slow for large-scale operations
Requires careful handling of authentication tokens
Some users report occasional inconsistencies in behavior across different Jira versions

Code Examples

Connecting to Jira and creating an issue:

from jira import JIRA

jira = JIRA(server="https://your-domain.atlassian.net", basic_auth=("your-email@example.com", "your-api-token"))

new_issue = jira.create_issue(project="PROJECT_KEY", summary="New issue summary", description="Detailed description", issuetype={"name": "Task"})
print(f"Created issue: {new_issue.key}")

Searching for issues:

issues = jira.search_issues('project = PROJECT_KEY AND status = "In Progress"')
for issue in issues:
    print(f"{issue.key}: {issue.fields.summary}")

Updating an issue:

issue = jira.issue("ISSUE-123")
issue.update(summary="Updated summary", description="New description")
issue.update(assignee={'name': 'new_assignee@example.com'})

Adding a comment to an issue:

issue = jira.issue("ISSUE-123")
jira.add_comment(issue, "This is a new comment on the issue.")

Getting Started

Install the library:
```
pip install jira
```

Import and initialize the JIRA client:

from jira import JIRA

jira = JIRA(server="https://your-domain.atlassian.net", basic_auth=("your-email@example.com", "your-api-token"))

Start interacting with Jira:

# Get information about a project
project = jira.project("PROJECT_KEY")
print(f"Project Name: {project.name}")

# Create a new issue
new_issue = jira.create_issue(project="PROJECT_KEY", summary="Test Issue", issuetype={"name": "Task"})
print(f"Created Issue: {new_issue.key}")

Competitor Comparisons

jira-cli

3,863

🔥 Feature-rich interactive Jira command line.

Pros of jira-cli

Command-line interface for easier integration with scripts and automation
Interactive mode for more user-friendly experience
Supports multiple Jira instances and context switching

Cons of jira-cli

Limited to CLI operations, less flexible for complex integrations
May require more setup and configuration for advanced use cases

Code comparison

jira-cli:

jira issue create -t Bug -s "New bug" -b "Description"
jira sprint list --board 10
jira issue assign PROJ-123 john.doe

jira (Python library):

from jira import JIRA

jira = JIRA('https://jira.example.com')
issue = jira.create_issue(project='PROJ', summary='New bug', description='Description', issuetype={'name': 'Bug'})
sprints = jira.sprints(board_id=10)
jira.assign_issue(issue, 'john.doe')

The jira-cli provides a more straightforward command-line interface for common Jira operations, while the jira Python library offers more flexibility for complex integrations and programmatic access to Jira functionality. The choice between the two depends on the specific use case and development environment.

atlassian-python-api

1,333

Atlassian Python REST API wrapper

Pros of atlassian-python-api

Supports multiple Atlassian products (Jira, Confluence, Bitbucket, etc.)
More actively maintained with frequent updates
Comprehensive documentation and examples

Cons of atlassian-python-api

Larger library size due to support for multiple products
May have a steeper learning curve for users only interested in Jira

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.issue_create(fields={'project': {'key': 'PROJ'}, 'summary': 'New issue', 'issuetype': {'name': 'Bug'}})

Both libraries offer similar functionality for basic Jira operations. The jira library has a more concise syntax for creating issues, while atlassian-python-api provides a more explicit approach. The choice between the two depends on whether you need support for other Atlassian products and your preference for API design.

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

=================== Jira Python Library

.. image:: https://img.shields.io/pypi/v/jira.svg :target: https://pypi.python.org/pypi/jira/

.. image:: https://img.shields.io/pypi/l/jira.svg :target: https://pypi.python.org/pypi/jira/

.. image:: https://img.shields.io/github/issues/pycontribs/jira.svg :target: https://github.com/pycontribs/jira/issues

.. image:: https://readthedocs.org/projects/jira/badge/?version=main :target: https://jira.readthedocs.io/

.. image:: https://codecov.io/gh/pycontribs/jira/branch/main/graph/badge.svg :target: https://codecov.io/gh/pycontribs/jira

This library eases the use of the Jira REST API from Python and it has been used in production for years.

As this is an open-source project that is community maintained, do not be surprised if some bugs or features are not implemented quickly enough.

Quickstart

Feeling impatient? I like your style.

.. code-block:: python

from jira import JIRA

jira = JIRA('https://jira.atlassian.com')

issue = jira.issue('JRA-9')
print(issue.fields.project.key)            # 'JRA'
print(issue.fields.issuetype.name)         # 'New Feature'
print(issue.fields.reporter.displayName)   # 'Mike Cannon-Brookes [Atlassian]'

Installation

Download and install using pip install jira or easy_install jira

You can also try pip install --user --upgrade jira which will install or upgrade jira to your user directory. Or maybe you ARE using a virtualenv_ right?

By default only the basic library dependencies are installed, so if you want to use the cli tool or other optional dependencies do perform a full installation using pip install jira[opt,cli,test]

.. _virtualenv: https://virtualenv.pypa.io/

Usage

See the documentation_ for full details.

.. _documentation: https://jira.readthedocs.org/

Development

Development takes place on GitHub_ using the default repository branch. Each version is tagged.

Setup

Fork_ repo
Keep it sync_'ed while you are developing

Automatic (VS Code)

.. image:: https://img.shields.io/static/v1?label=Remote%20-%20Containers&message=Open&color=blue&logo=visualstudiocode
    :target: https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/pycontribs/jira
    :alt: Open in Remote - Containers

Follow the instructions in the `contributing guide`_, which will describe how to use the dev container
that will automatically setup a suitable environment.

Manual
``````
* Install pyenv_ to install a suitable python version.
* Launch docker jira server
    - ``docker run -dit -p 2990:2990 --name jira addono/jira-software-standalone``

tox envs
````````
* Lint
    - ``tox -e lint``
* Run tests
    - ``tox``
* Build and publish with TWINE
    - ``tox -e publish``

.. _Fork: https://help.github.com/articles/fork-a-repo/
.. _sync: https://help.github.com/articles/syncing-a-fork/
.. _pyenv: https://amaral.northwestern.edu/resources/guides/pyenv-tutorial
.. _pytest: https://docs.pytest.org/en/stable/usage.html#specifying-tests-selecting-tests
.. _contributing guide: https://jira.readthedocs.io/contributing.html


Jira REST API Reference Links
=============================

When updating interactions with the Jira REST API please refer to the documentation below. We aim to support both Jira Cloud and Jira Server / Data Center.

1. `Jira Cloud`_                / `Jira Server`_ (main REST API reference)
2. `Jira Software Cloud`_       / `Jira Software Server`_ (former names include: Jira Agile, Greenhopper)
3. `Jira Service Desk Cloud`_   / `Jira Service Desk Server`_

.. _`Jira Cloud`: https://developer.atlassian.com/cloud/jira/platform/rest/v2/
.. _`Jira Server`: https://docs.atlassian.com/software/jira/docs/api/REST/latest/
.. _`Jira Software Cloud`: https://developer.atlassian.com/cloud/jira/software/rest/
.. _`Jira Software Server`: https://docs.atlassian.com/jira-software/REST/latest/
.. _`Jira Service Desk Cloud`: https://docs.atlassian.com/jira-servicedesk/REST/cloud/
.. _`Jira Service Desk Server`: https://docs.atlassian.com/jira-servicedesk/REST/server/


Credits
-------

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

* Atlassian_ for developing such a powerful issue tracker and for providing a free on-demand Jira_ instance that we can use for continuous integration testing.
* JetBrains_ for providing us with free licenses of PyCharm_
* GitHub_ for hosting our continuous integration and our git repo
* Navicat_ for providing us free licenses of their powerful database client GUI tools.

.. _Atlassian: https://www.atlassian.com/
.. _Jira: https://pycontribs.atlassian.net
.. _JetBrains: https://www.jetbrains.com/
.. _PyCharm: https://www.jetbrains.com/pycharm/
.. _GitHub: https://github.com/pycontribs/jira
.. _Navicat: https://www.navicat.com/

.. image:: https://raw.githubusercontent.com/pycontribs/resources/main/logos/x32/logo-atlassian.png
   :target: https://www.atlassian.com/

.. image:: https://raw.githubusercontent.com/pycontribs/resources/main/logos/x32/logo-pycharm.png
    :target: https://www.jetbrains.com/

.. image:: https://raw.githubusercontent.com/pycontribs/resources/main/logos/x32/logo-navicat.png
    :target: https://www.navicat.com/

Top Related Projects

jira-cli

3,863

🔥 Feature-rich interactive Jira command line.

atlassian-python-api

1,333

Atlassian Python REST API wrapper

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