jira2py 0.8.0

The Python library to interact with Atlassian Jira REST API

jira2py

A lightweight, type-safe Python client for the Jira Cloud REST API v3.

jira2py is Jira Cloud only. It does not add Jira Server/Data Center support, board/sprint/epic workflows, issue delete/archive workflows, or a dedicated issue-assign helper/API.

Installation

pip install jira2py

Quick Start

from jira2py import JiraAPI

jira = JiraAPI(
    url="https://your-domain.atlassian.net",
    username="[e-mail]",
    api_token="your-api-token",
)

issue = jira.issues.get_issue("PROJECT-123")
results = jira.search.enhanced_search("project = PROJECT AND status = 'In Progress'")

By default, JiraAPI() loads credentials from environment variables:

export JIRA_URL="https://your-domain.atlassian.net"
export JIRA_USER="[e-mail]"
export JIRA_API_TOKEN="your-api-token"

jira = JiraAPI()

You can also pass an explicit JSON credentials file path. There is no default credentials file path.

{
  "url": "https://your-domain.atlassian.net",
  "username": "[e-mail]",
  "api_token": "your-api-token"
}

jira = JiraAPI(credentials_file="./jira-credentials.json")

When credentials_file is provided, jira2py loads that file. Explicit url, username, and api_token arguments still override file values.

Choose Your API Layer

jira2py has two complementary layers:

• Low-level JiraAPI — endpoint-oriented methods that return Jira REST JSON shapes directly.
• High-level JiraHelpers — grouped workflows that return readable HelperResult objects with optional structured data.

from jira2py import JiraAPI
from jira2py.helpers import JiraHelpers

api = JiraAPI()
helpers = JiraHelpers(api)

print(helpers.auth.status().text)
print(helpers.auth.me().text)
print(helpers.metadata.transitions("PROJECT-123").text)
print(helpers.comments.update("PROJECT-123", "10001", "Updated comment").text)
print(helpers.attachments.list("PROJECT-123").text)
print(helpers.links.list("PROJECT-123").text)
print(helpers.worklogs.list("PROJECT-123").text)
print(helpers.metadata.project("PROJECT").text)
print(helpers.metadata.statuses().text)
print(helpers.metadata.priorities().text)
print(helpers.filters.search("Team").text)
print(helpers.filters.run("12345", fields=["summary", "status"]).text)

Helper methods cover:

• auth status and current user (helpers.auth.status(), helpers.auth.me())
• issue read/create/edit and workflow transitions
• comment list/add/update/delete
• attachment list/read/plan/download/upload/delete
• issue-link list/types/create/delete
• worklog list/add/update/delete/report
• project lookup, project search, transitions, statuses, priorities, users, and field metadata
• saved filter list/search and filter-run via resolved JQL

filter-run is exposed as a helper workflow: it resolves the saved filter JQL and returns the same output shape as normal issue search.

API Coverage

Module	Operations
Issues	Get, create, edit, transition issues; changelogs; edit metadata; create metadata
Issue Search	JQL search with pagination
Issue Comments	List, add, update, delete comments
Issue Worklogs	List, add, update, delete issue worklogs
Issue Fields	List system and custom fields
Issue Links	List issue links, list link types, create and delete links
Projects	Get, search, and list projects
Attachments	List issue attachments, read metadata, download, upload, and delete attachments
Users	Search users and get the current authenticated user
Metadata	Statuses and priorities
Filters	Search/list saved filters and resolve filter JQL
Helpers	High-level auth, issues, search, comments, worklogs, attachments, metadata, links, and filters workflows

Documentation

Full documentation is available at jira2py.org.

Machine-readable documentation for AI agents and LLMs:

• llms.txt
• llms-full.txt
• api-reference.json

License

MIT