Skip to content

Module yajaw.jira

Basic import statement for the module is:

from yajaw import jira

Module description

Module wrapping up the supported Jira resources. It is the main external interface for yajaw users.

async_fetch_all_projects(expand=None) async

Async call to fetch all projects.

It is intended to be used on asynchronous code. Use the sync version otherwise. Returns all projects visible to the user. It is based on the API GET /rest/api/2/project. That resource is deprecated and will be replaced by GET /rest/api/2/project/search, which will support pagination.

Parameters:

Name Type Description Default
expand str | None

Expect a simple string with a comma-separated list of attributes to be expanded. They are: description, issueTypes, lead, and projectKeys.

 None

Returns:

Type Description
list[dict]

List of dictionaries representing the returned projects. An empty list is returned if nothing found.
Source code in yajaw/jira.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
async def async_fetch_all_projects(expand: str | None = None) -> list[dict]:
    """
    Async call to fetch all projects.

    It is intended to be used on asynchronous code. Use the sync version otherwise.
    Returns all projects visible to the user. It is based on the API
    GET /rest/api/2/project. That resource is deprecated and will be replaced
    by GET /rest/api/2/project/search, which will support pagination.


    Args:
        expand (str | None, optional): Expect a simple string with a comma-separated\
        list of attributes to be expanded.\
        They are: description, issueTypes, lead, and projectKeys.

    Returns:
        List of dictionaries representing the returned projects.\
        An empty list is returned if nothing found.
    """
    expand_dict = {} if expand is None else {"expand": expand}

    jira = rest.JiraInfo(
        method="GET",
        resource="project",
        api=YajawConfig.SERVER_API,
        params=expand_dict,
        payload=None,
    )

    try:
        response = await rest.send_single_request(jira=jira)
        return response.json()
    except e.ResourceNotFoundError:
        return []

async_fetch_issue(issue_key, expand=None, api=ApiType.CLASSIC) async

Async call to fetch the details of a single issue.

It is intended to be used on asynchronous code. Use the sync version otherwise. Return the details of a single issue. It is based on the API GET /rest/api/2/issue/{issueKey}. If the identifier doesn't match an issue, a case-insensitive search and check for moved issues is performed. If a matching issue is found its details are returned.

Parameters:

Name Type Description Default
issue_key str

Key identifier for the issue.

 required
expand str | None

Expect a simple string with a comma-separated list of attributes to be expanded. They are: renderedFields, name, schema, transitions,editmeta, changelog, and versionedRepresentations. Defaults to None.

 None
api ApiType

Takes the enumeration values ApiType.CLASSIC or ApiType.AGILE as possible values to represent which API to be used. Defaults to ApiType.CLASSIC.

 CLASSIC

Returns:

Type Description
dict

Dictionary with the issue details. An empty dictionary is returned if nothing is found.
Source code in yajaw/jira.py 
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
async def async_fetch_issue(
    issue_key: str, expand: str | None = None, api: ApiType = ApiType.CLASSIC
) -> dict:
    """
    Async call to fetch the details of a single issue.

    It is intended to be used on asynchronous code. Use the sync version otherwise.
    Return the details of a single issue. It is based on the API
    GET /rest/api/2/issue/{issueKey}. If the identifier doesn't match an issue,
    a case-insensitive search and check for moved issues is performed.
    If a matching issue is found its details are returned.

    Args:
        issue_key (str):  Key identifier for the issue.
        expand (str | None, optional): Expect a simple string with a comma-separated\
        list of attributes to be expanded. They are: renderedFields, name, schema,\
        transitions,editmeta, changelog, and versionedRepresentations.\
        Defaults to None.
        api (ApiType, optional): Takes the enumeration values ApiType.CLASSIC or\
        ApiType.AGILE as possible values to represent which API to be used. Defaults\
        to ApiType.CLASSIC.

    Returns:
        Dictionary with the issue details. An empty dictionary is returned\
        if nothing is found.
    """
    expand_dict = {} if expand is None else {"expand": expand}

    api_value = YajawConfig.SERVER_API if api == ApiType.CLASSIC else YajawConfig.AGILE_API

    jira = rest.JiraInfo(
        method="GET", resource=f"issue/{issue_key}", api=api_value, params=expand_dict, payload=None
    )

    try:
        response = await rest.send_single_request(jira=jira)
        return response.json()
    except e.ResourceNotFoundError:
        return {}

async_fetch_project(project_key, expand=None) async

Async call to fetch the details of a single project.

