or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

administration.mdagile-boards.mdclient-setup.mdcomments-attachments.mdfilters-dashboards.mdindex.mdissue-management.mdproject-management.mdremote-links.mdservice-desk.mdsystem-operations.mduser-management.mdworklogs.md
tile.json

tessl/pypi-jira

Python library for interacting with JIRA via REST APIs.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/jira@2.0.x

To install, run

npx @tessl/cli install tessl/pypi-jira@2.0.0

index.mddocs/

JIRA Python Library

A comprehensive Python library for interacting with JIRA via REST APIs, enabling developers to programmatically manage JIRA issues, projects, users, and workflows. It offers a high-level client interface that abstracts the complexity of REST API calls, supports multiple authentication methods, and provides object-oriented access to JIRA resources.

Package Information

  • Package Name: jira
  • Language: Python
  • Installation: pip install jira

Core Imports

from jira import JIRA

Import specific resource classes:

from jira import JIRA, Issue, Project, User, Comment, Worklog, JIRAError

Import configuration helper:

from jira import get_jira

Access version information:

from jira import __version__, version_info

print(f"JIRA library version: {__version__}")
print(f"Version tuple: {version_info}")

Basic Usage

from jira import JIRA

# Connect to JIRA server with basic authentication
jira = JIRA(
    server='https://your-jira-instance.com',
    basic_auth=('username', 'password')
)

# Get current user information
user = jira.myself()
print(f"Connected as: {user.displayName}")

# Search for issues using JQL
issues = jira.search_issues('project = PROJ AND status = "To Do"', maxResults=10)
for issue in issues:
    print(f"{issue.key}: {issue.fields.summary}")

# Create a new issue
new_issue = jira.create_issue(
    project={'key': 'PROJ'},
    summary='New issue from Python',
    description='Created using jira-python library',
    issuetype={'name': 'Task'}
)
print(f"Created issue: {new_issue.key}")

# Add a comment to an issue
jira.add_comment(new_issue, 'This is a comment added via Python')

# Transition an issue
transitions = jira.transitions(new_issue)
for transition in transitions:
    if transition['name'] == 'In Progress':
        jira.transition_issue(new_issue, transition['id'])
        break

Architecture

The library is built around the main JIRA client class that provides methods for all JIRA operations. Key architectural components:

  • JIRA Client: Main interface with 241 methods covering complete JIRA functionality
  • Resource Classes: Object-oriented representations of JIRA entities (Issue, Project, User, etc.) with update/delete capabilities
  • Authentication: Support for Basic Auth, OAuth, JWT, Kerberos, and session-based authentication
  • Session Management: Built-in session handling with retry logic for resilient connections
  • Async Support: Optional asynchronous operations for high-performance applications

Capabilities

Client Setup & Authentication

Configuration and authentication options for connecting to JIRA instances, including basic auth, OAuth, JWT, and Kerberos authentication methods.

class JIRA:
    def __init__(
        self,
        server: str = None,
        options: dict = None,
        basic_auth: tuple = None,
        oauth: dict = None,
        jwt: dict = None,
        kerberos: bool = False,
        kerberos_options: dict = None,
        validate: bool = False,
        get_server_info: bool = True,
        async_: bool = False,
        async_workers: int = 5,
        logging: bool = True,
        max_retries: int = 3,
        proxies: dict = None,
        timeout: int = None,
        auth = None
    ): ...

Client Setup & Authentication

Issue Management

Comprehensive issue operations including creation, search, update, transitions, and bulk operations using JQL (JIRA Query Language).

def search_issues(
    self,
    jql_str: str,
    startAt: int = 0,
    maxResults: int = 50,
    validate_query: bool = True,
    fields: str = None,
    expand: str = None,
    json_result: bool = None
) -> list[Issue]: ...

