Quickstart¶

from jira import JIRA

jira = JIRA()

jac = JIRA('https://jira.atlassian.com')

authed_jira = JIRA(basic_auth=('username', 'password'))

# all values are samples and won't work in your code!
key_cert_data = None
with open(key_cert, 'r') as key_cert_file:
    key_cert_data = key_cert_file.read()

oauth_dict = {
    'access_token': 'd87f3hajglkjh89a97f8',
    'access_token_secret': 'a9f8ag0ehaljkhgeds90',
    'consumer_key': 'jira-oauth-consumer',
    'key_cert': key_cert_data
}
authed_jira = JIRA(oauth=oauth_dict)

issue = jira.issue('JRA-1330')

summary = issue.fields.summary         # 'Field level security permissions'
votes = issue.fields.votes.votes       # 440 (at least)

issue = jira.issue('JRA-1330', fields='summary,comment')

# requires issue assign permission, which is different from issue editing permission!
jira.assign_issue(issue, 'newassignee')

new_issue = jira.create_issue(project='PROJ_key_or_id', summary='New issue from jira-python',
                              description='Look into this one', issuetype={'name': 'Bug'})

issue_dict = {
    'project': {'id': 123},
    'summary': 'New issue from jira-python',
    'description': 'Look into this one',
    'issuetype': {'name': 'Bug'},
}
new_issue = jira.create_issue(fields=issue_dict)

issue.update(summary='new summary', description='A new summary was added')
issue.update(assignee={'name': 'new_user'})    # reassigning in update requires issue edit permission

issue.update(fields={'summary': 'new summary', 'description': 'A new summary was added'})

issue.delete()

existingComponents = []
for component in issue.fields.components:
    existingComponents.append({"name" : component.name})
issue.update(fields={"components": existingComponents})

issues_in_proj = jira.search_issues('project=PROJ')
all_proj_issues_but_mine = jira.search_issues('project=PROJ and assignee != currentUser()')

# my top 5 issues due by the end of the week, ordered by priority
oh_crap = jira.search_issues('assignee = currentUser() and due < endOfWeek() order by priority desc', maxResults=5)

# Summaries of my last 3 reported issues
print [issue.fields.summary for issue in jira.search_issues('reporter = currentUser() order by created desc', maxResults=3)]

comments_a = issue.fields.comments.comments
comments_b = jira.comments(issue) # comments_b == comments_a

comment = jira.comment('JRA-1330', '10234')

comment = jira.add_comment('JRA-1330', 'new comment')    # no Issue object required
comment = jira.add_comment(issue, 'new comment', visibility={'type': 'role', 'value': 'Administrators'})  # for admins only

comment.update(body = 'updated comment body')
comment.delete()

issue = jira.issue('PROJ-1')
transitions = jira.transitions(issue)
[(t['id'], t['name']) for t in transitions]    # [(u'5', u'Resolve Issue'), (u'2', u'Close Issue')]

# Resolve the issue and assign it to 'pm_user' in one step
jira.transition_issue(issue, '5', assignee={'name': 'pm_user'}, resolution={'id': '3'})

# The above line is equivalent to:
jira.transition_issue(issue, '5', fields: {'assignee':{'name': 'pm_user'}, 'resolution':{'id': '3'}})

projects = jira.projects()

jra = jira.project('JRA')
print jra.name                 # 'JIRA'
print jira.lead.displayName    # 'Paul Slade [Atlassian]'

components = jira.project_components(jra)
[c.name for c in components]                # 'Accessibility', 'Activity Stream', 'Administration', etc.

jira.project_roles(jra)                     # 'Administrators', 'Developers', etc.

versions = jira.project_versions(jra)
[v.name for v in reversed(versions)]        # '5.1.1', '5.1', '5.0.7', '5.0.6', etc.

Examples¶

Here’s a quick usage example:

# This script shows how to use the client in anonymous mode
# against jira.atlassian.com.

from jira import JIRA

# By default, the client will connect to a JIRA instance started from the Atlassian Plugin SDK
# (see https://developer.atlassian.com/display/DOCS/Installing+the+Atlassian+Plugin+SDK for details).
# Override this with the options parameter.
options = {
    'server': 'https://jira.atlassian.com'
}
jira = JIRA(options)

# Get all projects viewable by anonymous users.
projects = jira.projects()

# Sort available project keys, then return the second, third, and fourth keys.
keys = sorted([project.key for project in projects])[2:5]

# Get an issue.
issue = jira.issue('JRA-1330')

# Find all comments made by Atlassians on this issue.
import re
atl_comments = [comment for comment in issue.fields.comment.comments
                if re.search(r'@atlassian.com$', comment.author.emailAddress)]

# Add a comment to the issue.
jira.add_comment(issue, 'Comment text')

# Change the issue's summary and description.
issue.update(
    summary="I'm different!", description='Changed the summary to be different.')

