Skip to main content

PyPI version Python Development Status Maintenance PyPI License


Python JIRA Plus

An enhanced Python client for JIRA that extends the functionality of the official jira package, providing better error handling, pagination, metadata validation, and more.


Features

  • ✅ Simplified connection to JIRA Cloud and On-Premise instances
  • ✅ Clear error handling: failures raise (raise_on_error=True) or are logged and returned as None/False. Rate limits (429) and 503 are retried by jira-python itself
  • ✅ Built-in pagination for large result sets
  • ✅ Field validation against JIRA metadata
  • ✅ Enhanced issue creation, retrieval, and updating
  • ✅ Support for allowed values validation

Installation

pip install python-jira-plus

Requirements

  • Python 3.12+
  • jira package
  • custom-python-logger package

Configuration

The package uses environment variables for authentication and configuration:

# Required environment variables
JIRA_USER_NAME=your_jira_username
JIRA_TOKEN=your_jira_api_token
JIRA_BASE_URL=your-instance.atlassian.net  # Only used if base_url is not provided to constructor

Error handling

By default, write helpers (delete_issue, create_link, transition_issue, upload_attachment, update_issue) and get_issue_by_key log the error and return False/None. Pass raise_on_error=True to the constructor to get the original exception instead:

jira_client = JiraCloud(raise_on_error=True)
jira_client.get_issue_by_key("PROJ-404")  # raises JIRAError instead of returning None

Validation problems (ValueError) and failed searches (JIRAError) are always raised. Rate limits (429) and 503 are retried by jira-python's own session, not by this package.

Examples

Creating an Issue with Custom Fields

from python_jira_plus import JiraCloud  # or JiraOnPremise

jira_client = JiraCloud()
issue = jira_client.create_issue(
    project_key="PROJ",
    summary="Implement new feature",
    description="This feature will improve performance",
    issue_type="Task",
    custom_fields={
        "priority": "Critical",  # Priority
        "customfield_10003": {"name": "Sprint 1"}  # Sprint
    }
)

Searching for Issues

from python_jira_plus import JiraCloud

jira_client = JiraCloud()
issues = jira_client.get_objects_by_query(
    query="project = PROJ AND status = 'In Progress' ORDER BY created DESC",
    max_results=50,  # page size
    limit=200,  # optional cap on the total number of issues returned
    specific_fields=["summary", "status", "assignee"],
    json_result=False
)

for issue in issues:
    print(f"{issue.key}: {issue.fields.summary} - {issue.fields.status.name}")

Updating an Issue

from python_jira_plus import JiraCloud

jira_client = JiraCloud()
issue = jira_client.get_issue_by_key(key="PROJ-123", json_result=False)

fields_to_update = {
    "summary": "Updated summary",
    "description": "Updated description",
    "customfield_10003": {"name": "Sprint 2"},  # Update Sprint
}
_ = jira_client.update_issue(
    issue_key=issue.key,
    fields_to_update=fields_to_update
)

🤝 Contributing

If you have a helpful tool, pattern, or improvement to suggest: Fork the repo
Create a new branch
Submit a pull request
I welcome additions that promote clean, productive, and maintainable development.


🙏 Thanks

Thanks for exploring this repository!
Happy coding!

Metadata

Release files for python-jira-plus 4.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for python-jira-plus 4.1.0
File Size Uploaded Provenance Actions
python_jira_plus-4.1.0.tar.gz 23.8 kB Without provenance Details for python_jira_plus-4.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for python-jira-plus 4.1.0
File Interpreter ABI Platform Actions
python_jira_plus-4.1.0-py3-none-any.whl Python 3 none any Details for python_jira_plus-4.1.0-py3-none-any.whl

Total release size: 38.2 kB

Release files / python_jira_plus-4.1.0.tar.gz

Download URL python_jira_plus-4.1.0.tar.gz
Size 23.8 kB
Tags Source
SHA-256 checksum
How to use checksums
71086f880b1e7715b88f55b49915d1e72eb46a0ee2f71c073c420de2a5030a20
BLAKE2b-256 checksum
How to use checksums
fb0c5e4142f77bb55ac1641cfe50f44d1e67f004226574f081feddd9ba00db59
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / python_jira_plus-4.1.0-py3-none-any.whl

Download URL python_jira_plus-4.1.0-py3-none-any.whl
Size 14.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
91d362f095ab908955a7399698d81973b49fc4d6f6e9ecebbfb24a0861754f19
BLAKE2b-256 checksum
How to use checksums
450e69f44a63f22472ab591cef98a754d279bd697f15d6cf3994fd080c5795cb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for python-jira-plus 4.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

4.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page