0
# JIRA Python Library
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: jira
7
- **Language**: Python
8
- **Installation**: `pip install jira`
9

10
## Core Imports
11

12
```python
13
from jira import JIRA
14
```
15

16
Import specific resource classes:
17

18
```python
19
from jira import JIRA, Issue, Project, User, Comment, Worklog, JIRAError
20
```
21

22
Import configuration helper:
23

24
```python
25
from jira import get_jira
26
```
27

28
Access version information:
29

30
```python
31
from jira import __version__, version_info
32

33
print(f"JIRA library version: {__version__}")
34
print(f"Version tuple: {version_info}")
35
```
36

37
## Basic Usage
38

39
```python
40
from jira import JIRA
41

42
# Connect to JIRA server with basic authentication
43
jira = JIRA(
44
    server='https://your-jira-instance.com',
45
    basic_auth=('username', 'password')
46
)
47

48
# Get current user information
49
user = jira.myself()
50
print(f"Connected as: {user.displayName}")
51

52
# Search for issues using JQL
53
issues = jira.search_issues('project = PROJ AND status = "To Do"', maxResults=10)
54
for issue in issues:
55
    print(f"{issue.key}: {issue.fields.summary}")
56

57
# Create a new issue
58
new_issue = jira.create_issue(
59
    project={'key': 'PROJ'},
60
    summary='New issue from Python',
61
    description='Created using jira-python library',
62
    issuetype={'name': 'Task'}
63
)
64
print(f"Created issue: {new_issue.key}")
65

66
# Add a comment to an issue
67
jira.add_comment(new_issue, 'This is a comment added via Python')
68

69
# Transition an issue
70
transitions = jira.transitions(new_issue)
71
for transition in transitions:
72
    if transition['name'] == 'In Progress':
73
        jira.transition_issue(new_issue, transition['id'])
74
        break
75
```
76

77
## Architecture
78

79
The library is built around the main **JIRA** client class that provides methods for all JIRA operations. Key architectural components:
80

81
- **JIRA Client**: Main interface with 241 methods covering complete JIRA functionality
82
- **Resource Classes**: Object-oriented representations of JIRA entities (Issue, Project, User, etc.) with update/delete capabilities
83
- **Authentication**: Support for Basic Auth, OAuth, JWT, Kerberos, and session-based authentication
84
- **Session Management**: Built-in session handling with retry logic for resilient connections
85
- **Async Support**: Optional asynchronous operations for high-performance applications
86

87
## Capabilities
88

89
### Client Setup & Authentication
90

91
Configuration and authentication options for connecting to JIRA instances, including basic auth, OAuth, JWT, and Kerberos authentication methods.
92

93
```python { .api }
94
class JIRA:
95
    def __init__(
96
        self,
97
        server: str = None,
98
        options: dict = None,
99
        basic_auth: tuple = None,
100
        oauth: dict = None,
101
        jwt: dict = None,
102
        kerberos: bool = False,
103
        kerberos_options: dict = None,
104
        validate: bool = False,
105
        get_server_info: bool = True,
106
        async_: bool = False,
107
        async_workers: int = 5,
108
        logging: bool = True,
109
        max_retries: int = 3,
110
        proxies: dict = None,
111
        timeout: int = None,
112
        auth = None
113
    ): ...
114
```
115

116
[Client Setup & Authentication](./client-setup.md)
117

118
### Issue Management
119

120
Comprehensive issue operations including creation, search, update, transitions, and bulk operations using JQL (JIRA Query Language).
121

122
```python { .api }
123
def search_issues(
124
    self,
125
    jql_str: str,
126
    startAt: int = 0,
127
    maxResults: int = 50,
128
    validate_query: bool = True,
129
    fields: str = None,
130
    expand: str = None,
131
    json_result: bool = None
132
) -> list[Issue]: ...
133

134
def create_issue(self, fields: dict = None, prefetch: bool = True, **fieldargs) -> Issue: ...
135
def issue(self, id: str, fields: str = None, expand: str = None) -> Issue: ...
136
def assign_issue(self, issue: Issue, assignee: str): ...
137
def transition_issue(
138
    self,
139
    issue: Issue,
140
    transition: str,
141
    fields: dict = None,
142
    comment: str = None,
143
    worklog: dict = None,
144
    **fieldargs
145
): ...
146
```
147

148
[Issue Management](./issue-management.md)
149

150
### Project & Component Management
151

152
Project administration including project creation, component management, version control, and role assignment.
153

154
```python { .api }
155
def projects(self) -> list[Project]: ...
156
def project(self, id: str) -> Project: ...
157
def create_project(
158
    self,
159
    key: str,
160
    name: str = None,
161
    assignee: str = None,
162
    type: str = "Software",
163
    template_name: str = None
164
) -> Project: ...
165
def project_components(self, project: str) -> list: ...
166
def create_component(
167
    self,
168
    name: str,
169
    project: str,
170
    description: str = None,
171
    leadUserName: str = None
172
) -> dict: ...
173
```
174