def create_issue(self, fields: dict = None, prefetch: bool = True, **fieldargs) -> Issue: ...
def issue(self, id: str, fields: str = None, expand: str = None) -> Issue: ...
def assign_issue(self, issue: Issue, assignee: str): ...
def transition_issue(
    self,
    issue: Issue,
    transition: str,
    fields: dict = None,
    comment: str = None,
    worklog: dict = None,
    **fieldargs
): ...

Issue Management

Project & Component Management

Project administration including project creation, component management, version control, and role assignment.

def projects(self) -> list[Project]: ...
def project(self, id: str) -> Project: ...
def create_project(
    self,
    key: str,
    name: str = None,
    assignee: str = None,
    type: str = "Software",
    template_name: str = None
) -> Project: ...
def project_components(self, project: str) -> list: ...
def create_component(
    self,
    name: str,
    project: str,
    description: str = None,
    leadUserName: str = None
) -> dict: ...

Project & Component Management

User & Group Management

User administration including user creation, group management, permissions, and avatar management.

def user(self, id: str, expand: str = None) -> User: ...
def search_users(
    self,
    user: str,
    startAt: int = 0,
    maxResults: int = 50,
    includeActive: bool = True,
    includeInactive: bool = False
) -> list[User]: ...
def add_user(
    self,
    username: str,
    email: str,
    directoryId: int = 1,
    password: str = None,
    fullname: str = None,
    notify: bool = False,
    active: bool = True
) -> User: ...

User & Group Management

Comments & Attachments

Comment management and file attachment operations for issues.

def add_comment(
    self,
    issue: Issue,
    body: str,
    visibility: dict = None,
    is_internal: bool = False
) -> Comment: ...
def comments(self, issue: Issue) -> list[Comment]: ...
def add_attachment(
    self,
    issue: Issue,
    attachment: str,
    filename: str = None
) -> Attachment: ...
def attachment(self, id: str) -> Attachment: ...

Comments & Attachments

Worklogs & Time Tracking

Work logging and time tracking functionality for issues.

def add_worklog(
    self,
    issue: Issue,
    timeSpent: str = None,
    timeSpentSeconds: int = None,
    adjustEstimate: str = None,
    newEstimate: str = None,
    reduceBy: str = None,
    comment: str = None,
    started: str = None,
    user: str = None
) -> Worklog: ...
def worklogs(self, issue: Issue) -> list[Worklog]: ...

Worklogs & Time Tracking

Agile & Boards

Agile/Scrum functionality including board management, sprint operations, and backlog management using the GreenHopper API.

def boards(
    self,
    startAt: int = 0,
    maxResults: int = 50,
    type: str = None,
    name: str = None
) -> list[Board]: ...
def create_sprint(
    self,
    name: str,
    board_id: int,
    startDate: str = None,
    endDate: str = None
) -> Sprint: ...
def add_issues_to_sprint(self, sprint_id: int, issue_keys: list[str]): ...

Agile & Boards

Service Desk

JIRA Service Desk functionality for customer request management and service desk operations.

def create_customer(self, email: str, displayName: str) -> Customer: ...
def service_desks(self) -> list[ServiceDesk]: ...
def create_customer_request(self, fields: dict = None, prefetch: bool = True, **fieldargs): ...

Service Desk

Filters & Dashboards

Manage saved JQL filters and dashboard operations for organizing and sharing JIRA queries and visualizations.

def filter(self, id: str) -> Filter: ...
def favourite_filters(self) -> list[Filter]: ...
def create_filter(
    self,
    name: str = None,
    description: str = None,
    jql: str = None,
    favourite: bool = None
) -> Filter: ...
def dashboards(
    self,
    filter: str = None,
    startAt: int = 0,
    maxResults: int = 20
) -> list[Dashboard]: ...

Filters & Dashboards

Remote Links

Manage external links from JIRA issues to external applications, web resources, and other systems.

def remote_links(self, issue: Issue) -> list[RemoteLink]: ...
def add_remote_link(
    self,
    issue: Issue,
    destination: dict,
    globalId: str = None,
    application: dict = None,
    relationship: str = None
) -> RemoteLink: ...
def add_simple_link(self, issue: Issue, object: dict) -> RemoteLink: ...

