Getting Started
Installation
Ensure you have Python 3.11 or later before installing Yajaw. The package can be installed via pip
using the following command:
Yajaw requires a dedicated configuration directory named .yajaw
, located in your home directory. To ascertain the path to your home directory, run this Python script:
Should the .yajaw
directory be absent, Yajaw will automatically create it and the necessary configuration files on first run. You are still responsible for providing your specific JIRA instance settings.
To configure, navigate to your home directory, open the .yajaw
folder, and edit the yajaw.toml
file. It contains default settings that you'll need to modify:
[jira]
token = "YOUR_PERSONAL_ACCESS_TOKEN"
base_url = "https://your-jira-domain.com"
server_api_v2 = "rest/api/2"
agile_api_v1 = "rest/agile/1.0"
greenhopper_api = "rest/greenhopper/1.0"
[retries]
tries = 10
delay = 0.0
backoff = 2.0
[requests]
timeout = 60
[concurrency]
semaphore_limit = 50
[pagination]
page_results = 40
Adjust the token
and base_url
with the correct values for your JIRA environment. If necessary, these adjustments can also be executed programmatically using the yajaw.configuration
module. For further instructions, refer to the User Guide.
Basic Use
The fundamental use of Yajaw involves importing the yajaw.jira
module and calling one of its functions. For example:
from yajaw import jira
projects = jira.fetch_all_projects()
# Displays <class 'list'>
print(type(projects))
# Displays the type of each accessed project, which is <class 'dict'>
print(*[type(project) for project in projects], sep="\t")
# Ensure to replace "ABC" with a valid project key
project = jira.fetch_project(project_key="ABC")
# Displays <class 'dict'>
print(type(project))
An asynchronous code example for fetching projects can be written as follows:
import asyncio
from yajaw import jira
async def main():
projects = await jira.async_fetch_all_projects()
# Displays <class 'list'>
print(type(projects))
# Displays the type of each accessed project, which is <class 'dict'>
print(*[type(project) for project in projects], sep="\t")
# Ensure to replace "ABC" with a valid project key
project = await jira.async_fetch_project(project_key="ABC")
# Displays <class 'dict'>
print(f"Type: {type(project)}")
asyncio.run(main())
To understand Yajaw's function naming convention, consider the following pattern:
[async_
] + action
+ _
+ target_resource
+ [_from_list
]
Elements of the pattern:
async_
: An optional prefix for asynchronous functions. Omitted in synchronous functions.action
: Represents the operation such asfetch
,create
,update
, ordelete
.target_resource
: Specifies the JIRA resource being accessed._from_list
: When used, it denotes a function operating on each element of a list.
Therefore, a function named async_fetch_projects_from_list
would asynchronously execute async_fetch_project
for every project given, with all calls happening in parallel, outputting a list of dictionaries, each representing a project.