Metadata-Version: 2.4
Name: jira-connector
Version: 1.0.1
Summary: A flexible and powerful Python connector for interacting with Jira API
Home-page: https://github.com/yourusername/jira-connector
Author: Your Name
Author-email: Your Name <your.email@example.com>
Maintainer-email: Your Name <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/jira-connector
Project-URL: Documentation, https://jira-connector.readthedocs.io/
Project-URL: Repository, https://github.com/yourusername/jira-connector
Project-URL: Bug Tracker, https://github.com/yourusername/jira-connector/issues
Project-URL: Changelog, https://github.com/yourusername/jira-connector/blob/main/CHANGELOG.md
Keywords: jira,api,connector,atlassian,issue-tracking,project-management,rest-api,python,library,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Office/Business
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: urllib3>=1.26.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Requires-Dist: responses>=0.23.0; extra == "test"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Generic Jira Connector

A flexible and powerful Python connector for interacting with Jira API. This connector allows you to connect to any Jira instance and dynamically read specified properties from issues.

## Features

- **Generic Design**: Works with any Jira instance (Atlassian Cloud, Jira Server, Jira Data Center)
- **Flexible Authentication**: Supports both Bearer token and basic authentication
- **Dynamic Property Reading**: Extract any Jira issue properties using dot notation
- **Configuration Management**: Built-in support for multiple Jira service configurations
- **Error Handling**: Comprehensive error handling with retry logic
- **Logging**: Detailed logging for debugging and monitoring
- **Environment Variables**: Support for environment-based configuration

## Installation

### Install from PyPI (Recommended)

```bash
pip install jira-connector
```

This will automatically install all required dependencies:
- `requests>=2.31.0`
- `urllib3>=1.26.0`

### Install from Source

```bash
git clone https://github.com/yourusername/jira-connector.git
cd jira-connector
pip install .
```

### Development Installation

```bash
git clone https://github.com/yourusername/jira-connector.git
cd jira-connector
pip install -e .[dev]
```

### Install with Optional Dependencies

```bash
# For development
pip install jira-connector[dev]

# For documentation
pip install jira-connector[docs]

# For testing
pip install jira-connector[test]
```

## Quick Start

### Basic Usage

```python
from jira_connector import JiraConnector

# Initialize connector
connector = JiraConnector(
    jira_url="https://yourcompany.atlassian.net",
    token="your_api_token_here",
    service="my_service"
)

# Test connection
if connector.test_connection():
    print("Connection successful!")
    
    # Get specific issue with custom properties
    properties = [
        'key',
        'fields.summary',
        'fields.status.name',
        'fields.assignee.displayName'
    ]
    
    issue = connector.get_issue("PROJ-123", properties)
    print(issue)

# Close connection
connector.close()
```

### Using Environment Variables

```bash
export JIRA_URL="https://yourcompany.atlassian.net"
export JIRA_TOKEN="your_api_token_here"
export JIRA_USERNAME="your_username"  # Optional
```

```python
import os
from jira_connector import JiraConnector

connector = JiraConnector(
    jira_url=os.getenv('JIRA_URL'),
    token=os.getenv('JIRA_TOKEN'),
    service="my_service",
    username=os.getenv('JIRA_USERNAME')  # Optional
)
```

## API Reference

### JiraConnector Class

#### Initialization Parameters

- `jira_url` (str): Base URL of Jira instance
- `token` (str): API token for authentication
- `service` (str): Service name for logging (default: "jira")
- `username` (str, optional): Username for basic auth
- `timeout` (int): Request timeout in seconds (default: 30)
- `verify_ssl` (bool): Verify SSL certificates (default: True)
- `max_retries` (int): Maximum retry attempts (default: 3)

#### Main Methods

##### Connection Methods
- `test_connection()`: Test connection to Jira
- `close()`: Close the session

##### Issue Methods
- `get_issue(issue_key, properties=None)`: Get issue details
- `search_issues(jql, properties=None, max_results=50, start_at=0)`: Search issues using JQL
- `get_project_issues(project_key, properties=None, max_results=50, start_at=0)`: Get issues from project
- `create_issue(project_key, issue_type, summary, description=None, **fields)`: Create new issue
- `update_issue(issue_key, **fields)`: Update existing issue