Remote Links

System Operations & Administration

Administrative and system-level operations including server information, session management, backup, reindexing, and application configuration.

def server_info(self) -> dict: ...
def myself(self) -> User: ...
def reindex(self, force: bool = False, background: bool = True): ...
def backup(self, filename: str = 'backup.zip', attachments: bool = False): ...
def application_properties(self, key: str = None) -> dict: ...
def session(self, auth: tuple = None) -> dict: ...
def my_permissions(
    self,
    projectKey: str = None,
    projectId: str = None,
    issueKey: str = None,
    issueId: str = None
) -> dict: ...

System Operations & Administration

Types

Core types used throughout the API:

class Issue:
    """JIRA issue resource with update/delete capabilities."""
    def update(
        self,
        fields: dict = None,
        update: dict = None,
        async_: bool = None,
        jira: JIRA = None,
        notify: bool = True,
        **fieldargs
    ): ...
    def delete(self, deleteSubtasks: bool = False): ...
    def permalink(self) -> str: ...

class Project:
    """JIRA project resource."""
    pass

class Priority:
    """JIRA issue priority resource."""
    pass

class Role:
    """JIRA project role resource with user management capabilities."""
    def update(self, users: list = None, groups: list = None): ...
    def add_user(self, users: list = None, groups: list = None): ...

class User:
    """JIRA user resource."""
    pass

class Watchers:
    """JIRA issue watchers resource with removal capability."""
    def delete(self, username: str): ...

class Comment:
    """Issue comment resource with update capability."""
    def update(
        self,
        fields: dict = None,
        async_: bool = None,
        jira: JIRA = None,
        body: str = '',
        visibility: dict = None
    ): ...

class Worklog:
    """Work log entry resource with delete capability."""
    def delete(
        self,
        adjustEstimate: str = None,
        newEstimate: str = None,
        increaseBy: str = None
    ): ...

class Attachment:
    """File attachment resource with content access."""
    def get(self) -> str: ...
    def iter_content(self, chunk_size: int = 1024): ...

class Filter:
    """JIRA filter resource for saved searches."""
    pass

class Dashboard:
    """JIRA dashboard resource."""
    pass

class RemoteLink:
    """Remote link resource connecting issues to external systems."""
    pass

class Board:
    """Agile board resource for scrum/kanban boards."""
    pass

class Sprint:
    """Agile sprint resource."""
    pass

class Component:
    """Project component resource."""
    pass

class Version:
    """Project version resource."""
    pass

class IssueType:
    """Issue type resource."""
    pass

class Resolution:
    """Issue resolution resource."""
    pass

class Status:
    """Issue status resource."""
    pass

class IssueLink:
    """Link between two issues."""
    pass

class IssueLinkType:
    """Type of link between issues."""
    pass

class SecurityLevel:
    """Security level resource."""
    pass

class CustomFieldOption:
    """Custom field option resource."""
    pass

class Votes:
    """Issue votes resource."""
    pass

class Customer:
    """Service Desk customer resource."""
    pass

class ServiceDesk:
    """Service Desk resource."""
    pass

class RequestType:
    """Service Desk request type resource."""
    pass

class JIRAError(Exception):
    """Exception raised for JIRA API errors."""
    def __init__(
        self,
        status_code: int = None,
        text: str = None,
        url: str = None,
        request = None,
        response = None,
        **kwargs
    ): ...

Configuration function:

def get_jira(
    profile: str = None,
    url: str = "http://localhost:2990",
    username: str = "admin",
    password: str = "admin",
    appid: str = None,
    autofix: bool = False,
    verify: bool = True
) -> JIRA:
    """Return a JIRA object by loading connection details from config file."""

Version constants:

__version__: str
"""Version string of the JIRA library (e.g., '2.0.0')."""

version_info: tuple
"""Version information tuple containing version components."""