175
[Project & Component Management](./project-management.md)
176

177
### User & Group Management
178

179
User administration including user creation, group management, permissions, and avatar management.
180

181
```python { .api }
182
def user(self, id: str, expand: str = None) -> User: ...
183
def search_users(
184
    self,
185
    user: str,
186
    startAt: int = 0,
187
    maxResults: int = 50,
188
    includeActive: bool = True,
189
    includeInactive: bool = False
190
) -> list[User]: ...
191
def add_user(
192
    self,
193
    username: str,
194
    email: str,
195
    directoryId: int = 1,
196
    password: str = None,
197
    fullname: str = None,
198
    notify: bool = False,
199
    active: bool = True
200
) -> User: ...
201
```
202

203
[User & Group Management](./user-management.md)
204

205
### Comments & Attachments
206

207
Comment management and file attachment operations for issues.
208

209
```python { .api }
210
def add_comment(
211
    self,
212
    issue: Issue,
213
    body: str,
214
    visibility: dict = None,
215
    is_internal: bool = False
216
) -> Comment: ...
217
def comments(self, issue: Issue) -> list[Comment]: ...
218
def add_attachment(
219
    self,
220
    issue: Issue,
221
    attachment: str,
222
    filename: str = None
223
) -> Attachment: ...
224
def attachment(self, id: str) -> Attachment: ...
225
```
226

227
[Comments & Attachments](./comments-attachments.md)
228

229
### Worklogs & Time Tracking
230

231
Work logging and time tracking functionality for issues.
232

233
```python { .api }
234
def add_worklog(
235
    self,
236
    issue: Issue,
237
    timeSpent: str = None,
238
    timeSpentSeconds: int = None,
239
    adjustEstimate: str = None,
240
    newEstimate: str = None,
241
    reduceBy: str = None,
242
    comment: str = None,
243
    started: str = None,
244
    user: str = None
245
) -> Worklog: ...
246
def worklogs(self, issue: Issue) -> list[Worklog]: ...
247
```
248

249
[Worklogs & Time Tracking](./worklogs.md)
250

251
### Agile & Boards
252

253
Agile/Scrum functionality including board management, sprint operations, and backlog management using the GreenHopper API.
254

255
```python { .api }
256
def boards(
257
    self,
258
    startAt: int = 0,
259
    maxResults: int = 50,
260
    type: str = None,
261
    name: str = None
262
) -> list[Board]: ...
263
def create_sprint(
264
    self,
265
    name: str,
266
    board_id: int,
267
    startDate: str = None,
268
    endDate: str = None
269
) -> Sprint: ...
270
def add_issues_to_sprint(self, sprint_id: int, issue_keys: list[str]): ...
271
```
272

273
[Agile & Boards](./agile-boards.md)
274

275
### Service Desk
276

277
JIRA Service Desk functionality for customer request management and service desk operations.
278

279
```python { .api }
280
def create_customer(self, email: str, displayName: str) -> Customer: ...
281
def service_desks(self) -> list[ServiceDesk]: ...
282
def create_customer_request(self, fields: dict = None, prefetch: bool = True, **fieldargs): ...
283
```
284

285
[Service Desk](./service-desk.md)
286

287
### Filters & Dashboards
288

289
Manage saved JQL filters and dashboard operations for organizing and sharing JIRA queries and visualizations.
290

291
```python { .api }
292
def filter(self, id: str) -> Filter: ...
293
def favourite_filters(self) -> list[Filter]: ...
294
def create_filter(
295
    self,
296
    name: str = None,
297
    description: str = None,
298
    jql: str = None,
299
    favourite: bool = None
300
) -> Filter: ...
301
def dashboards(
302
    self,
303
    filter: str = None,
304
    startAt: int = 0,
305
    maxResults: int = 20
306
) -> list[Dashboard]: ...
307
```
308

309
[Filters & Dashboards](./filters-dashboards.md)
310

311
### Remote Links
312

313
Manage external links from JIRA issues to external applications, web resources, and other systems.
314

315
```python { .api }
316
def remote_links(self, issue: Issue) -> list[RemoteLink]: ...
317
def add_remote_link(
318
    self,
319
    issue: Issue,
320
    destination: dict,
321
    globalId: str = None,
322
    application: dict = None,
323
    relationship: str = None
324
) -> RemoteLink: ...
325
def add_simple_link(self, issue: Issue, object: dict) -> RemoteLink: ...
326
```
327

328
[Remote Links](./remote-links.md)
329

330
### System Operations & Administration
331

332
Administrative and system-level operations including server information, session management, backup, reindexing, and application configuration.
333