# You can update the entire labels field like this
issue.update(labels=['AAA', 'BBB'])

# Or modify the List of existing labels. The new label is unicode with no
# spaces
issue.fields.labels.append(u'new_text')
issue.update(fields={"labels": issue.fields.labels})

# Send the issue away for good.
issue.delete()

# Linking a remote jira issue (needs applinks to be configured to work)
issue = jira.issue('JRA-1330')
issue2 = jira2.issue('XX-23')
jira.add_remote_link(issue, issue2)

Another example shows how to authenticate with your JIRA username and password:

# This script shows how to connect to a JIRA instance with a
# username and password over HTTP BASIC authentication.

from jira import JIRA

# By default, the client will connect to a JIRA instance started from the Atlassian Plugin SDK.
# See
# https://developer.atlassian.com/display/DOCS/Installing+the+Atlassian+Plugin+SDK
# for details.
jira = JIRA(basic_auth=('admin', 'admin'))    # a username/password tuple

# Get the mutable application properties for this server (requires
# jira-system-administrators permission)
props = jira.application_properties()

# Find all issues reported by the admin
issues = jira.search_issues('assignee=admin')

# Find the top three projects containing issues reported by admin
from collections import Counter
top_three = Counter(
    [issue.fields.project.key for issue in issues]).most_common(3)

This example shows how to work with GreenHopper:

# This script shows how to use the client in anonymous mode
# against jira.atlassian.com.
from six import print_ as print

from jira.client import GreenHopper

# By default, the client will connect to a JIRA instance started from the Atlassian Plugin SDK
# (see https://developer.atlassian.com/display/DOCS/Installing+the+Atlassian+Plugin+SDK for details).
# Override this with the options parameter.
# GreenHopper is a plugin in a JIRA instance
options = {
    'server': 'https://jira.atlassian.com'
}
gh = GreenHopper(options)

# Get all boards viewable by anonymous users.
boards = gh.boards()

# Get the sprints in a specific board
board_id = 441
print("GreenHopper board: %s (%s)" % (boards[0].name, board_id))
sprints = gh.sprints(board_id)

# List the incomplete issues in each sprint
for sprint in sprints:
    sprint_id = sprint.id
    print("Sprint: %s" % sprint.name)
    incompleted_issues = gh.incompleted_issues(board_id, sprint_id)
    print("Incomplete issues: %s" %
          ', '.join(issue.key for issue in incompleted_issues))

jirashell¶

There is no substitute for play. The only way to really know a service, an API or a package is to explore it, poke at it, and bang your elbows – trial and error. A REST design is especially well-suited to active exploration, and the jirashell script (installed automatically when you use pip) is designed to help you do exactly that.

Run it from the command line:

$ jirashell -s http://jira.atlassian.com
<JIRA Shell (http://jira.atlassian.com)>

*** JIRA shell active; client is in 'jira'. Press Ctrl-D to exit.

In [1]:

This is a specialized Python interpreter (built on IPython) that lets you explore JIRA as a service. Any legal Python code is acceptable input. The shell builds a JIRA client object for you (based on the launch parameters) and stores it in the jira object.

Try getting an issue:

In [1]: issue = jira.issue('JRA-1330')

issue now contains a reference to an issue Resource. To see the available properties and methods, hit the TAB key:

In [2]: issue.
issue.delete  issue.fields  issue.id      issue.raw     issue.update
issue.expand  issue.find    issue.key     issue.self

In [2]: issue.fields.
issue.fields.aggregateprogress              issue.fields.customfield_11531
issue.fields.aggregatetimeestimate          issue.fields.customfield_11631
issue.fields.aggregatetimeoriginalestimate  issue.fields.customfield_11930
issue.fields.aggregatetimespent             issue.fields.customfield_12130
issue.fields.assignee                       issue.fields.customfield_12131
issue.fields.attachment                     issue.fields.description
issue.fields.comment                        issue.fields.environment
issue.fields.components                     issue.fields.fixVersions
issue.fields.created                        issue.fields.issuelinks
issue.fields.customfield_10150              issue.fields.issuetype
issue.fields.customfield_10160              issue.fields.labels
issue.fields.customfield_10161              issue.fields.mro
issue.fields.customfield_10180              issue.fields.progress
issue.fields.customfield_10230              issue.fields.project
issue.fields.customfield_10575              issue.fields.reporter
issue.fields.customfield_10610              issue.fields.resolution
issue.fields.customfield_10650              issue.fields.resolutiondate
issue.fields.customfield_10651              issue.fields.status
issue.fields.customfield_10680              issue.fields.subtasks
issue.fields.customfield_10723              issue.fields.summary
issue.fields.customfield_11130              issue.fields.timeestimate
issue.fields.customfield_11230              issue.fields.timeoriginalestimate
issue.fields.customfield_11431              issue.fields.timespent
issue.fields.customfield_11433              issue.fields.updated
issue.fields.customfield_11434              issue.fields.versions
issue.fields.customfield_11435              issue.fields.votes
issue.fields.customfield_11436              issue.fields.watches
issue.fields.customfield_11437              issue.fields.workratio

Since the Resource class maps the server’s JSON response directly into a Python object with attribute access, you can see exactly what’s in your resources.

Advanced¶

API Documentation¶

class jira.JIRA(server=None, options=None, basic_auth=None, oauth=None, validate=None, async=False, logging=True, max_retries=3)[source]¶

Bases: object

User interface to JIRA.

Clients interact with JIRA by constructing an instance of this object and calling its methods. For addressable resources in JIRA – those with “self” links – an appropriate subclass of Resource will be returned with customized update() and delete() methods, along with attribute access to fields. This means that calls of the form issue.fields.summary will be resolved into the proper lookups to return the JSON value at that mapping. Methods that do not return resources will return a dict constructed from the JSON response or a scalar value; see each method’s documentation for details on what that method returns.

AGILE_BASE_URL = u'{server}/rest/greenhopper/1.0/{path}'¶

DEFAULT_OPTIONS = {u'check_update': True, u'headers': {u'Content-Type': u'application/json', u'X-Atlassian-Token': u'no-check', u'Cache-Control': u'no-cache'}, u'rest_api_version': u'2', u'rest_path': u'api', u'async': False, u'resilient': True, u'verify': True, u'client_cert': None, u'server': u'http://localhost:2990/jira'}¶

JIRA_BASE_URL = u'{server}/rest/api/{rest_api_version}/{path}'¶

add_attachment(*args, **kwargs)[source]¶

Attach an attachment to an issue and returns a Resource for it.

The client will not attempt to open or validate the attachment; it expects a file-like object to be ready for its use. The user is still responsible for tidying up (e.g., closing the file, killing the socket, etc.)

Parameters:	issue – the issue to attach the attachment to attachment – file-like object to attach to the issue, also works if it is a string with the filename. filename – optional name for the attached file. If omitted, the file object’s name attribute is used. If you aquired the file-like object by any other method than open(), make sure that a name is specified in one way or the other.
Return type:	an Attachment Resource

add_comment(*args, **kwargs)[source]¶

Add a comment from the current authenticated user on the specified issue and return a Resource for it. The issue identifier and comment body are required.

Parameters:	issue – ID or key of the issue to add the comment to body – Text of the comment to add visibility – a dict containing two entries: “type” and “value”. “type” is ‘role’ (or ‘group’ if the JIRA server has configured comment visibility for groups) and ‘value’ is the name of the role (or group) to which viewing of this comment will be restricted.

add_group(groupname)[source]¶

Creates a new group in JIRA. :param groupname: The name of the group you wish to create. :return: Boolean - True if succesfull.

add_issues_to_epic(epic_id, issue_keys, ignore_epics=True)[source]¶

Add the issues in issue_keys to the epic_id.

Parameters:	epic_id – the epic to add issues to issue_keys – the issues to add to the epic ignore_epics – ignore any issues listed in issue_keys that are epics

add_issues_to_sprint(sprint_id, issue_keys)[source]¶

Add the issues in issue_keys to the sprint_id. The sprint must be started but not completed.

If a sprint was completed, then have to also edit the history of the issue so that it was added to the sprint before it was completed, preferably before it started. A completed sprint’s issues also all have a resolution set before the completion date.

If a sprint was not started, then have to edit the marker and copy the rank of each issue too.

Parameters:	sprint_id – the sprint to add issues to issue_keys – the issues to add to the sprint

add_remote_link(issue, destination, globalId=None, application=None, relationship=None)[source]¶

Add a remote link from an issue to an external application and returns a remote link Resource for it. object should be a dict containing at least url to the linked external URL and title to display for the link inside JIRA.

For definitions of the allowable fields for object and the keyword arguments globalId, application and relationship, see https://developer.atlassian.com/display/JIRADEV/JIRA+REST+API+for+Remote+Issue+Links.

Parameters:	issue – the issue to add the remote link to destination – the link details to add (see the above link for details) globalId – unique ID for the link (see the above link for details) application – application information for the link (see the above link for details) relationship – relationship description for the link (see the above link for details)

add_user(username, email, directoryId=1, password=None, fullname=None, sendEmail=False, active=True)[source]¶

add_user_to_group(username, group)[source]¶

Adds a user to an existing group. :param username: Username that will be added to specified group. :param group: Group that the user will be added to. :return: Boolean, True for success, false for failure.

add_vote(*args, **kwargs)[source]¶

Register a vote for the current authenticated user on an issue.

Parameters:	issue – ID or key of the issue to vote on

add_watcher(*args, **kwargs)[source]¶

Add a user to an issue’s watchers list.

Parameters:	issue – ID or key of the issue affected watcher – username of the user to add to the watchers list

add_worklog(*args, **kwargs)[source]¶

Add a new worklog entry on an issue and return a Resource for it.

Parameters:

issue – the issue to add the worklog to timeSpent – a worklog entry with this amount of time spent, e.g. “2d” adjustEstimate – (optional) allows the user to provide specific instructions to update the remaining time estimate of the issue. The value can either be new, leave, manual or auto (default). newEstimate – the new value for the remaining estimate field. e.g. “2d” reduceBy – the amount to reduce the remaining estimate by e.g. “2d” started – Moment when the work is logged, if not specified will default to now comment – optional worklog comment

application_properties(key=None)[source]¶

Return the mutable server application properties.

Parameters:	key – the single property to return a value for

applicationlinks(cached=True)[source]¶

List of application links :return: json

assign_issue(*args, **kwargs)[source]¶

Assign an issue to a user. None will set it to unassigned. -1 will set it to Automatic.

Parameters:	issue – the issue to assign assignee – the user to assign the issue to

async_do(size=10)[source]¶

This will execute all async jobs and wait for them to finish. By default it will run on 10 threads.

size: number of threads to run on. :return:

attachment(id)[source]¶

Get an attachment Resource from the server for the specified ID.

attachment_meta()[source]¶

Get the attachment metadata.

backup(filename=u'backup.zip')[source]¶

Will call jira export to backup as zipped xml. Returning with success does not mean that the backup process finished.

boards(*args, **kwargs)[source]¶

Get a list of board GreenHopperResources.

checked_version = False¶

client_info()[source]¶

Get the server this client is connected to.

comment(*args, **kwargs)[source]¶

Get a comment Resource from the server for the specified ID.

Parameters:	issue – ID or key of the issue to get the comment from comment – ID of the comment to get

comments(*args, **kwargs)[source]¶

Get a list of comment Resources.

Parameters:	issue – the issue to get comments from

completedIssuesEstimateSum(board_id, sprint_id)[source]¶

Return the total completed points this sprint.

completed_issues(board_id, sprint_id)[source]¶

Return the completed issues for board_id and sprint_id.

Parameters:	board_id – the board retrieving issues from sprint_id – the sprint retieving issues from

component(id)[source]¶

Get a component Resource from the server.

Parameters:	id – ID of the component to get

component_count_related_issues(id)[source]¶

Get the count of related issues for a component.

Parameters:	id (integer) – ID of the component to use

confirm_project_avatar(*args, **kwargs)[source]¶

Confirm the temporary avatar image previously uploaded with the specified cropping.

After a successful registry with create_temp_project_avatar(), use this method to confirm the avatar for use. The final avatar can be a subarea of the uploaded image, which is customized with the cropping_properties: the return value of create_temp_project_avatar() should be used for this argument.

Parameters:	project – ID or key of the project to confirm the avatar in cropping_properties – a dict of cropping properties from create_temp_project_avatar()

confirm_user_avatar(user, cropping_properties)[source]¶

Confirm the temporary avatar image previously uploaded with the specified cropping.

After a successful registry with create_temp_user_avatar(), use this method to confirm the avatar for use. The final avatar can be a subarea of the uploaded image, which is customized with the cropping_properties: the return value of create_temp_user_avatar() should be used for this argument.

Parameters:	user – the user to confirm the avatar for cropping_properties – a dict of cropping properties from create_temp_user_avatar()

create_board(name, project_ids, preset=u'scrum')[source]¶

Create a new board for the project_ids.

Parameters:	name – name of the board project_ids – the projects to create the board in preset (‘kanban’, ‘scrum’, ‘diy’) – what preset to use for this board

create_component(*args, **kwargs)[source]¶

Create a component inside a project and return a Resource for it.

Parameters:	name – name of the component project – key of the project to create the component in description – a description of the component leadUserName – the username of the user responsible for this component assigneeType – see the ComponentBean.AssigneeType class for valid values isAssigneeTypeValid – boolean specifying whether the assignee type is acceptable

create_filter(name=None, description=None, jql=None, favourite=None)[source]¶

Create a new filter and return a filter Resource for it.

Keyword arguments: name – name of the new filter description – useful human readable description of the new filter jql – query string that defines the filter favourite – whether to add this filter to the current user’s favorites

create_issue(fields=None, prefetch=True, **fieldargs)[source]¶

Create a new issue and return an issue Resource for it.

Each keyword argument (other than the predefined ones) is treated as a field name and the argument’s value is treated as the intended value for that field – if the fields argument is used, all other keyword arguments will be ignored.

By default, the client will immediately reload the issue Resource created by this method in order to return a complete Issue object to the caller; this behavior can be controlled through the ‘prefetch’ argument.

JIRA projects may contain many different issue types. Some issue screens have different requirements for fields in a new issue. This information is available through the ‘createmeta’ method. Further examples are available here: https://developer.atlassian.com/display/JIRADEV/JIRA+REST+API+Example+-+Create+Issue

Parameters:	fields – a dict containing field names and the values to use. If present, all other keyword arguments will be ignored prefetch – whether to reload the created issue Resource so that all of its data is present in the value returned from this method

create_issue_link(*args, **kwargs)[source]¶

Create a link between two issues.

Parameters:

type – the type of link to create inwardIssue – the issue to link from outwardIssue – the issue to link to comment – a comment to add to the issues with the link. Should be a dict containing body and visibility fields: body being the text of the comment and visibility being a dict containing two entries: type and value. type is role (or group if the JIRA server has configured comment visibility for groups) and value is the name of the role (or group) to which viewing of this comment will be restricted.

create_project(key, name=None, assignee=None)[source]¶

Key is mandatory and has to match JIRA project key requirements, usually only 2-10 uppercase characters. If name is not specified it will use the key value. If assignee is not specified it will use current user. The returned value should evaluate to False if it fails otherwise it will be the new project id.

create_sprint(name, board_id, startDate=None, endDate=None)[source]¶

Create a new sprint for the board_id.

Parameters:	name – name of the sprint board_id – the board to add the sprint to

create_temp_project_avatar(*args, **kwargs)[source]¶

Register an image file as a project avatar. The avatar created is temporary and must be confirmed before it can be used.

Avatar images are specified by a filename, size, and file object. By default, the client will attempt to autodetect the picture’s content type: this mechanism relies on libmagic and will not work out of the box on Windows systems (see http://filemagic.readthedocs.org/en/latest/guide.html for details on how to install support). The contentType argument can be used to explicitly set the value (note that JIRA will reject any type other than the well-known ones for images, e.g. image/jpg, image/png, etc.)

This method returns a dict of properties that can be used to crop a subarea of a larger image for use. This dict should be saved and passed to confirm_project_avatar() to finish the avatar creation process. If you want to cut out the middleman and confirm the avatar with JIRA’s default cropping, pass the ‘auto_confirm’ argument with a truthy value and confirm_project_avatar() will be called for you before this method returns.

Parameters:	project – ID or key of the project to create the avatar in filename – name of the avatar file size – size of the avatar file avatar_img – file-like object holding the avatar contentType – explicit specification for the avatar image’s content-type auto_confirm (boolean) – whether to automatically confirm the temporary avatar by calling confirm_project_avatar() with the return value of this method.

create_temp_user_avatar(user, filename, size, avatar_img, contentType=None, auto_confirm=False)[source]¶

Register an image file as a user avatar. The avatar created is temporary and must be confirmed before it can be used.

Avatar images are specified by a filename, size, and file object. By default, the client will attempt to autodetect the picture’s content type: this mechanism relies on libmagic and will not work out of the box on Windows systems (see http://filemagic.readthedocs.org/en/latest/guide.html for details on how to install support). The contentType argument can be used to explicitly set the value (note that JIRA will reject any type other than the well-known ones for images, e.g. image/jpg, image/png, etc.)

This method returns a dict of properties that can be used to crop a subarea of a larger image for use. This dict should be saved and passed to confirm_user_avatar() to finish the avatar creation process. If you want to cut out the middleman and confirm the avatar with JIRA’s default cropping, pass the auto_confirm argument with a truthy value and confirm_user_avatar() will be called for you before this method returns.

Parameters:	user – user to register the avatar for filename – name of the avatar file size – size of the avatar file avatar_img – file-like object containing the avatar contentType – explicit specification for the avatar image’s content-type auto_confirm – whether to automatically confirm the temporary avatar by calling confirm_user_avatar() with the return value of this method.

create_version(*args, **kwargs)[source]¶

Create a version in a project and return a Resource for it.

Parameters:	name – name of the version to create project – key of the project to create the version in description – a description of the version releaseDate – the release date assigned to the version startDate – The start date for the version

createmeta(projectKeys=None, projectIds=[], issuetypeIds=None, issuetypeNames=None, expand=None)[source]¶

Gets the metadata required to create issues, optionally filtered by projects and issue types.

Parameters:

projectKeys – keys of the projects to filter the results with. Can be a single value or a comma-delimited string. May be combined with projectIds. projectIds – IDs of the projects to filter the results with. Can be a single value or a comma-delimited string. May be combined with projectKeys. issuetypeIds – IDs of the issue types to filter the results with. Can be a single value or a comma-delimited string. May be combined with issuetypeNames. issuetypeNames – Names of the issue types to filter the results with. Can be a single value or a comma-delimited string. May be combined with issuetypeIds. expand – extra information to fetch inside each resource.

current_user()[source]¶

custom_field_option(id)[source]¶

Get a custom field option Resource from the server.

Parameters:	id – ID of the custom field to use

dashboard(id)[source]¶

Get a dashboard Resource from the server.

Parameters:	id – ID of the dashboard to get.

dashboards(filter=None, startAt=0, maxResults=20)[source]¶

Return a ResultList of Dashboard resources and a total count.

Parameters:	filter – either “favourite” or “my”, the type of dashboards to return startAt – index of the first dashboard to return maxResults – maximum number of dashboards to return. The total number of results is always available in the total attribute of the returned ResultList.

delete_board(id)[source]¶

Deletes an agile board.

Parameters:	id –
Returns:

delete_project(pid)[source]¶

Project can be id, project key or project name. It will return False if it fails.

delete_project_avatar(*args, **kwargs)[source]¶

Delete a project’s avatar.

Parameters:	project – ID or key of the project to delete the avatar from avatar – ID of the avater to delete

delete_user(username)[source]¶

delete_user_avatar(username, avatar)[source]¶

Delete a user’s avatar.

Parameters:	username – the user to delete the avatar from avatar – ID of the avatar to remove

editmeta(*args, **kwargs)[source]¶

Get the edit metadata for an issue.

Parameters:	issue – the issue to get metadata for

email_user(user, body, title=u'JIRA Notification')[source]¶

TBD:

favourite_filters()[source]¶

Get a list of filter Resources which are the favourites of the currently authenticated user.

fields()[source]¶

Return a list of all issue fields.

filter(id)[source]¶

Get a filter Resource from the server.

Parameters:	id – ID of the filter to get.

find(resource_format, ids=None)[source]¶

Get a Resource object for any addressable resource on the server.

This method is a universal resource locator for any RESTful resource in JIRA. The argument resource_format is a string of the form resource, resource/{0}, resource/{0}/sub, resource/{0}/sub/{1}, etc. The format placeholders will be populated from the ids argument if present. The existing authentication session will be used.

The return value is an untyped Resource object, which will not support specialized Resource.update() or Resource.delete() behavior. Moreover, it will not know to return an issue Resource if the client uses the resource issue path. For this reason, it is intended to support resources that are not included in the standard Atlassian REST API.

Parameters:	resource_format – the subpath to the resource string ids (tuple or None) – values to substitute in the resource_format string

find_transitionid_by_name(issue, transition_name)[source]¶

Get a transitionid available on the specified issue to the current user. Look at https://developer.atlassian.com/static/rest/jira/6.1.html#d2e1074 for json reference

Parameters:	issue – ID or key of the issue to get the transitions from trans_name – iname of transition we are looking for

get_igrid(issueid, customfield, schemeid)[source]¶

group_members(group)[source]¶

Return a hash or users with their information. Requires JIRA 6.0 or will raise NotImplemented.

groups(query=None, exclude=None, maxResults=None)[source]¶

Return a list of groups matching the specified criteria.

Keyword arguments: query – filter groups by name with this string exclude – filter out groups by name with this string maxResults – maximum results to return. defaults to system property jira.ajax.autocomplete.limit (20)

incompleted_issues(board_id, sprint_id)[source]¶

Return the completed issues for the sprint

issue(id, fields=None, expand=None)[source]¶

Get an issue Resource from the server.

Parameters:	id – ID or key of the issue to get fields – comma-separated string of issue fields to include in the results expand – extra information to fetch inside each resource

issue_link(id)[source]¶

Get an issue link Resource from the server.

Parameters:	id – ID of the issue link to get

issue_link_type(id)[source]¶

Get an issue link type Resource from the server.

Parameters:	id – ID of the issue link type to get

issue_link_types()[source]¶

Get a list of issue link type Resources from the server.

issue_type(id)[source]¶

Get an issue type Resource from the server.

Parameters:	id – ID of the issue type to get

issue_types()[source]¶

Get a list of issue type Resources from the server.

kill_session()[source]¶

Destroy the session of the current authenticated user.

kill_websudo()[source]¶

Destroy the user’s current WebSudo session.

move_version(id, after=None, position=None)[source]¶

Move a version within a project’s ordered version list and return a new version Resource for it. One, but not both, of after and position must be specified.

Parameters:	id – ID of the version to move after – the self attribute of a version to place the specified version after (that is, higher in the list) position – the absolute position to move this version to: must be one of First, Last, Earlier, or Later

my_permissions(projectKey=None, projectId=None, issueKey=None, issueId=None)[source]¶

Get a dict of all available permissions on the server.

Parameters:	projectKey – limit returned permissions to the specified project projectId – limit returned permissions to the specified project issueKey – limit returned permissions to the specified issue issueId – limit returned permissions to the specified issue

priorities()[source]¶

Get a list of priority Resources from the server.

priority(id)[source]¶

Get a priority Resource from the server.

Parameters:	id – ID of the priority to get

project(id)[source]¶

Get a project Resource from the server.

Parameters:	id – ID or key of the project to get

project_avatars(*args, **kwargs)[source]¶

Get a dict of all avatars for a project visible to the current authenticated user.

Parameters:	project – ID or key of the project to get avatars for

project_components(*args, **kwargs)[source]¶

Get a list of component Resources present on a project.

Parameters:	project – ID or key of the project to get components from

project_role(*args, **kwargs)[source]¶

Get a role Resource.

Parameters:	project – ID or key of the project to get the role from id – ID of the role to get

project_roles(*args, **kwargs)[source]¶

Get a dict of role names to resource locations for a project.

Parameters:	project – ID or key of the project to get roles from

project_versions(*args, **kwargs)[source]¶

Get a list of version Resources present on a project.

Parameters:	project – ID or key of the project to get versions from

projects()[source]¶

Get a list of project Resources from the server visible to the current authenticated user.

rank(issue, next_issue)[source]¶

Rank an issue before another using the default Ranking field, the one named ‘Rank’.

Parameters:	issue – issue key of the issue to be ranked before the second one. next_issue – issue key of the second issue.

reindex(force=False, background=True)[source]¶

Start jira re-indexing. Returns True if reindexing is in progress or not needed, or False.

If you call reindex() without any parameters it will perform a backfround reindex only if JIRA thinks it should do it.

Parameters:	force – reindex even if JIRA doesn’tt say this is needed, False by default. background – reindex inde background, slower but does not impact the users, defaults to True.

remote_link(*args, **kwargs)[source]¶

Get a remote link Resource from the server.

Parameters:	issue – the issue holding the remote link id – ID of the remote link

remote_links(*args, **kwargs)[source]¶

Get a list of remote link Resources from an issue.

Parameters:	issue – the issue to get remote links from

remove_group(groupname)[source]¶

Deletes a group from the JIRA instance. :param groupname: The group to be deleted from the JIRA instance. :return: Boolean. Returns True on success.

remove_user_from_group(username, groupname)[source]¶

Removes a user from a group. :param username: The user to remove from the group. :param groupname: The group that the user will be removed from. :return:

remove_vote(*args, **kwargs)[source]¶

Remove the current authenticated user’s vote from an issue.

Parameters:	issue – ID or key of the issue to unvote on

remove_watcher(*args, **kwargs)[source]¶

Remove a user from an issue’s watch list.

Parameters:	issue – ID or key of the issue affected watcher – username of the user to remove from the watchers list

rename_user(old_user, new_user)[source]¶

Rename a JIRA user. Current implementation relies on third party plugin but in the future it may use embedded JIRA functionality.

Parameters:	old_user – string with username login new_user – string with username login

resolution(id)[source]¶

Get a resolution Resource from the server.

Parameters:	id – ID of the resolution to get

resolutions()[source]¶

Get a list of resolution Resources from the server.

search_allowed_users_for_issue(user, issueKey=None, projectKey=None, startAt=0, maxResults=50)[source]¶

Get a list of user Resources that match a username string and have browse permission for the issue or project.

Parameters:	user – a string to match usernames against issueKey – find users with browse permission for this issue projectKey – find users with browse permission for this project startAt – index of the first user to return maxResults – maximum number of users to return

search_assignable_users_for_issues(username, project=None, issueKey=None, expand=None, startAt=0, maxResults=50)[source]¶

Get a list of user Resources that match the search string for assigning or creating issues.

This method is intended to find users that are eligible to create issues in a project or be assigned to an existing issue. When searching for eligible creators, specify a project. When searching for eligible assignees, specify an issue key.

Parameters:

username – a string to match usernames against project – filter returned users by permission in this project (expected if a result will be used to create an issue) issueKey – filter returned users by this issue (expected if a result will be used to edit this issue) expand – extra information to fetch inside each resource startAt – index of the first user to return maxResults – maximum number of users to return

search_assignable_users_for_projects(username, projectKeys, startAt=0, maxResults=50)[source]¶

Get a list of user Resources that match the search string and can be assigned issues for projects.

Parameters:	username – a string to match usernames against projectKeys – comma-separated list of project keys to check for issue assignment permissions startAt – index of the first user to return maxResults – maximum number of users to return

search_issues(jql_str, startAt=0, maxResults=50, validate_query=True, fields=None, expand=None, json_result=None)[source]¶

Get a ResultList of issue Resources matching a JQL search string.

Parameters:

jql_str – the JQL search string to use startAt – index of the first issue to return maxResults – maximum number of issues to return. Total number of results is available in the total attribute of the returned ResultList. If maxResults evaluates as False, it will try to get all issues in batches of 50. fields – comma-separated string of issue fields to include in the results expand – extra information to fetch inside each resource

search_users(user, startAt=0, maxResults=50, includeActive=True, includeInactive=False)[source]¶

Get a list of user Resources that match the specified search string.

Parameters:	user – a string to match usernames, name or email against startAt – index of the first user to return maxResults – maximum number of users to return

security_level(id)[source]¶

Get a security level Resource.

Parameters:	id – ID of the security level to get

server_info()[source]¶

Get a dict of server information for this JIRA instance.

session()[source]¶

Get a dict of the current authenticated user’s session information.

set_application_property(key, value)[source]¶

Set the application property.

Parameters:	key – key of the property to set value – value to assign to the property

set_project_avatar(*args, **kwargs)[source]¶

Set a project’s avatar.

Parameters:	project – ID or key of the project to set the avatar on avatar – ID of the avatar to set

set_user_avatar(username, avatar)[source]¶

Set a user’s avatar.

Parameters:	username – the user to set the avatar for avatar – ID of the avatar to set

sprint_info(board_id, sprint_id)[source]¶

Return the information about a sprint.

Parameters:	board_id – the board retrieving issues from sprint_id – the sprint retieving issues from

sprints(*args, **kwargs)[source]¶

Get a list of sprint GreenHopperResources.

Parameters:	id – the board to get sprints from extended – fetch additional information like startDate, endDate, completeDate, much slower because it requires an additional requests for each sprint
Return type:	dict >>> { “id”: 893, >>> “name”: “iteration.5”, >>> “state”: “FUTURE”, >>> “linkedPagesCount”: 0, >>> “startDate”: “None”, >>> “endDate”: “None”, >>> “completeDate”: “None”, >>> “remoteLinks”: [] >>> }

sprints_by_name(id, extended=False)[source]¶

status(id)[source]¶

Get a status Resource from the server.

Parameters:	id – ID of the status resource to get

statuses()[source]¶

Get a list of status Resources from the server.

transition_issue(*args, **kwargs)[source]¶

Perform a transition on an issue.

Each keyword argument (other than the predefined ones) is treated as a field name and the argument’s value is treated as the intended value for that field – if the fields argument is used, all other keyword arguments will be ignored. Field values will be set on the issue as part of the transition process.

Parameters:	issue – ID or key of the issue to perform the transition on transition – ID or name of the transition to perform comment – Optional String to add as comment to the issue when performing the transition. fields – a dict containing field names and the values to use. If present, all other keyword arguments will be ignored

transitions(*args, **kwargs)[source]¶

Get a list of the transitions available on the specified issue to the current user.

Parameters:	issue – ID or key of the issue to get the transitions from id – if present, get only the transition matching this ID expand – extra information to fetch inside each transition

update_sprint(id, name=None, startDate=None, endDate=None)[source]¶

user(id, expand=None)[source]¶

Get a user Resource from the server.

Parameters:	id – ID of the user to get expand – extra information to fetch inside each resource

user_avatars(username)[source]¶

Get a dict of avatars for the specified user.

Parameters:	username – the username to get avatars for

version(id, expand=None)[source]¶

Get a version Resource.

Parameters:	id – ID of the version to get expand – extra information to fetch inside each resource

version_count_related_issues(id)[source]¶

Get a dict of the counts of issues fixed and affected by a version.

Parameters:	id – the version to count issues for

version_count_unresolved_issues(id)[source]¶

Get the number of unresolved issues for a version.

Parameters:	id – ID of the version to count issues for

votes(*args, **kwargs)[source]¶

Get a votes Resource from the server.

Parameters:	issue – ID or key of the issue to get the votes for

watchers(*args, **kwargs)[source]¶

Get a watchers Resource from the server for an issue.

Parameters:	issue – ID or key of the issue to get the watchers for

worklog(*args, **kwargs)[source]¶

Get a specific worklog Resource from the server.

Parameters:	issue – ID or key of the issue to get the worklog from id – ID of the worklog to get

worklogs(*args, **kwargs)[source]¶

Get a list of worklog Resources from the server for an issue.

Parameters:	issue – ID or key of the issue to get worklogs from

class jira.Priority(options, session, raw=None)[source]¶

Bases: jira.resources.Resource

Priority that can be set on an issue.

class jira.Comment(options, session, raw=None)[source]¶

Bases: jira.resources.Resource

An issue comment.

update(fields=None, async=None, jira=None, body=u'', visibility=None)[source]¶

class jira.Worklog(options, session, raw=None)[source]¶

Bases: jira.resources.Resource

Worklog on an issue.

delete(adjustEstimate=None, newEstimate=None, increaseBy=None)[source]¶

Delete this worklog entry from its associated issue.

Parameters:	adjustEstimate – one of new, leave, manual or auto. auto is the default and adjusts the estimate automatically. leave leaves the estimate unchanged by this deletion. newEstimate – combined with adjustEstimate=new, set the estimate to this value increaseBy – combined with adjustEstimate=manual, increase the remaining estimate by this amount

class jira.Watchers(options, session, raw=None)[source]¶

Bases: jira.resources.Resource

Watcher information on an issue.

delete(username)[source]¶

Remove the specified user from the watchers list.

exception jira.JIRAError(status_code=None, text=None, url=None, request=None, response=None, **kwargs)[source]¶

Bases: exceptions.Exception

General error raised for all problems in operation of the client.