Metadata-Version: 2.4
Name: python-jira-plus
Version: 2.0.4
Summary: Enhanced Python client for JIRA with better error handling, pagination, and metadata validation.
Author: Avi Zaguri
License: MIT
Project-URL: Homepage, https://github.com/aviz92/python-jira-plus
Project-URL: Repository, https://github.com/aviz92/python-jira-plus
Project-URL: Issues, https://github.com/aviz92/python-jira-plus/issues
Keywords: development,jira,atlassian,api,client,python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Classifier: Topic :: System :: Logging
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: custom-python-logger>=2.0.10
Requires-Dist: dotenv>=0.9.9
Requires-Dist: jira>=3.10.5
Requires-Dist: pre-commit>=4.5.0
Requires-Dist: pytest>=9.0.1
Requires-Dist: requests>=2.32.5
Requires-Dist: retrying>=1.4.2
Requires-Dist: setuptools>=80.9.0
Requires-Dist: wheel>=0.45.1
Dynamic: license-file

# 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
- ✅ Robust error handling with automatic retries
- ✅ Built-in pagination for large result sets
- ✅ Field validation against JIRA metadata
- ✅ Enhanced issue creation, retrieval, and updating
- ✅ Support for allowed values validation

---

## Installation
```bash
pip install python-jira-plus
```

---

## Requirements
- Python 3.9+
- `jira` package
- `retrying` package
- `custom-python-logger` package

---

## Configuration
The package uses environment variables for authentication and configuration:

```bash
# 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
```

## Examples

### Creating an Issue with Custom Fields
```python
from python_jira_plus.jira_plus import JiraPlus

jira_client = JiraPlus()
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
```python
from python_jira_plus.jira_plus import JiraPlus

jira_client = JiraPlus()
issues = jira_client.get_objects_by_query(
    query="project = PROJ AND status = 'In Progress' ORDER BY created DESC",
    max_results=50,
    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
```python
from python_jira_plus.jira_plus import JiraPlus

jira_client = JiraPlus()
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 <br>
Create a new branch <br>
Submit a pull request <br>
I welcome additions that promote clean, productive, and maintainable development. <br>

---

## 🙏 Thanks
Thanks for exploring this repository! <br>
Happy coding! <br>