334
```python { .api }
335
def server_info(self) -> dict: ...
336
def myself(self) -> User: ...
337
def reindex(self, force: bool = False, background: bool = True): ...
338
def backup(self, filename: str = 'backup.zip', attachments: bool = False): ...
339
def application_properties(self, key: str = None) -> dict: ...
340
def session(self, auth: tuple = None) -> dict: ...
341
def my_permissions(
342
    self,
343
    projectKey: str = None,
344
    projectId: str = None,
345
    issueKey: str = None,
346
    issueId: str = None
347
) -> dict: ...
348
```
349

350
[System Operations & Administration](./system-operations.md)
351

352
## Types
353

354
Core types used throughout the API:
355

356
```python { .api }
357
class Issue:
358
    """JIRA issue resource with update/delete capabilities."""
359
    def update(
360
        self,
361
        fields: dict = None,
362
        update: dict = None,
363
        async_: bool = None,
364
        jira: JIRA = None,
365
        notify: bool = True,
366
        **fieldargs
367
    ): ...
368
    def delete(self, deleteSubtasks: bool = False): ...
369
    def permalink(self) -> str: ...
370

371
class Project:
372
    """JIRA project resource."""
373
    pass
374

375
class Priority:
376
    """JIRA issue priority resource."""
377
    pass
378

379
class Role:
380
    """JIRA project role resource with user management capabilities."""
381
    def update(self, users: list = None, groups: list = None): ...
382
    def add_user(self, users: list = None, groups: list = None): ...
383

384
class User:
385
    """JIRA user resource."""
386
    pass
387

388
class Watchers:
389
    """JIRA issue watchers resource with removal capability."""
390
    def delete(self, username: str): ...
391

392
class Comment:
393
    """Issue comment resource with update capability."""
394
    def update(
395
        self,
396
        fields: dict = None,
397
        async_: bool = None,
398
        jira: JIRA = None,
399
        body: str = '',
400
        visibility: dict = None
401
    ): ...
402

403
class Worklog:
404
    """Work log entry resource with delete capability."""
405
    def delete(
406
        self,
407
        adjustEstimate: str = None,
408
        newEstimate: str = None,
409
        increaseBy: str = None
410
    ): ...
411

412
class Attachment:
413
    """File attachment resource with content access."""
414
    def get(self) -> str: ...
415
    def iter_content(self, chunk_size: int = 1024): ...
416

417
class Filter:
418
    """JIRA filter resource for saved searches."""
419
    pass
420

421
class Dashboard:
422
    """JIRA dashboard resource."""
423
    pass
424

425
class RemoteLink:
426
    """Remote link resource connecting issues to external systems."""
427
    pass
428

429
class Board:
430
    """Agile board resource for scrum/kanban boards."""
431
    pass
432

433
class Sprint:
434
    """Agile sprint resource."""
435
    pass
436

437
class Component:
438
    """Project component resource."""
439
    pass
440

441
class Version:
442
    """Project version resource."""
443
    pass
444

445
class IssueType:
446
    """Issue type resource."""
447
    pass
448

449
class Resolution:
450
    """Issue resolution resource."""
451
    pass
452

453
class Status:
454
    """Issue status resource."""
455
    pass
456

457
class IssueLink:
458
    """Link between two issues."""
459
    pass
460

461
class IssueLinkType:
462
    """Type of link between issues."""
463
    pass
464

465
class SecurityLevel:
466
    """Security level resource."""
467
    pass
468

469
class CustomFieldOption:
470
    """Custom field option resource."""
471
    pass
472

473
class Votes:
474
    """Issue votes resource."""
475
    pass
476

477
class Customer:
478
    """Service Desk customer resource."""
479
    pass
480

481
class ServiceDesk:
482
    """Service Desk resource."""
483
    pass
484

485
class RequestType:
486
    """Service Desk request type resource."""
487
    pass
488

489
class JIRAError(Exception):
490
    """Exception raised for JIRA API errors."""
491
    def __init__(
492
        self,
493
        status_code: int = None,
494
        text: str = None,
495
        url: str = None,
496
        request = None,
497
        response = None,
498
        **kwargs
499
    ): ...
500
```
501

502
Configuration function:
503

504
```python { .api }
505
def get_jira(
506
    profile: str = None,
507
    url: str = "http://localhost:2990",
508
    username: str = "admin",
509
    password: str = "admin",
510
    appid: str = None,
511
    autofix: bool = False,
512
    verify: bool = True
513
) -> JIRA:
514
    """Return a JIRA object by loading connection details from config file."""
515
```
516

517
Version constants:
518

519
```python { .api }
520
__version__: str
521
"""Version string of the JIRA library (e.g., '2.0.0')."""
522

523
version_info: tuple
524
"""Version information tuple containing version components."""
525
```