tessl/pypi-jira

Python library for interacting with JIRA via REST APIs.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

JIRA Python Library

Name: tessl/pypi-jira
Author: tessl

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

Administration & Utilities

Administrative functions, server utilities, dashboard/filter management, system monitoring, batch operations, and configuration management requiring administrative permissions.

def server_info(self) -> dict: ...
def reindex(self, force: bool = False, background: bool = True): ...
def backup(self, filename: str = 'backup.zip', attachments: bool = False): ...
def dashboards(self, filter: str = None, startAt: int = 0, maxResults: int = 20) -> list[Dashboard]: ...
def favourite_filters(self) -> list[Filter]: ...

Administration & Utilities

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."""

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:pypi/jira@2.0.x
Publish Source: CLI
Badge