##### Comment Methods
- `add_comment(issue_key, comment)`: Add comment to issue

##### Transition Methods
- `get_issue_transitions(issue_key)`: Get available transitions
- `transition_issue(issue_key, transition_id)`: Transition issue to new status

##### Utility Methods
- `get_projects()`: Get all accessible projects
- `get_custom_fields()`: Get all custom fields

### Property Extraction

Use dot notation to extract nested properties:

```python
properties = [
    'key',                                    # Issue key
    'fields.summary',                         # Issue summary
    'fields.status.name',                     # Status name
    'fields.status.statusCategory.name',     # Status category
    'fields.assignee.displayName',           # Assignee name
    'fields.customfield_10010',               # Custom field
    'fields.customfield_10020.value',         # Nested custom field
]
```

## Examples

### Search Issues with JQL

```python
# Find all open bugs in a project
jql = "project = PROJ AND issuetype = Bug AND status != Closed"
issues = connector.search_issues(jql, properties, max_results=100)

# Find issues assigned to me
jql = "assignee = currentUser() AND status = 'In Progress'"
my_issues = connector.search_issues(jql, properties)
```

### Work with Custom Fields

```python
# Get all custom fields
custom_fields = connector.get_custom_fields()

# Use custom field in property extraction
properties = [
    'key',
    'fields.summary',
    'fields.customfield_10010',  # Text field
    'fields.customfield_10020.value',  # Select field
]

issues = connector.search_issues("project = PROJ", properties)
```

### Create and Update Issues

```python
# Create new issue
new_issue = connector.create_issue(
    project_key="PROJ",
    issue_type="Task",
    summary="New task from connector",
    description="Task description",
    priority={"name": "High"},
    labels=["urgent", "backend"]
)

# Update issue
connector.update_issue(
    issue_key="PROJ-123",
    summary="Updated summary",
    priority={"name": "Medium"}
)
```

### Add Comments and Transitions

```python
# Add comment
connector.add_comment("PROJ-123", "Working on this issue")

# Get available transitions
transitions = connector.get_issue_transitions("PROJ-123")

# Transition issue
if transitions:
    transition_id = transitions[0]['id']
    connector.transition_issue("PROJ-123", transition_id)
```

## Environment Variables

### Required
- `JIRA_URL`: Your Jira instance URL
- `JIRA_TOKEN`: Your API token

### Optional
- `JIRA_USERNAME`: Username for basic auth
- `JIRA_TIMEOUT`: Request timeout (default: 30)
- `JIRA_VERIFY_SSL`: Verify SSL certificates (default: true)
- `JIRA_MAX_RETRIES`: Maximum retry attempts (default: 3)

## Error Handling

The connector includes comprehensive error handling:

- **Retry Logic**: Automatic retries for failed requests
- **Logging**: Detailed error messages and debug information
- **Graceful Degradation**: Continues operation even if some requests fail

```python
try:
    issues = connector.search_issues(jql, properties)
except Exception as e:
    print(f"Search failed: {e}")
    # Handle error appropriately
```

## Security Considerations

1. **API Tokens**: Store API tokens securely, don't commit them to version control
2. **Environment Variables**: Use environment variables for sensitive data
3. **SSL Verification**: Keep SSL verification enabled in production
4. **Access Control**: Use tokens with minimal required permissions

## Troubleshooting

### Common Issues

1. **Authentication Failed**
   - Check API token is valid and not expired
   - Verify correct authentication method (token vs basic auth)

2. **SSL Certificate Error**
   - Set `verify_ssl=False` for self-signed certificates (not recommended for production)
   - Check if Jira URL is correct

3. **Permission Denied**
   - Ensure token has required permissions
   - Check user has access to the project/issue

4. **Rate Limiting**
   - Implement delays between requests
   - Use appropriate timeout values

### Debug Logging

Enable debug logging:

```python
import logging
logging.getLogger("JiraConnector").setLevel(logging.DEBUG)
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

This project is licensed under the MIT License.

## Support

For issues and questions:
- Check the troubleshooting section
- Review the example usage in `example_usage.py`
- Create an issue in the repository
