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