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.0.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.0.0
File Size Uploaded Provenance Actions
python_jira_plus-4.0.0.tar.gz 22.3 kB Without provenance Details for python_jira_plus-4.0.0.tar.gz

Built distribution (wheel)

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

Total release size: 35.5 kB

Release files / python_jira_plus-4.0.0.tar.gz

Download URL python_jira_plus-4.0.0.tar.gz
Size 22.3 kB
Tags Source
SHA-256 checksum
How to use checksums
1d91ecfbef52c92837a52149dd0db9dc17c2b201b8e5c62e57dbd55f3cd38d26
BLAKE2b-256 checksum
How to use checksums
88bc193de04b854a52ef14113e0194829f51f421ee52cc0a496fe4b64e70d075
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.0.0-py3-none-any.whl

Download URL python_jira_plus-4.0.0-py3-none-any.whl
Size 13.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9ae8f86536d874f872a559c86d0af8b7b17c0f321d7b6260319e24d4e9733766
BLAKE2b-256 checksum
How to use checksums
385502a84017135654ac5edae1587bd00b84c315ba4bae6a5747951cbee18522
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.0.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.0.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