It is intended to be used on asynchronous code. Use the sync version otherwise. Return the details of a single project. It is based on the API GET /rest/api/2/project/{projectKey}.

Parameters:

Name Type Description Default
project_key str

Key identifier for the project.

 required
expand str | None

Expect a simple string with a comma-separated list of attributes to be expanded. They are: description, issueTypes, lead, projectKeys, and issueTypeHierarchy. Defaults to None.

 None

Returns:

Type Description
dict

Dictionary with the project details. An empty dictionary is returned if nothing is found.
Source code in yajaw/jira.py 
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
async def async_fetch_project(project_key: str, expand: str | None = None) -> dict:
    """
    Async call to fetch the details of a single project.

     It is intended to be used on asynchronous code. Use the sync version otherwise.
     Return the details of a single project. It is based on the API
     GET /rest/api/2/project/{projectKey}.

    Args:
        project_key (str): Key identifier for the project.
        expand (str | None, optional): Expect a simple string with a comma-separated\
        list of attributes to be expanded. They are: description, issueTypes, lead,\
        projectKeys, and issueTypeHierarchy. Defaults to None.

    Returns:
        Dictionary with the project details. An empty dictionary is returned\
        if nothing is found.
    """
    expand_dict = {} if expand is None else {"expand": expand}

    jira = rest.JiraInfo(
        method="GET",
        resource=f"project/{project_key}",
        api=YajawConfig.SERVER_API,
        params=expand_dict,
        payload=None,
    )

    try:
        response = await rest.send_single_request(jira=jira)
        return response.json()
    except e.ResourceNotFoundError:
        return {}

async_fetch_projects_from_list(project_keys, expand=None) async

Async call to fetch the details of a list of projects.

It is intended to be used on asynchronous code. Use the sync version otherwise. Return the details of a list of projects. It is based on the API GET /rest/api/2/project/{projectKey} and the function calls it as many times as items in the provided list.

Parameters:

Name Type Description Default
project_keys list[str]

A list of strings representing the project keys.

 required
expand str | None

Expect a simple string with a comma-separated list of attributes to be expanded. They are: description, issueTypes, lead, projectKeys, and issueTypeHierarchy. Defaults to None.

 None

Returns:

Type Description
list[dict]

List of dictionaries representing the returned projects. An empty list is returned if nothing found.
Source code in yajaw/jira.py 
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
async def async_fetch_projects_from_list(
    project_keys: list[str], expand: str | None = None
) -> list[dict]:
    """
    Async call to fetch the details of a list of projects.

    It is intended to be used on asynchronous code. Use the sync version otherwise.
    Return the details of a list of projects. It is based on the API
    GET /rest/api/2/project/{projectKey} and the function calls it as many times as
    items in the provided list.

    Args:
        project_keys (list[str]): A list of strings representing the project keys.
        expand (str | None, optional): Expect a simple string with a comma-separated\
        list of attributes to be expanded. They are: description, issueTypes, lead,\
        projectKeys, and issueTypeHierarchy. Defaults to None.

    Returns:
        List of dictionaries representing the returned projects.\
        An empty list is returned if nothing found.
    """
    expand_dict = {} if expand is None else {"expand": expand}

    jira_list = [
        rest.JiraInfo(
            method="GET",
            resource=f"project/{project_key}",
            api=YajawConfig.SERVER_API,
            params=expand_dict,
            payload=None,
        )
        for project_key in project_keys
    ]

    try:
        tasks = [asyncio.create_task(rest.send_single_request(jira=jira)) for jira in jira_list]
        responses = await asyncio.gather(*tasks)
        return [response.json() for response in responses]
    except e.ResourceNotFoundError:
        return []

async_search_issues(jql, expand=None) async

Async call to fetch the result of a search for issues using JQL.

It is intended to be used on asynchronous code. Use the sync version otherwise. Return the results of a search for issues using the provided JQL. It is based on the API POST /rest/api/2/search.

Parameters:

Name Type Description Default
jql str

A valid Jira Query Language in string format.

 required
expand str | None

Expect a simple string with a comma-separated list of attributes to be expanded. They are: renderedFields, name, schema, transitions, operations, editmeta, changelog, and versionedRepresentations. Defaults to None.

 None

Returns:

Type Description
list[dict]

