jiratools package¶

Some simple API functions and command-line tools for interaction with JIRA.

jiratools.add_comment()[source]¶

Quick “add a short comment to a JIRA” command line tool.

If ‘message’ is ‘-‘ then stdin will be read.

Return type: None

jiratools.example_config_install()[source]¶

Build example config.

Return type: None

jiratools.format_as_code_block(text_to_wrap)[source]¶

Wrap the text in a JIRA code block.

Parameters: text_to_wrap (str) – The text to wrap.
Return type: str
Returns: A JIRA formatted code block.

jiratools.jira_link()[source]¶

Link two JIRA from cli.

Return type: None

jiratools.main()[source]¶

Master jiratool command.

Return type: None

jiratools.make_linked()[source]¶

Make a JIRA linked to the given one.

Return type: None

jiratools.reassign()[source]¶

Assign JIRA to given user.

Return type: None

jiratools.search()[source]¶

Perform JQL search and return results.

Return type: None

Submodules¶

jiratools.assignee module¶

Issue Reassignment command.

jiratools.assignee.cli_reassign(jira_id, user)[source]¶

Change issue assignment.

Return type: None

jiratools.comment module¶

Add Comment command.

jiratools.comment.cli_add_comment(jira_id, message)[source]¶

Add comment to issue.

Return type: Comment

jiratools.do_search module¶

Search command.

jiratools.do_search.cli_search(query, max_results, count_only)[source]¶

Search using JQL and return matches.

Return type: None

jiratools.error_logger module¶

Error logging for jiratools.

class jiratools.error_logger.JiraEntry[source]¶

Bases: object

Typing mock for Jira Entry data.

error_message: str¶

jira_id: str¶

jiratools.error_logger.add_jira_comment_with_table(jira_id, data_headers, data_array, msg_prefix='', **format_kwargs)[source]¶

Add a comment to a JIRA with a formatted data table.

Parameters

jira_id (str) – the Issue ID of the JIRA to be updated
data_headers (List[str]) – a list of header column names
data_array (List[List[Union[str, int]]]) –
An array of lists of strings, representing table rows. e.g.:
```
[["a", "b", "c"], ["d", "e", "f"]]
```
**format_kwargs – formatting keyword args to be passed to jiratools.formatting.format_jira_msg

Returns

the Issue ID of the JIRA which received the comment

Return type

str

jiratools.error_logger.add_jira_error_comment(jira_id, error_msg, **format_kwargs)[source]¶

Add a comment to a JIRA with a formatted error message.

Parameters

jira_id (str) – the Issue ID of the JIRA to be updated
error_msg (str) – the raw error message to include in the comment
**format_kwargs – formatting keyword args to be passed to jiratools.formatting.format_jira_msg

Return type

str

Returns

the Issue ID of the JIRA which received the comment

jiratools.error_logger.update_jira_for_errors(jiras, *errors, **format_kwargs)[source]¶

Auto-Update JIRAs if errors are found that match the jira list.

Parameters

jiras (Iterable[JiraEntry]) –
an iterable of objects that each contain two required attributes
- jira_id: the Issue Id of the JIRA to be updated
- error_message: an error message substring which, if found, will trigger and update of the JIRA with the actual error message.
*errors – an error message to be checked against the jiras for a match
**format_kwargs – formatting keyword args to be passed to jiratools.formatting.format_jira_msg

Return type

List[str]

Returns

A list of JIRA Issue IDs that were updated.

jiratools.example_config module¶

Build Example Config.

jiratools.example_config.cli_example_config(install, install_if_missing)[source]¶

Build example config.

Return type: None

jiratools.formatting module¶

Formatting helpers for jiratools.

jiratools.formatting.format_as_jira_table(headers, data_array)[source]¶

Build a JIRA table given headers and row data.

Parameters

headers (List[str]) – a list of header column names
data_array (List[List[Union[str, int]]]) –
An array of lists, representing table rows. e.g.:
```
[["a", "b", "c"], ["d", "e", "f"]]
```

Return type

str

Returns

a formatted JIRA table

jiratools.formatting.format_autoupdate_jira_msg(message_body, header_body=None)[source]¶

Format a JIRA message with useful headers.

An “Automated JIRA Update” title will be added, as well as either a URL link if a BUILD_URL env variable is present, or a note indicating a manual run with user id otherwise.

Parameters

message_body (str) – the body of the message
header_body (Optional[str]) – a header to be added with h2 tag

Return type

str

Returns

a formatted message with headers

jiratools.helpers module¶

A collection of helpers for JIRA commands.

jiratools.helpers.add_comment(jira_id, comment_text)[source]¶

Add a comment to the JIRA ID.

Parameters

jira_id (str) – The JIRA ID to comment on.
comment_text (str) – The text to add as the comment body.

Return type

Comment

Returns

A jira comment.

jiratools.helpers.check_for_valid_user(user)[source]¶

Ensure that a user exists, exit if not found.

Parameters: user (str) – the user id
Return type: None

jiratools.helpers.component_id_from_name(project_components, component_name)[source]¶

Retrive the id of the compoment with the desired name.

Parameters

project_components (List[Component]) – a list of all components associated with a JIRA project
component_name (str) – the name of the desired component

Return type

str

Returns

the id of the matching component

jiratools.helpers.get_issue_by_id(jira_id)[source]¶

Find the JIRA of a given id, or exit if not found.

Parameters: jira_id (str) – the id of the desired JIRA
Return type: Issue
Returns: the issue with the provided id

jiratools.helpers.link_jiras(from_jira, to_jira, relation_type='relates to', client=None)[source]¶

Create a link between two JIRA issues.

Parameters

from_jira (str) – a JIRA issue id
to_jira (str) – a JIRA issue id
relation_type (str) – the type of link relationship
client (Optional[JIRA]) – the instantiated JIRA client

Return type

Response

Returns

the client Response

jiratools.helpers.list_from_config(key_name)[source]¶

Return a list from a comma-separated config file entry.

Parameters: key_name (str) – the name of the key in the config
Return type: List[str]
Returns: a list of string values

jiratools.link module¶

Link JIRAs command.

jiratools.link.cli_jira_link(link_type, from_jira, to_jira)[source]¶

Create JIRA link.

Return type: None

jiratools.make_and_link module¶

Make a linked story command.

jiratools.make_and_link.cli_make_linked(jira_id, project, summary, description, issue_type, user, assign, labels, components, watchers)[source]¶

Build a new story linked to the given one.

Return type: None

jiratools.utils module¶

Basic utility functions for JIRA tools.

exception jiratools.utils.ConfigNotFoundException[source]¶

Bases: Exception

Exception for config failure.

jiratools.utils.get_client()[source]¶

Return a configured JIRA client.

Configured per the user’s home directory jira.config file.

Return type: JIRA

jiratools.utils.load_config()[source]¶

Load CONFIG_FILENAME into CONFIG.

If not already loaded; call before touching CONFIG

Return type: SectionProxy