List of dictionaries representing the returned projects. An empty list is returned if nothing found.
Source code in yajaw/jira.py 
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
async def async_search_issues(jql: str, expand: str | None = None) -> list[dict]:
    """
    Async call to fetch the result of a search for issues using JQL.

    It is intended to be used on asynchronous code. Use the sync version otherwise.
    Return the results of a search for issues using the provided JQL. It is based on
    the API POST /rest/api/2/search.

    Args:
        jql (str): A valid Jira Query Language in string format.
        expand (str | None, optional): Expect a simple string with a comma-separated\
        list of attributes to be expanded. They are: renderedFields, name, schema,\
        transitions, operations, editmeta, changelog, and versionedRepresentations.\
        Defaults to None.

    Returns:
        List of dictionaries representing the returned projects.\
        An empty list is returned if nothing found.
    """
    expand_dict = {} if expand is None else {"expand": expand}
    query = {"jql": jql}

    jira = rest.JiraInfo(
        method="POST",
        resource="search",
        api=YajawConfig.SERVER_API,
        params=expand_dict,
        payload=query,
    )

    try:
        responses = await rest.send_paginated_requests(jira=jira)
        return [issue for issue_page in responses for issue in issue_page.json()["issues"]]
    except e.ResourceNotFoundError:
        return []

fetch_all_projects(expand=None)

Sync call to fetch all projects.

It is intended to be used on synchronous code. Use the async version otherwise. Returns all projects visible to the user. It is based on the API GET /rest/api/2/project. That resource is deprecated and will be replaced by GET /rest/api/2/project/search, which will support pagination.

Parameters:

Name Type Description Default
expand str | None

Expect a simple string with a comma-separated list of attributes to be expanded. They are: description, issueTypes, lead, and projectKeys.

 None

Returns:

Type Description
list[dict]

List of dictionaries representing the returned projects. An empty list is returned if nothing found.
Source code in yajaw/jira.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
@async_to_sync
def fetch_all_projects(expand: str | None = None) -> list[dict]:
    """
    Sync call to fetch all projects.

    It is intended to be used on synchronous code. Use the async version otherwise.
    Returns all projects visible to the user. It is based on the API
    GET /rest/api/2/project. That resource is deprecated and will be replaced
    by GET /rest/api/2/project/search, which will support pagination.


    Args:
        expand (str | None, optional): Expect a simple string with a comma-separated\
        list of attributes to be expanded.\
        They are: description, issueTypes, lead, and projectKeys.

    Returns:
        List of dictionaries representing the returned projects.\
        An empty list is returned if nothing found.
    """
    return async_fetch_all_projects(expand=expand)

fetch_issue(issue_key, expand=None, api=ApiType.CLASSIC)

Sync call to fetch the details of a single issue.

It is intended to be used on synchronous code. Use the async version otherwise. Return the details of a single issue. It is based on the API GET /rest/api/2/issue/{issueKey}. If the identifier doesn't match an issue, a case-insensitive search and check for moved issues is performed. If a matching issue is found its details are returned.

Parameters:

Name Type Description Default
issue_key str

Key identifier for the issue.

 required
expand str | None

Expect a simple string with a comma-separated list of attributes to be expanded. They are: renderedFields, name, schema, transitions,editmeta, changelog, and versionedRepresentations. Defaults to None.

 None
api ApiType

Takes the enumeration values ApiType.CLASSIC or ApiType.AGILE as possible values to represent which API to be used. Defaults to ApiType.CLASSIC.

 CLASSIC

Returns:

Type Description
dict

Dictionary with the issue details. An empty dictionary is returned if nothing is found.
Source code in yajaw/jira.py 
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
@async_to_sync
def fetch_issue(issue_key: str, expand: str | None = None, api: ApiType = ApiType.CLASSIC) -> dict:
    """
    Sync call to fetch the details of a single issue.

    It is intended to be used on synchronous code. Use the async version otherwise.
    Return the details of a single issue. It is based on the API
    GET /rest/api/2/issue/{issueKey}. If the identifier doesn't match an issue,
    a case-insensitive search and check for moved issues is performed.
    If a matching issue is found its details are returned.

    Args:
        issue_key (str):  Key identifier for the issue.
        expand (str | None, optional): Expect a simple string with a comma-separated\
        list of attributes to be expanded. They are: renderedFields, name, schema,\
        transitions,editmeta, changelog, and versionedRepresentations.\
        Defaults to None.
        api (ApiType, optional): Takes the enumeration values ApiType.CLASSIC or\
        ApiType.AGILE as possible values to represent which API to be used. Defaults\
        to ApiType.CLASSIC.

    Returns:
        Dictionary with the issue details. An empty dictionary is returned\
        if nothing is found.
    """
    return async_fetch_issue(issue_key=issue_key, expand=expand, api=api)

fetch_project(project_key, expand=None)

Sync call to fetch the details of a single project.

It is intended to be used on synchronous code. Use the async version otherwise. Return the details of a single project. It is based on the API GET /rest/api/2/project/{projectKey}.

Parameters:

Name Type Description Default
project_key str

Key identifier for the project.

 required
expand str | None

Expect a simple string with a comma-separated list of attributes to be expanded. They are: description, issueTypes, lead, projectKeys, and issueTypeHierarchy. Defaults to None.

 None

Returns:

Type Description
dict

Dictionary with the project details. An empty dictionary is returned if nothing is found.
Source code in yajaw/jira.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
@async_to_sync
def fetch_project(project_key: str, expand: str | None = None) -> dict:
    """
    Sync call to fetch the details of a single project.

     It is intended to be used on synchronous code. Use the async version otherwise.
     Return the details of a single project. It is based on the API
     GET /rest/api/2/project/{projectKey}.

    Args:
        project_key (str): Key identifier for the project.
        expand (str | None, optional): Expect a simple string with a comma-separated\
        list of attributes to be expanded. They are: description, issueTypes, lead,\
        projectKeys, and issueTypeHierarchy. Defaults to None.

    Returns:
        Dictionary with the project details. An empty dictionary is returned\
        if nothing is found.
    """
    return async_fetch_project(project_key=project_key, expand=expand)

fetch_projects_from_list(project_keys, expand=None)

Sync call to fetch the details of a list of projects.

It is intended to be used on synchronous code. Use the async version otherwise. Return the details of a list of projects. It is based on the API GET /rest/api/2/project/{projectKey} and the function calls it as many times as items in the provided list.

Parameters:

Name Type Description Default
project_keys list[str]

A list of strings representing the project keys.

 required
expand str | None

Expect a simple string with a comma-separated list of attributes to be expanded. They are: description, issueTypes, lead, projectKeys, and issueTypeHierarchy. Defaults to None.

 None

Returns:

Type Description
list[dict]

List of dictionaries representing the returned projects. An empty list is returned if nothing found.
Source code in yajaw/jira.py 
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
@async_to_sync
def fetch_projects_from_list(project_keys: list[str], expand: str | None = None) -> list[dict]:
    """
    Sync call to fetch the details of a list of projects.

    It is intended to be used on synchronous code. Use the async version otherwise.
    Return the details of a list of projects. It is based on the API
    GET /rest/api/2/project/{projectKey} and the function calls it as many times as
    items in the provided list.

    Args:
        project_keys (list[str]): A list of strings representing the project keys.
        expand (str | None, optional): Expect a simple string with a comma-separated\
        list of attributes to be expanded. They are: description, issueTypes, lead,\
        projectKeys, and issueTypeHierarchy. Defaults to None.

    Returns:
        List of dictionaries representing the returned projects.\
        An empty list is returned if nothing found.
    """
    return async_fetch_projects_from_list(project_keys=project_keys, expand=expand)

search_issues(jql, expand=None)

Sync call to fetch the result of a search for issues using JQL.

It is intended to be used on synchronous code. Use the async version otherwise. Return the results of a search for issues using the provided JQL. It is based on the API POST /rest/api/2/search.

Parameters:

Name Type Description Default
jql str

A valid Jira Query Language in string format.

 required
expand str | None

Expect a simple string with a comma-separated list of attributes to be expanded. They are: renderedFields, name, schema, transitions, operations, editmeta, changelog, and versionedRepresentations. Defaults to None.

 None

Returns:

Type Description
list[dict]

List of dictionaries representing the returned projects. An empty list is returned if nothing found.
Source code in yajaw/jira.py 
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
@async_to_sync
def search_issues(jql: str, expand: str | None = None) -> list[dict]:
    """
    Sync call to fetch the result of a search for issues using JQL.

    It is intended to be used on synchronous code. Use the async version otherwise.
    Return the results of a search for issues using the provided JQL. It is based on
    the API POST /rest/api/2/search.

    Args:
        jql (str): A valid Jira Query Language in string format.
        expand (str | None, optional): Expect a simple string with a comma-separated\
        list of attributes to be expanded. They are: renderedFields, name, schema,\
        transitions, operations, editmeta, changelog, and versionedRepresentations.\
        Defaults to None.

    Returns:
        List of dictionaries representing the returned projects.\
        An empty list is returned if nothing found.
    """
    return async_search_issues(jql=jql, expand=expand)