6. API Documentation¶
Contents
6.1. jira package¶
6.1.1. jira.client module¶
This module implements a friendly (well, friendlier) interface between the raw JSON responses from Jira and the Resource/dict abstractions provided by this library. Users will construct a JIRA object as described below. Full API documentation can be found at: https://jira.readthedocs.io/en/latest/
- jira.client.translate_resource_args(func: Callable)[source]¶
Decorator that converts Issue and Project resources to their keys when used as arguments.
- class jira.client.ResultList(iterable: Optional[collections.abc.Iterable] = None, _startAt: int = 0, _maxResults: int = 0, _total: Optional[int] = None, _isLast: Optional[bool] = None)[source]¶
Bases:
list
,Generic
[jira.client.ResourceType
]
- class jira.client.JiraCookieAuth(session: jira.resilientsession.ResilientSession, session_api_url: str, auth: Tuple[str, str])[source]¶
Bases:
requests.auth.AuthBase
Jira Cookie Authentication
Allows using cookie authentication as described by https://developer.atlassian.com/server/jira/platform/cookie-based-authentication/
- __init__(session: jira.resilientsession.ResilientSession, session_api_url: str, auth: Tuple[str, str])[source]¶
Cookie Based Authentication
- Parameters
session (ResilientSession) – The Session object to communicate with the API.
session_api_url (str) – The session api url to use.
- property cookies¶
- handle_401(response: requests.models.Response, **kwargs)[source]¶
Refresh cookies if the session cookie has expired. Then retry the request.
- process_original_request(original_request: requests.models.PreparedRequest)[source]¶
- update_cookies(original_request: requests.models.PreparedRequest)[source]¶
- send_request(request: requests.models.PreparedRequest)[source]¶
- class jira.client.TokenAuth(token: str)[source]¶
Bases:
requests.auth.AuthBase
Bearer Token Authentication
- class jira.client.JIRA(server: Optional[str] = None, options: Optional[Dict[str, Union[str, bool, Any]]] = None, basic_auth: Optional[Tuple[str, str]] = None, token_auth: Optional[str] = None, oauth: Optional[Dict[str, Any]] = None, jwt: Optional[Dict[str, Any]] = None, kerberos=False, kerberos_options: Optional[Dict[str, Any]] = None, validate=False, get_server_info: bool = True, async_: bool = False, async_workers: int = 5, logging: bool = True, max_retries: int = 3, proxies: Optional[Any] = None, timeout: Optional[Union[float, int, Tuple[float, float]]] = None, auth: Optional[Tuple[str, str]] = None)[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
jira.resources.Resource
will be returned with customizedupdate()
anddelete()
methods, along with attribute access to fields. This means that calls of the formissue.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.Without any arguments, this client will connect anonymously to the Jira instance started by the Atlassian Plugin SDK from one of the ‘atlas-run’,
atlas-debug
, oratlas-run-standalone
commands. By default, this instance runs athttp://localhost:2990/jira
. Theoptions
argument can be used to set the Jira instance to use.Authentication is handled with the
basic_auth
argument. If authentication is supplied (and is accepted by Jira), the client will remember it for subsequent requests.For quick command line access to a server, see the
jirashell
script included with this distribution.The easiest way to instantiate is using
j = JIRA("https://jira.atlassian.com")
- DEFAULT_OPTIONS = {'agile_rest_api_version': '1.0', 'agile_rest_path': 'agile', 'async': False, 'async_workers': 5, 'auth_url': '/rest/auth/1/session', 'check_update': False, 'client_cert': None, 'context_path': '/', 'delay_reload': 0, 'headers': {'Cache-Control': 'no-cache', 'Content-Type': 'application/json', 'X-Atlassian-Token': 'no-check'}, 'resilient': True, 'rest_api_version': '2', 'rest_path': 'api', 'server': 'http://localhost:2990/jira', 'verify': True}¶
- checked_version = False¶
- JIRA_BASE_URL = '{server}/rest/{rest_path}/{rest_api_version}/{path}'¶
- AGILE_BASE_URL = '{server}/rest/{agile_rest_path}/{agile_rest_api_version}/{path}'¶
- __init__(server: Optional[str] = None, options: Optional[Dict[str, Union[str, bool, Any]]] = None, basic_auth: Optional[Tuple[str, str]] = None, token_auth: Optional[str] = None, oauth: Optional[Dict[str, Any]] = None, jwt: Optional[Dict[str, Any]] = None, kerberos=False, kerberos_options: Optional[Dict[str, Any]] = None, validate=False, get_server_info: bool = True, async_: bool = False, async_workers: int = 5, logging: bool = True, max_retries: int = 3, proxies: Optional[Any] = None, timeout: Optional[Union[float, int, Tuple[float, float]]] = None, auth: Optional[Tuple[str, str]] = None)[source]¶
Construct a Jira client instance.
Without any arguments, this client will connect anonymously to the Jira instance started by the Atlassian Plugin SDK from one of the ‘atlas-run’,
atlas-debug
, oratlas-run-standalone
commands. By default, this instance runs athttp://localhost:2990/jira
. Theoptions
argument can be used to set the Jira instance to use.Authentication is handled with the
basic_auth
ortoken_auth
argument. If authentication is supplied (and is accepted by Jira), the client will remember it for subsequent requests.For quick command line access to a server, see the
jirashell
script included with this distribution.The easiest way to instantiate is using
j = JIRA("https://jira.atlasian.com")
- Parameters
server (Optional[str]) – The server address and context path to use. Defaults to
http://localhost:2990/jira
.options (Optional[Dict[str, Any]]) –
Specify the server and properties this client will use. Use a dict with any of the following properties:
server – the server address and context path to use. Defaults to
http://localhost:2990/jira
.rest_path – the root REST path to use. Defaults to
api
, where the Jira REST resources live.rest_api_version – the version of the REST resources under rest_path to use. Defaults to
2
.agile_rest_path - the REST path to use for Jira Agile requests. Defaults to
greenhopper
(old, private API). Checkjira.resources.GreenHopperResource
for other supported values.verify (Union[bool, str]) – Verify SSL certs. Defaults to
True
. Or path to to a CA_BUNDLE file or directory with certificates of trusted CAs, for the requests library to use.client_cert (Union[str, Tuple[str,str]]) – Path to file with both cert and key or a tuple of (cert,key), for the requests library to use for client side SSL.
check_update – Check whether using the newest python-jira library version.
headers – a dict to update the default headers the session uses for all API requests.
basic_auth (Optional[Tuple[str, str]]) – A tuple of username and password to use when establishing a session via HTTP BASIC authentication.
token_auth (Optional[str]) – A string containing the token necessary for (PAT) bearer token authorization.
oauth (Optional[Any]) –
A dict of properties for OAuth authentication. The following properties are required:
access_token – OAuth access token for the user
access_token_secret – OAuth access token secret to sign with the key
consumer_key – key of the OAuth application link defined in Jira
key_cert – private key file to sign requests with (should be the pair of the public key supplied to Jira in the OAuth application link)
kerberos (bool) – If true it will enable Kerberos authentication.
kerberos_options (Optional[Dict[str,str]]) –
A dict of properties for Kerberos authentication. The following properties are possible:
mutual_authentication – string DISABLED or OPTIONAL.
Example kerberos_options structure:
{'mutual_authentication': 'DISABLED'}
jwt (Optional[Any]) –
A dict of properties for JWT authentication supported by Atlassian Connect. The following properties are required:
secret – shared secret as delivered during ‘installed’ lifecycle event (see https://developer.atlassian.com/static/connect/docs/latest/modules/lifecycle.html for details)
payload – dict of fields to be inserted in the JWT payload, e.g. ‘iss’
Example jwt structure:
{'secret': SHARED_SECRET, 'payload': {'iss': PLUGIN_KEY}}
validate (bool) – If true it will validate your credentials first. Remember that if you are accessing Jira as anonymous it will fail to instantiate.
get_server_info (bool) – If true it will fetch server version info first to determine if some API calls are available.
async (bool) – To enable async requests for those actions where we implemented it, like issue update() or delete().
async_workers (int) – Set the number of worker threads for async operations.
timeout (Optional[Union[Union[float, int], Tuple[float, float]]]) – Set a read/connect timeout for the underlying calls to Jira (default: None). Obviously this means that you cannot rely on the return code when this is enabled.
max_retries (int) – Sets the amount Retries for the HTTP sessions initiated by the client. (Default: 3)
proxies (Optional[Any]) – Sets the proxies for the HTTP session.
auth (Optional[Tuple[str,str]]) – Set a cookie auth token if this is required.
logging (bool) – Determine whether or not logging should be enabled. (Default: True)
- find(resource_format: str, ids: Union[Tuple[str, str], int, str] = '') jira.resources.Resource [source]¶
Find Resource object for any addressable resource on the server.
This method is a universal resource locator for any REST-ful resource in Jira. The argument
resource_format
is a string of the formresource
,resource/{0}
,resource/{0}/sub
,resource/{0}/sub/{1}
, etc. The format placeholders will be populated from theids
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()
orResource.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 (str) – the subpath to the resource string
ids (Optional[Tuple]) – values to substitute in the
resource_format
string
- Returns
Resource
- async_do(size: int = 10)[source]¶
Execute all asynchronous jobs and wait for them to finish. By default it will run on 10 threads.
- Parameters
size (int) – number of threads to run on.
- application_properties(key: Optional[str] = None) Union[Dict[str, str], List[Dict[str, str]]] [source]¶
Return the mutable server application properties.
- Parameters
key (Optional[str]) – the single property to return a value for
- Returns
Union[Dict[str, str], List[Dict[str, str]]]
- applicationlinks(cached: bool = True) List [source]¶
List of application links.
- Returns
json, or empty list
- Return type
List[Dict]
- attachment(id: str) jira.resources.Attachment [source]¶
Get an attachment Resource from the server for the specified ID.
- Parameters
id (str) – The Attachment ID
- Returns
Attachment
- add_attachment(issue: str, attachment: Union[str, _io.BufferedReader], filename: str = None) jira.resources.Attachment [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 (str) – the issue to attach the attachment to
attachment (Union[str,BufferedReader]) – file-like object to attach to the issue, also works if it is a string with the filename.
filename (str) – optional name for the attached file. If omitted, the file object’s
name
attribute is used. If you acquired the file-like object by any other method thanopen()
, make sure that a name is specified in one way or the other.
- Returns
Attachment
- delete_attachment(id: str) requests.models.Response [source]¶
Delete attachment by id.
- Parameters
id (str) – ID of the attachment to delete
- Returns
Response
- component(id: str)[source]¶
Get a component Resource from the server.
- Parameters
id (str) – ID of the component to get
- create_component(name: str, project: str, description=None, leadUserName=None, assigneeType=None, isAssigneeTypeValid=False) jira.resources.Component [source]¶
Create a component inside a project and return a Resource for it.
- Parameters
name (str) – name of the component
project (str) – key of the project to create the component in
description (str) – a description of the component
leadUserName (Optional[str]) – the username of the user responsible for this component
assigneeType (Optional[str]) – see the ComponentBean.AssigneeType class for valid values
isAssigneeTypeValid (bool) – boolean specifying whether the assignee type is acceptable (Default: False)
- Returns
Component
Get the count of related issues for a component.
- Parameters
id (str) – ID of the component to use
- delete_component(id: str) requests.models.Response [source]¶
Delete component by id.
- Parameters
id (str) – ID of the component to use
- Returns
Response
- custom_field_option(id: str) jira.resources.CustomFieldOption [source]¶
Get a custom field option Resource from the server.
- Parameters
id (str) – ID of the custom field to use
- Returns
CustomFieldOption
- dashboards(filter=None, startAt=0, maxResults=20) jira.client.ResultList[jira.resources.Dashboard] [source]¶
Return a ResultList of Dashboard resources and a
total
count.- Parameters
filter (Optional[str]) – either “favourite” or “my”, the type of dashboards to return
startAt (int) – index of the first dashboard to return (Default: 0)
maxResults (int) – maximum number of dashboards to return. If maxResults evaluates as False, it will try to get all items in batches. (Default: 20)
- Returns
ResultList
- dashboard(id: str) jira.resources.Dashboard [source]¶
Get a dashboard Resource from the server.
- Parameters
id (str) – ID of the dashboard to get.
- Returns
Dashboard
- fields() List[Dict[str, Any]] [source]¶
Return a list of all issue fields.
- Returns
List[Dict[str, Any]]
- filter(id: str) jira.resources.Filter [source]¶
Get a filter Resource from the server.
- Parameters
id (str) – ID of the filter to get.
- Returns
Filter
- favourite_filters() List[jira.resources.Filter] [source]¶
Get a list of filter Resources which are the favourites of the currently authenticated user.
- Returns
List[Filter]
- create_filter(name: Optional[str] = None, description: Optional[str] = None, jql: Optional[str] = None, favourite: Optional[bool] = None)[source]¶
Create a new filter and return a filter Resource for it.
- update_filter(filter_id, name: Optional[str] = None, description: Optional[str] = None, jql: Optional[str] = None, favourite: Optional[bool] = None)[source]¶
Update a filter and return a filter Resource for it.
- group(id: str, expand: Optional[Any] = None) jira.resources.Group [source]¶
Get a group Resource from the server.
- Parameters
id (str) – ID of the group to get
expand (Optional[Any]) – Extra information to fetch inside each resource
- Returns
Group
- groups(query: Optional[str] = None, exclude: Optional[Any] = None, maxResults: int = 9999) List[str] [source]¶
Return a list of groups matching the specified criteria.
- group_members(group: str) collections.OrderedDict [source]¶
Return a hash or users with their information. Requires Jira 6.0 or will raise NotImplemented.
- Parameters
group (str) – Name of the group.
- issue(id: Union[jira.resources.Issue, str], fields: Optional[str] = None, expand: Optional[str] = None) jira.resources.Issue [source]¶
Get an issue Resource from the server.
- create_issue(fields: Optional[Dict[str, Any]] = None, prefetch: bool = True, **fieldargs) jira.resources.Issue [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
- Returns
Issue
- create_issues(field_list: List[Dict[str, Any]], prefetch: bool = True) List[Dict[str, Any]] [source]¶
Bulk create new issues and return an issue Resource for each successfully created issue.
See create_issue documentation for field information.
- Parameters
field_list (List[Dict[str, Any]]) – a list of dicts each containing field names and the values to use. Each dict is an individual issue to create and is subject to its minimum requirements.
prefetch (bool) – whether to reload the created issue Resource for each created issue so that all of its data is present in the value returned from this method.
- Returns
List[Dict[str, Any]]
- supports_service_desk()[source]¶
Returns whether or not the Jira instance supports service desk.
- Returns
bool
- create_customer(email: str, displayName: str) jira.resources.Customer [source]¶
Create a new customer and return an issue Resource for it.
- service_desks() List[jira.resources.ServiceDesk] [source]¶
Get a list of ServiceDesk Resources from the server visible to the current authenticated user.
- Returns
List[ServiceDesk]
- service_desk(id: str) jira.resources.ServiceDesk [source]¶
Get a Service Desk Resource from the server.
- Parameters
id (str) – ID or key of the Service Desk to get
- Returns
ServiceDesk
- create_customer_request(fields: Dict[str, Any] = None, prefetch: bool = True, **fieldargs) jira.resources.Issue [source]¶
Create a new customer request 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
- createmeta(projectKeys: Optional[Union[Tuple[str, str], str]] = None, projectIds: Union[List, Tuple[str, str]] = [], issuetypeIds: Optional[List[str]] = None, issuetypeNames: Optional[str] = None, expand: Optional[str] = None) Dict[str, Any] [source]¶
Get the metadata required to create issues, optionally filtered by projects and issue types.
- Parameters
projectKeys (Optional[Union[Tuple[str, str], str]]) – 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 (Union[List, Tuple[str, str]]) – 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 (Optional[List[str]]) – 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 (Optional[str]) – 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 (Optional[str]) – extra information to fetch inside each resource.
- Returns
Dict[str, Any]
- assign_issue(issue: Union[int, str], assignee: Optional[str]) bool [source]¶
Assign an issue to a user.
- comments(issue: str, expand: Optional[str] = None) List[jira.resources.Comment] [source]¶
Get a list of comment Resources.
- comment(issue: str, comment: str, expand: Optional[str] = None) jira.resources.Comment [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
expand – extra information to fetch for comment such as renderedBody and properties.
- add_comment(issue: str, body: str, visibility: Optional[Dict[str, str]] = None, is_internal: bool = False) jira.resources.Comment [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 (str) – ID or key of the issue to add the comment to
body (str) – Text of the comment to add
visibility (Optional[Dict[str, str]]) – 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.
is_internal (bool) – Defines whether a comment has to be marked as ‘Internal’ in Jira Service Desk (Default: False)
- Returns
the created comment
- Return type
- editmeta(issue: Union[str, int])[source]¶
Get the edit metadata for an issue.
- Parameters
issue (str) – the issue to get metadata for
- Returns
Dict[str, Dict[str, Dict[str, Any]]]
- remote_links(issue: Union[str, int]) List[jira.resources.RemoteLink] [source]¶
Get a list of remote link Resources from an issue.
- Parameters
issue (str) – the issue to get remote links from
- remote_link(issue: str, id: str) jira.resources.RemoteLink [source]¶
Get a remote link Resource from the server.
- add_remote_link(issue: str, destination: Union[jira.resources.Issue, Dict[str, Any]], globalId: Optional[str] = None, application: Optional[Dict[str, Any]] = None, relationship: Optional[str] = None) jira.resources.RemoteLink [source]¶
Add a remote link from an issue to an external application and returns a remote link Resource for it.
destination
should be a dict containing at leasturl
to the linked external URL andtitle
to display for the link inside Jira.For definitions of the allowable fields for
destination
and the keyword argumentsglobalId
,application
andrelationship
, see https://developer.atlassian.com/display/JIRADEV/JIRA+REST+API+for+Remote+Issue+Links.- Parameters
issue (str) – the issue to add the remote link to
destination (Union[Issue, Dict[str, Any]]) – the link details to add (see the above link for details)
globalId (Optional[str]) – unique ID for the link (see the above link for details)
application (Optional[Dict[str,Any]]) – application information for the link (see the above link for details)
relationship (Optional[str]) – relationship description for the link (see the above link for details)
- Returns
the added remote lint
- Return type
- add_simple_link(issue: str, object: Dict[str, Any])[source]¶
Add a simple remote link from an issue to web resource.
This avoids the admin access problems from add_remote_link by just using a simple object and presuming all fields are correct and not requiring more complex
application
data.object
should be a dict containing at leasturl
to the linked external URL andtitle
to display for the link inside Jira.For definitions of the allowable fields for
object
, see https://developer.atlassian.com/display/JIRADEV/JIRA+REST+API+for+Remote+Issue+Links.
- transitions(issue: str, id: Optional[str] = None, expand=None)[source]¶
Get a list of the transitions available on the specified issue to the current user.
- find_transitionid_by_name(issue: str, transition_name: str) Optional[int] [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
- transition_issue(issue: str, transition: str, fields: Optional[Dict[str, Any]] = None, comment: Optional[str] = None, worklog: Optional[str] = None, **fieldargs)[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 (str) – ID or key of the issue to perform the transition on
transition (str) – ID or name of the transition to perform
fields (Optional[Dict[str,Any]]) – a dict containing field names and the values to use.
comment (Optional[str]) – String to add as comment to the issue when performing the transition.
workload (Optional[str]) – String to add as time spent on the issue when performing the transition.
**fieldargs – If present, all other keyword arguments will be ignored
- votes(issue: str) jira.resources.Votes [source]¶
Get a votes Resource from the server.
- Parameters
issue (str) – ID or key of the issue to get the votes for
- Returns
Votes
- project_issue_security_level_scheme(project: str) jira.resources.IssueSecurityLevelScheme [source]¶
Get a IssueSecurityLevelScheme Resource from the server.
- Parameters
project (str) – ID or key of the project to get the IssueSecurityLevelScheme for
- Returns
The issue security level scheme
- Return type
- project_notification_scheme(project: str) jira.resources.NotificationScheme [source]¶
Get a NotificationScheme Resource from the server.
- Parameters
project (str) – ID or key of the project to get the NotificationScheme for
- Returns
The notification scheme
- Return type
- project_permissionscheme(project: str) jira.resources.PermissionScheme [source]¶
Get a PermissionScheme Resource from the server.
- Parameters
project (str) – ID or key of the project to get the permissionscheme for
- Returns
The permission scheme
- Return type
- project_priority_scheme(project: str) jira.resources.PriorityScheme [source]¶
Get a PriorityScheme Resource from the server.
- Parameters
project (str) – ID or key of the project to get the PriorityScheme for
- Returns
The priority scheme
- Return type
- project_workflow_scheme(project: str) jira.resources.WorkflowScheme [source]¶
Get a WorkflowScheme Resource from the server.
- Parameters
project (str) – ID or key of the project to get the WorkflowScheme for
- Returns
The workflow scheme
- Return type
- add_vote(issue: str) requests.models.Response [source]¶
Register a vote for the current authenticated user on an issue.
- Parameters
issue (str) – ID or key of the issue to vote on
- Returns
Response
- remove_vote(issue: str)[source]¶
Remove the current authenticated user’s vote from an issue.
- Parameters
issue (str) – ID or key of the issue to remove vote on
- watchers(issue: str) jira.resources.Watchers [source]¶
Get a watchers Resource from the server for an issue.
- Parameters
issue (str) – ID or key of the issue to get the watchers for
- Returns
Watchers
- add_watcher(issue: str, watcher: str) requests.models.Response [source]¶
Add a user to an issue’s watchers list.
- remove_watcher(issue: str, watcher: str) requests.models.Response [source]¶
Remove a user from an issue’s watch list.
- worklogs(issue: str) List[jira.resources.Worklog] [source]¶
Get a list of worklog Resources from the server for an issue.
- Parameters
issue (str) – ID or key of the issue to get worklogs from
- Returns
List[Worklog]
- worklog(issue: str, id: str) jira.resources.Worklog [source]¶
Get a specific worklog Resource from the server.
- add_worklog(issue, timeSpent: Optional[str] = None, timeSpentSeconds: Optional[str] = None, adjustEstimate: Optional[str] = None, newEstimate: Optional[str] = None, reduceBy: Optional[str] = None, comment: Optional[str] = None, started: Optional[datetime.datetime] = None, user: Optional[str] = None) jira.resources.Worklog [source]¶
Add a new worklog entry on an issue and return a Resource for it.
- Parameters
issue (str) – the issue to add the worklog to
timeSpent (Optional[str]) – a worklog entry with this amount of time spent, e.g. “2d”
timeSpentSeconds (Optional[str]) – a worklog entry with this amount of time spent in seconds
adjustEstimate (Optional[str]) – allows the user to provide specific instructions to update the remaining time estimate of the issue. The value can either be
new
,leave
,manual
orauto
(default).newEstimate (Optional[str]) – the new value for the remaining estimate field. e.g. “2d”
reduceBy (Optional[str]) – the amount to reduce the remaining estimate by e.g. “2d”
comment (Optional[str]) – optional worklog comment
started (Optional[datetime.datetime]) – Moment when the work is logged, if not specified will default to now
user (Optional[str]) – the user ID or name to use for this worklog
- Returns
Worklog
- create_issue_link(type: Union[str, jira.resources.IssueLinkType], inwardIssue: str, outwardIssue: str, comment: Optional[Dict[str, Any]] = None) requests.models.Response [source]¶
Create a link between two issues.
- Parameters
type (Union[str,IssueLinkType]) – the type of link to create
inwardIssue – the issue to link from
outwardIssue – the issue to link to
comment (Optional[Dict[str, Any]]) – a comment to add to the issues with the link. Should be a dict containing
body
andvisibility
fields:body
being the text of the comment andvisibility
being a dict containing two entries:type
andvalue
.type
isrole
(orgroup
if the Jira server has configured comment visibility for groups) andvalue
is the name of the role (or group) to which viewing of this comment will be restricted.
- Returns
Response
- delete_issue_link(id: str)[source]¶
Delete a link between two issues.
- Parameters
id (str) – ID of the issue link to delete
- issue_link(id: str)[source]¶
Get an issue link Resource from the server.
- Parameters
id (str) – ID of the issue link to get
- issue_link_types(force: bool = False) List[jira.resources.IssueLinkType] [source]¶
Get a list of issue link type Resources from the server.
- Returns
List[IssueLinkType]
- issue_link_type(id: str) jira.resources.IssueLinkType [source]¶
Get an issue link type Resource from the server.
- Parameters
id (str) – ID of the issue link type to get
- Returns
IssueLinkType
- issue_types() List[jira.resources.IssueType] [source]¶
Get a list of issue type Resources from the server.
- Returns
List[IssueType]
- issue_type(id: str) jira.resources.IssueType [source]¶
Get an issue type Resource from the server.
- Parameters
id (str) – ID of the issue type to get
- Returns
IssueType
- issue_type_by_name(name: str) jira.resources.IssueType [source]¶
- Parameters
name (str) – Name of the issue type
- Returns
IssueType
- request_types(service_desk: jira.resources.ServiceDesk) List[jira.resources.RequestType] [source]¶
Returns request types supported by a service desk instance.
- Parameters
service_desk (ServiceDesk) – The service desk instance.
- Returns
List[RequestType]
- request_type_by_name(service_desk: jira.resources.ServiceDesk, name: str)[source]¶
- my_permissions(projectKey: Optional[str] = None, projectId: Optional[str] = None, issueKey: Optional[str] = None, issueId: Optional[str] = None) Dict[str, Dict[str, Dict[str, str]]] [source]¶
Get a dict of all available permissions on the server.
- Parameters
projectKey (Optional[str]) – limit returned permissions to the specified project
projectId (Optional[str]) – limit returned permissions to the specified project
issueKey (Optional[str]) – limit returned permissions to the specified issue
issueId (Optional[str]) – limit returned permissions to the specified issue
- Returns
Dict[str, Dict[str, Dict[str, str]]]
- priority(id: str) jira.resources.Priority [source]¶
Get a priority Resource from the server.
- Parameters
id (str) – ID of the priority to get
- Returns
Priority
- projects(expand: Optional[str] = None) List[jira.resources.Project] [source]¶
Get a list of project Resources from the server visible to the current authenticated user.
- Parameters
expand (Optional[str]) – extra information to fetch for each project such as projectKeys and description.
- Returns
List[Project]
- project(id: str, expand: Optional[str] = None) jira.resources.Project [source]¶
Get a project Resource from the server.
- project_avatars(project: str)[source]¶
Get a dict of all avatars for a project visible to the current authenticated user.
- Parameters
project (str) – ID or key of the project to get avatars for
- create_temp_project_avatar(project: str, filename: str, size: int, avatar_img: bytes, contentType: str = None, auto_confirm: bool = False)[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 https://filemagic.readthedocs.io/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 andconfirm_project_avatar()
will be called for you before this method returns.- Parameters
project (str) – ID or key of the project to create the avatar in
filename (str) – name of the avatar file
size (int) – size of the avatar file
avatar_img (bytes) – file-like object holding the avatar
contentType (str) – explicit specification for the avatar image’s content-type
auto_confirm (bool) – whether to automatically confirm the temporary avatar by calling
confirm_project_avatar()
with the return value of this method. (Default: False)
- confirm_project_avatar(project: str, cropping_properties: Dict[str, Any])[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 thecropping_properties
: the return value ofcreate_temp_project_avatar()
should be used for this argument.- Parameters
project (str) – ID or key of the project to confirm the avatar in
cropping_properties (Dict[str,Any]) – a dict of cropping properties from
create_temp_project_avatar()
- delete_project_avatar(project: str, avatar: str) requests.models.Response [source]¶
Delete a project’s avatar.
- project_components(project: str) List[jira.resources.Component] [source]¶
Get a list of component Resources present on a project.
- Parameters
project (str) – ID or key of the project to get components from
- Returns
List[Component]
- project_versions(project: str) List[jira.resources.Version] [source]¶
Get a list of version Resources present on a project.
- Parameters
project (str) – ID or key of the project to get versions from
- Returns
List[Version]
- get_project_version_by_name(project: str, version_name: str) Optional[jira.resources.Version] [source]¶
Get a version Resource by its name present on a project.
- rename_version(project: str, old_name: str, new_name: str) None [source]¶
Rename a version Resource on a project.
- project_roles(project: str) Dict[str, Dict[str, str]] [source]¶
Get a dict of role names to resource locations for a project.
- Parameters
project (str) – ID or key of the project to get roles from
- project_role(project: str, id: str) jira.resources.Role [source]¶
Get a role Resource.
- resolutions() List[jira.resources.Resolution] [source]¶
Get a list of resolution Resources from the server.
- Returns
List[Resolution]
- resolution(id: str) jira.resources.Resolution [source]¶
Get a resolution Resource from the server.
- Parameters
id (str) – ID of the resolution to get
- Returns
Resolution
- search_issues(jql_str: str, startAt: int = 0, maxResults: int = 50, validate_query: bool = True, fields: Optional[Union[str, List[str]]] = None, expand: Optional[str] = None, json_result: bool = False) Union[List[Dict[str, Any]], jira.client.ResultList[jira.resources.Issue]] [source]¶
Get a
ResultList
of issue Resources matching a JQL search string.- Parameters
jql_str (str) – The JQL search string.
startAt (int) – Index of the first issue to return. (Default: 0)
maxResults (int) – Maximum number of issues to return. Total number of results is available in the
total
attribute of the returnedResultList
. If maxResults evaluates as False, it will try to get all issues in batches. (Default: 50)validate_query (bool) – Whether or not the query should be validated. (Default: True)
fields (Optional[Union[str, List[str]]]) – comma-separated string or list of issue fields to include in the results. Default is to include all fields.
expand (Optional[str]) – extra information to fetch inside each resource
json_result (bool) – JSON response will be returned when this parameter is set to True. Otherwise,
ResultList
will be returned.
- Returns
Dict if
json_result=True
- Return type
Union[Dict,ResultList]
- security_level(id: str) jira.resources.SecurityLevel [source]¶
Get a security level Resource.
- Parameters
id (str) – ID of the security level to get
- server_info() Dict[str, Any] [source]¶
Get a dict of server information for this Jira instance.
- Returns
Dict[str, Any]
- statuses() List[jira.resources.Status] [source]¶
Get a list of status Resources from the server.
- Returns
List[Status]
- status(id: str) jira.resources.Status [source]¶
Get a status Resource from the server.
- Parameters
id (str) – ID of the status resource to get
- Returns
Status
- statuscategories() List[jira.resources.StatusCategory] [source]¶
Get a list of status category Resources from the server.
- Returns
List[StatusCategory]
- statuscategory(id: int) jira.resources.StatusCategory [source]¶
Get a status category Resource from the server.
- Parameters
id (int) – ID of the status category resource to get
- Returns
StatusCategory
- user(id: str, expand: Optional[Any] = None) jira.resources.User [source]¶
Get a user Resource from the server.
- Parameters
id (str) – ID of the user to get
expand (Optional[Any]) – Extra information to fetch inside each resource
- Returns
User
- search_assignable_users_for_projects(username: str, projectKeys: str, startAt: int = 0, maxResults: int = 50) jira.client.ResultList [source]¶
Get a list of user Resources that match the search string and can be assigned issues for projects.
- Parameters
username (str) – A string to match usernames against
projectKeys (str) – Comma-separated list of project keys to check for issue assignment permissions
startAt (int) – Index of the first user to return (Default: 0)
maxResults (int) – Maximum number of users to return. If maxResults evaluates as False, it will try to get all users in batches. (Default: 50)
- Returns
ResultList
- search_assignable_users_for_issues(username: Optional[str] = None, project: Optional[str] = None, issueKey: Optional[str] = None, expand: Optional[Any] = None, startAt: int = 0, maxResults: int = 50, query: Optional[str] = None)[source]¶
Get a list of user Resources that match the search string for assigning or creating issues. “username” query parameter is deprecated in Jira Cloud; the expected parameter now is “query”, which can just be the full email again. But the “user” parameter is kept for backwards compatibility, i.e. Jira Server/Data Center.
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 (Optional[str]) – A string to match usernames against
project (Optional[str]) – Filter returned users by permission in this project (expected if a result will be used to create an issue)
issueKey (Optional[str]) – Filter returned users by this issue (expected if a result will be used to edit this issue)
expand (Optional[Any]) – Extra information to fetch inside each resource
startAt (int) – Index of the first user to return (Default: 0)
maxResults (int) – maximum number of users to return. If maxResults evaluates as False, it will try to get all items in batches. (Default: 50)
query (Optional[str]) – Search term. It can just be the email.
- Returns
ResultList
- user_avatars(username: str) Dict[str, Any] [source]¶
Get a dict of avatars for the specified user.
- Parameters
username (str) – the username to get avatars for
- create_temp_user_avatar(user: str, filename: str, size: int, avatar_img: bytes, contentType: Optional[Any] = None, auto_confirm: bool = 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). ThecontentType
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 theauto_confirm
argument with a truthy value andconfirm_user_avatar()
will be called for you before this method returns.- Parameters
user (str) – User to register the avatar for
filename (str) – name of the avatar file
size (int) – size of the avatar file
avatar_img (bytes) – file-like object containing the avatar
contentType (Optional[Any]) – explicit specification for the avatar image’s content-type
auto_confirm (bool) – whether to automatically confirm the temporary avatar by calling
confirm_user_avatar()
with the return value of this method. (Default: False)
- confirm_user_avatar(user: str, cropping_properties: Dict[str, Any])[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 thecropping_properties
: the return value ofcreate_temp_user_avatar()
should be used for this argument.- Parameters
user (str) – the user to confirm the avatar for
cropping_properties (Dict[str,Any]) – a dict of cropping properties from
create_temp_user_avatar()
- set_user_avatar(username: str, avatar: str) requests.models.Response [source]¶
Set a user’s avatar.
- search_users(user: Optional[str] = None, startAt: int = 0, maxResults: int = 50, includeActive: bool = True, includeInactive: bool = False, query: Optional[str] = None) jira.client.ResultList[jira.resources.User] [source]¶
Get a list of user Resources that match the specified search string. “username” query parameter is deprecated in Jira Cloud; the expected parameter now is “query”, which can just be the full email again. But the “user” parameter is kept for backwards compatibility, i.e. Jira Server/Data Center.
- Parameters
user (Optional[str]) – a string to match usernames, name or email against.
startAt (int) – index of the first user to return.
maxResults (int) – maximum number of users to return. If maxResults evaluates as False, it will try to get all items in batches.
includeActive (bool) – If true, then active users are included in the results. (Default: True)
includeInactive (bool) – If true, then inactive users are included in the results. (Default: False)
query (Optional[str]) – Search term. It can just be the email.
- Returns
ResultList[User]
- search_allowed_users_for_issue(user: str, issueKey: Optional[str] = None, projectKey: Optional[str] = None, startAt: int = 0, maxResults: int = 50) jira.client.ResultList [source]¶
Get a list of user Resources that match a username string and have browse permission for the issue or project.
- Parameters
user (str) – a string to match usernames against.
issueKey (Optional[str]) – find users with browse permission for this issue.
projectKey (Optional[str]) – find users with browse permission for this project.
startAt (int) – index of the first user to return. (Default: 0)
maxResults (int) – maximum number of users to return. If maxResults evaluates as False, it will try to get all items in batches. (Default: 50)
- Returns
ResultList
- create_version(name: str, project: str, description: str = None, releaseDate: Any = None, startDate: Any = None, archived: bool = False, released: bool = False) jira.resources.Version [source]¶
Create a version in a project and return a Resource for it.
- Parameters
name (str) – name of the version to create
project (str) – key of the project to create the version in
description (str) – a description of the version
releaseDate (Optional[Any]) – the release date assigned to the version
startDate (Optional[Any]) – The start date for the version
archived (bool) – Denotes whether a version should be archived. (Default: False)
released (bool) – Denotes whether a version is released. (Default: False)
- Returns
Version
- move_version(id: str, after: Optional[str] = None, position: Optional[str] = None) jira.resources.Version [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
andposition
must be specified.
- version(id: str, expand: Optional[Any] = None) jira.resources.Version [source]¶
Get a version Resource.
- Parameters
id (str) – ID of the version to get
expand (Optional[Any]) – extra information to fetch inside each resource
- Returns
Version
Get a dict of the counts of issues fixed and affected by a version.
- Parameters
id (str) – the version to count issues for
- version_count_unresolved_issues(id: str)[source]¶
Get the number of unresolved issues for a version.
- Parameters
id (str) – ID of the version to count issues for
- session() jira.resources.User [source]¶
Get a dict of the current authenticated user’s session information.
- Returns
User
- kill_session() requests.models.Response [source]¶
Destroy the session of the current authenticated user.
- kill_websudo() Optional[requests.models.Response] [source]¶
Destroy the user’s current WebSudo session.
Works only for non-cloud deployments, for others does nothing.
- Returns
Optional[Response]
- deactivate_user(username: str) Union[str, int] [source]¶
Disable/deactivate the user.
- Parameters
username (str) – User to be deactivated.
- Returns
Union[str, int]
- reindex(force: bool = False, background: bool = True) bool [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 background reindex only if Jira thinks it should do it.
- backup(filename: str = 'backup.zip', attachments: bool = False)[source]¶
Will call jira export to backup as zipped xml. Returning with success does not mean that the backup process finished.
- backup_progress()[source]¶
Return status of cloud backup as a dict.
Is there a way to get progress for Server version?
- backup_complete() Optional[bool] [source]¶
Return boolean based on ‘alternativePercentage’ and ‘size’ returned from backup_progress (cloud only).
- backup_download(filename: Optional[str] = None)[source]¶
Download backup file from WebDAV (cloud only).
- current_user(field: Optional[str] = None) str [source]¶
Return the accountId (Cloud) else username of the current user. For anonymous users it will return a value that evaluates as False.
- delete_project(pid: Union[str, jira.resources.Project]) Optional[bool] [source]¶
Delete project from Jira.
- Parameters
pid (Union[str, Project]) – Jira projectID or Project or slug
- Raises
JIRAError – If project not found or not enough permissions
ValueError – If pid parameter is not Project, slug or ProjectID
- Returns
True if project was deleted
- Return type
- issue_type_schemes() List[jira.resources.IssueTypeScheme] [source]¶
Get all issue type schemes defined (Admin required).
- Returns
All the Issue Type Schemes available to the currently logged in user.
- Return type
List[IssueTypeScheme]
- get_issue_type_scheme_associations(id: str) List[jira.resources.Project] [source]¶
For the specified issue type scheme, returns all of the associated projects. (Admin required)
- create_project(key: str, name: Optional[str] = None, assignee: Optional[str] = None, ptype: str = 'software', template_name: Optional[str] = None, avatarId=None, issueSecurityScheme=None, permissionScheme=None, projectCategory=None, notificationScheme=10000, categoryId=None, url: str = '')[source]¶
Create a project with the specified parameters.
- Parameters
key (str) – Mandatory. Must match Jira project key requirements, usually only 2-10 uppercase characters.
name (Optional[str]) – If not specified it will use the key value.
assignee (Optional[str]) – key of the lead, if not specified it will use current user.
ptype (Optional[str]) – Determines the type of project should be created.
template_name (Optional[str]) – is used to create a project based on one of the existing project templates. If template_name is not specified, then it should use one of the default values.
- Returns
Should evaluate to False if it fails otherwise it will be the new project id.
- Return type
- add_user(username: str, email: str, directoryId: int = 1, password: Optional[str] = None, fullname: Optional[str] = None, notify: bool = False, active: bool = True, ignore_existing: bool = False, application_keys: Optional[List] = None)[source]¶
Create a new Jira user.
- Parameters
username (str) – the username of the new user
email (str) – email address of the new user
directoryId (int) – The directory ID the new user should be a part of (Default: 1)
password (Optional[str]) – Optional, the password for the new user
fullname (Optional[str]) – Optional, the full name of the new user
notify (bool) – Whether or not to send a notification to the new user. (Default: False)
active (bool) – Whether or not to make the new user active upon creation. (Default: True)
ignore_existing (bool) – Whether or not to ignore and existing user. (Default: False)
applicationKeys (Optional[list]) – Keys of products user should have access to
- Raises
JIRAError – If username already exists and ignore_existing has not been set to True.
- Returns
Whether or not the user creation was successful.
- Return type
- add_user_to_group(username: str, group: str) Union[bool, Dict[str, Any]] [source]¶
Add a user to an existing group.
- role() List[Dict[str, Any]] [source]¶
Return Jira role information.
- Returns
List of current user roles
- Return type
List[Dict[str,Any]]
- boards(startAt: int = 0, maxResults: int = 50, type: str = None, name: str = None, projectKeyOrID=None) jira.client.ResultList[jira.resources.Board] [source]¶
Get a list of board resources.
- Parameters
startAt – The starting index of the returned boards. Base index: 0.
maxResults – The maximum number of boards to return per page. Default: 50
type – Filters results to boards of the specified type. Valid values: scrum, kanban.
name – Filters results to boards that match or partially match the specified name.
projectKeyOrID – Filters results to boards that match the specified project key or ID.
- Returns
ResultList[Board]
When old GreenHopper private API is used, paging is not enabled and all parameters are ignored.
- sprints(board_id: int, extended: bool = False, startAt: int = 0, maxResults: int = 50, state: str = None) jira.client.ResultList[jira.resources.Sprint] [source]¶
Get a list of sprint GreenHopperResources.
- Parameters
board_id (int) – the board to get sprints from
extended (bool) – Used only by old GreenHopper API to fetch additional information like startDate, endDate, completeDate, much slower because it requires an additional requests for each sprint. New Jira Agile API always returns this information without a need for additional requests.
startAt (int) – the index of the first sprint to return (0 based)
maxResults (int) – the maximum number of sprints to return
state (str) – Filters results to sprints in specified states. Valid values: future, active, closed. You can define multiple states separated by commas
- Returns
(content depends on API version, but always contains id, name, state, startDate and endDate) When old GreenHopper private API is used, paging is not enabled, and startAt, maxResults and state parameters are ignored.
- Return type
- incompletedIssuesEstimateSum(board_id: str, sprint_id: str)[source]¶
Return the total incompleted points this sprint.
- removedIssuesEstimateSum(board_id: str, sprint_id: str)[source]¶
Return the total incompleted points this sprint.
- sprint_info(board_id: str, sprint_id: str) Optional[Dict[str, Any]] [source]¶
Return the information about a sprint.
- sprint(id: int) jira.resources.Sprint [source]¶
Return the information about a sprint.
- Parameters
sprint_id (int) – the sprint retrieving issues from
- Returns
Sprint
- create_board(name: str, project_ids: Union[str, List[str]], preset: str = 'scrum', location_type: str = 'user', location_id: Optional[str] = None) jira.resources.Board [source]¶
Create a new board for the
project_ids
.- Parameters
name (str) – name of the board
project_ids (str) – the projects to create the board in
preset (str) – What preset to use for this board, options: kanban, scrum, diy. (Default: scrum)
location_type (str) – the location type. Available in cloud. (Default: user)
location_id (Optional[str]) – the id of project that the board should be located under. Omit this for a ‘user’ location_type. Available in cloud.
- Returns
The newly created board
- Return type
- create_sprint(name: str, board_id: int, startDate: Optional[Any] = None, endDate: Optional[Any] = None) jira.resources.Sprint [source]¶
Create a new sprint for the
board_id
.
- add_issues_to_sprint(sprint_id: int, issue_keys: List[str]) requests.models.Response [source]¶
Add the issues in
issue_keys
to thesprint_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.
- add_issues_to_epic(epic_id: str, issue_keys: str, ignore_epics: bool = True) requests.models.Response [source]¶
Add the issues in
issue_keys
to theepic_id
.
- class jira.client.GreenHopper(options=None, basic_auth=None, oauth=None, async_=None)[source]¶
Bases:
jira.client.JIRA
6.1.2. jira.config module¶
This module allows people to keep their jira server credentials outside their script, in a configuration file that is not saved in the source control.
Also, this simplifies the scripts by not having to write the same initialization code for each script.
- jira.config.get_jira(profile: Optional[str] = None, url: str = 'http://localhost:2990', username: str = 'admin', password: str = 'admin', appid=None, autofix=False, verify: Union[bool, str] = True)[source]¶
Return a JIRA object by loading the connection details from the config.ini file.
- Parameters
profile (Optional[str]) – The name of the section from config.ini file that stores server config url/username/password
url (str) – URL of the Jira server
username (str) – username to use for authentication
password (str) – password to use for authentication
appid – appid
autofix – autofix
verify (Union[bool, str]) – boolean indicating whether SSL certificates should be verified, or path to a CA_BUNDLE file or directory with certificates of trusted CAs.
- Returns
an instance to a JIRA object.
- Return type
- Raises
Usage:
>>> from jira.config import get_jira >>> >>> jira = get_jira(profile='jira')
Also create a config.ini like this and put it in current directory, user home directory or PYTHONPATH.
[jira] url=https://jira.atlassian.com # only the `url` is mandatory user=... pass=... appid=... verify=...
6.1.3. jira.exceptions module¶
- exception jira.exceptions.JIRAError(text: Optional[str] = None, status_code: Optional[int] = None, url: Optional[str] = None, request: Optional[requests.models.Response] = None, response: Optional[requests.models.Response] = None, **kwargs)[source]¶
Bases:
Exception
General error raised for all problems in operation of the client.
- __init__(text: Optional[str] = None, status_code: Optional[int] = None, url: Optional[str] = None, request: Optional[requests.models.Response] = None, response: Optional[requests.models.Response] = None, **kwargs)[source]¶
Creates a JIRAError.
- Parameters
text (Optional[str]) – Message for the error.
status_code (Optional[int]) – Status code for the error.
url (Optional[str]) – Url related to the error.
request (Optional[requests.Response]) – Request made related to the error.
response (Optional[requests.Response]) – Response received related to the error.
**kwargs – Will be used to get request headers.
6.1.4. jira.jirashell module¶
Starts an interactive Jira session in an ipython terminal.
Script arguments support changing the server and a persistent authentication over HTTP BASIC or Kerberos.
6.1.5. jira.resilientsession module¶
- jira.resilientsession.raise_on_error(r: Optional[requests.models.Response], verb='???', **kwargs)[source]¶
Handle errors from a Jira Request
- class jira.resilientsession.ResilientSession(timeout=None)[source]¶
Bases:
requests.sessions.Session
This class is supposed to retry requests that do return temporary errors.
At this moment it supports: 502, 503, 504
6.1.6. jira.resources module¶
- jira.client.ResourceType¶
alias of TypeVar(‘ResourceType’, bound=
jira.resources.Resource
, contravariant=True)
This module implements the Resource classes that translate JSON from Jira REST resources into usable objects.
- class jira.resources.Resource(resource: str, options: Dict[str, Any], session: jira.resilientsession.ResilientSession, base_url: str = '{server}/rest/{rest_path}/{rest_api_version}/{path}')[source]¶
Bases:
object
Models a URL-addressable resource in the Jira REST API.
All Resource objects provide the following:
find()
– get a resource from the server and load it into the current object (though clients should use the methods in the JIRA class instead of this method directly)update()
– changes the value of this resource on the server and returns a new resource object for itdelete()
– deletes this resource from the serverself
– the URL of this resource on the serverraw
– dict of properties parsed out of the JSON response from the serverSubclasses will implement
update()
anddelete()
as appropriate for the specific resource.All Resources have a resource path of the form:
issue
project/{0}
issue/{0}/votes
issue/{0}/comment/{1}
where the bracketed numerals are placeholders for ID values that are filled in from the
ids
parameter tofind()
.- JIRA_BASE_URL = '{server}/rest/{rest_path}/{rest_api_version}/{path}'¶
- _READABLE_IDS = ('displayName', 'key', 'name', 'accountId', 'filename', 'value', 'scope', 'votes', 'id', 'mimeType', 'closed')¶
- _HASH_IDS = ('self', 'type', 'key', 'id', 'name')¶
- __init__(resource: str, options: Dict[str, Any], session: jira.resilientsession.ResilientSession, base_url: str = '{server}/rest/{rest_path}/{rest_api_version}/{path}')[source]¶
Initializes a generic resource.
- Parameters
resource (str) – The name of the resource.
session (ResilientSession) – Session used for the resource.
base_url (Optional[str]) – The Base Jira url.
- find(id: Union[Tuple[str, str], int, str], params: Optional[Dict[str, str]] = None)[source]¶
Finds a resource based on the input parameters.
- _get_url(path: str) str [source]¶
Gets the url for the specified path.
- Parameters
path (str) – str
- Returns
str
- update(fields: Optional[Dict[str, Any]] = None, async_: Optional[bool] = None, jira: JIRA = None, notify: bool = True, **kwargs: Any)[source]¶
Update this resource on the server.
Keyword arguments are marshalled into a dict before being sent. If this resource doesn’t support
PUT
, aJIRAError
will be raised; subclasses that specialize this method will only raise errors in case of user error.- Parameters
fields (Optional[Dict[str, Any]]) – Fields which should be updated for the object.
async (bool) – If true the request will be added to the queue so it can be executed later using async_run()
jira (jira.client.JIRA) – Instance of Jira Client
notify (bool) – Whether or not to notify users about the update. (Default: True)
kwargs (Any) – extra arguments to the PUT request.
- delete(params: Optional[Dict[str, Any]] = None) Optional[requests.models.Response] [source]¶
Delete this resource from the server, passing the specified query parameters.
If this resource doesn’t support
DELETE
, aJIRAError
will be raised; subclasses that specialize this method will only raise errors in case of user error.- Parameters
params – Parameters for the delete request.
- Returns
Returns None if async
- Return type
Optional[Response]
- _load(url: str, headers={}, params: Optional[Dict[str, str]] = None, path: Optional[str] = None)[source]¶
Load a resource.
- Parameters
url (str) – url
headers (Optional[CaseInsensitiveDict]) – headers. Defaults to CaseInsensitiveDict().
params (Optional[Dict[str,str]]) – params to get request. Defaults to None.
path (Optional[str]) – field to get. Defaults to None.
- Raises
ValueError – If json cannot be loaded
- class jira.resources.Issue(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
A Jira issue.
- __init__(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
- update(fields: Dict[str, Any] = None, update: Dict[str, Any] = None, async_: bool = None, jira: JIRA = None, notify: bool = True, **fieldargs)[source]¶
Update this issue on the server.
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.
Jira projects may contain many different issue types. Some issue screens have different requirements for fields in an issue. This information is available through the
JIRA.editmeta()
method. Further examples are available here: https://developer.atlassian.com/display/JIRADEV/JIRA+REST+API+Example+-+Edit+issues- Parameters
fields (Dict[str,Any]) – a dict containing field names and the values to use
update (Dict[str,Any]) – a dict containing update operations to apply
notify (bool) – query parameter notifyUsers. If true send the email with notification that the issue was updated to users that watch it. Admin or project admin permissions are required to disable the notification.
jira (Optional[jira.client.JIRA]) – JIRA instance.
fieldargs (dict) – keyword arguments will generally be merged into fields, except lists, which will be merged into updates
- get_field(field_name: str) Any [source]¶
Obtain the (parsed) value from the Issue’s field.
- Parameters
field_name (str) – The name of the field to get
- Raises
AttributeError – If the field does not exist or if the field starts with an
_
- Returns
Returns the parsed data stored in the field. For example, “project” would be of class
Project
- Return type
Any
- add_field_value(field: str, value: str)[source]¶
Add a value to a field that supports multiple values, without resetting the existing values.
This should work with: labels, multiple checkbox lists, multiple select
- class jira.resources.Comment(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
An issue comment.
- class jira.resources.Project(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
A Jira project.
- class jira.resources.Attachment(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
An issue attachment.
- class jira.resources.Component(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
A project component.
- class jira.resources.Dashboard(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
A Jira dashboard.
- class jira.resources.Filter(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
An issue navigator filter.
- class jira.resources.Votes(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
Vote information on an issue.
- class jira.resources.PermissionScheme(options, session, raw=None)[source]¶
Bases:
jira.resources.Resource
Permissionscheme information on an project.
- class jira.resources.Watchers(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
Watcher information on an issue.
- class jira.resources.Worklog(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
Worklog on an issue.
- __init__(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
- delete(adjustEstimate: Optional[str] = None, newEstimate=None, increaseBy=None)[source]¶
Delete this worklog entry from its associated issue.
- Parameters
adjustEstimate – one of
new
,leave
,manual
orauto
.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 valueincreaseBy – combined with
adjustEstimate=manual
, increase the remaining estimate by this amount
- class jira.resources.IssueLink(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
Link between two issues.
- class jira.resources.IssueLinkType(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
Type of link between two issues.
- class jira.resources.IssueSecurityLevelScheme(options, session, raw=None)[source]¶
Bases:
jira.resources.Resource
IssueSecurityLevelScheme information on an project.
- class jira.resources.IssueType(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
Type of an issue.
- class jira.resources.IssueTypeScheme(options, session, raw=None)[source]¶
Bases:
jira.resources.Resource
An issue type scheme.
- class jira.resources.NotificationScheme(options, session, raw=None)[source]¶
Bases:
jira.resources.Resource
NotificationScheme information on an project.
- class jira.resources.Priority(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
Priority that can be set on an issue.
- class jira.resources.PriorityScheme(options, session, raw=None)[source]¶
Bases:
jira.resources.Resource
PriorityScheme information on an project.
- class jira.resources.Version(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
A version of a project.
- __init__(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
- delete(moveFixIssuesTo=None, moveAffectedIssuesTo=None)[source]¶
Delete this project version from the server.
If neither of the arguments are specified, the version is removed from all issues it is attached to.
- Parameters
moveFixIssuesTo – in issues for which this version is a fix version, add this argument version to the fix version list
moveAffectedIssuesTo – in issues for which this version is an affected version, add this argument version to the affected version list
- update(**kwargs)[source]¶
Update this project version from the server. It is prior used to archive versions.
Refer to Atlassian REST API documentation.
- Example
>> version_id = "10543" >> version = JIRA("https://atlassian.org").version(version_id) >> print(version.name) "some_version_name" >> version.update(name="another_name") >> print(version.name) "another_name" >> version.update(archived=True) >> print(version.archived) True
- class jira.resources.WorkflowScheme(options, session, raw=None)[source]¶
Bases:
jira.resources.Resource
WorkflowScheme information on an project.
- class jira.resources.Role(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
A role inside a project.
- __init__(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
- update(users: Optional[Union[str, List, Tuple]] = None, groups: Optional[Union[str, List, Tuple]] = None)[source]¶
Add the specified users or groups to this project role. One of
users
orgroups
must be specified.
- class jira.resources.Resolution(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
A resolution for an issue.
- class jira.resources.SecurityLevel(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
A security level for an issue or project.
- class jira.resources.Status(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
Status for an issue.
- class jira.resources.User(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None, *, _query_param: str = 'username')[source]¶
Bases:
jira.resources.Resource
A Jira user.
- class jira.resources.Group(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
A Jira user group.
- class jira.resources.CustomFieldOption(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
An existing option for a custom issue field.
- class jira.resources.RemoteLink(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
A link to a remote application from an issue.
- __init__(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
- update(object, globalId=None, application=None, relationship=None)[source]¶
Update a RemoteLink. ‘object’ is required.
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
object – 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)
- class jira.resources.Customer(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
A Service Desk customer.
- class jira.resources.ServiceDesk(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
A Service Desk.
- class jira.resources.RequestType(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
A Service Desk Request Type.
- class jira.resources.StatusCategory(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
StatusCategory for an issue.
- class jira.resources.GreenHopperResource(path: str, options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.Resource
A generic GreenHopper resource.
- AGILE_BASE_URL = '{server}/rest/{agile_rest_path}/{agile_rest_api_version}/{path}'¶
- GREENHOPPER_REST_PATH = 'greenhopper'¶
Old, private API. Deprecated and will be removed from Jira on the 1st February 2016.
- AGILE_EXPERIMENTAL_REST_PATH = 'greenhopper/experimental-api'¶
Experimental API available in Jira Agile 6.7.3 - 6.7.6, basically the same as Public API
- AGILE_BASE_REST_PATH = 'agile'¶
Public API introduced in Jira Agile 6.7.7.
- class jira.resources.Sprint(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.GreenHopperResource
A GreenHopper sprint.
- class jira.resources.Board(options: Dict[str, str], session: jira.resilientsession.ResilientSession, raw: Optional[Dict[str, Any]] = None)[source]¶
Bases:
jira.resources.GreenHopperResource
A GreenHopper board.
6.1.7. jira.utils module¶
Jira utils used internally.
- class jira.utils.CaseInsensitiveDict(*args, **kwargs)[source]¶
Bases:
requests.structures.CaseInsensitiveDict
A case-insensitive
dict
-like object.DEPRECATED: use requests.structures.CaseInsensitiveDict directly.
Implements all methods and operations of
collections.MutableMapping
as well as dict’scopy
. Also provideslower_items
.All keys are expected to be strings. The structure remembers the case of the last key to be set, and
iter(instance)
,keys()
,items()
,iterkeys()
will contain case-sensitive keys. However, querying and contains testing is case insensitive:cid = CaseInsensitiveDict() cid['Accept'] = 'application/json' cid['accept'] == 'application/json' # True list(cid) == ['Accept'] # True
For example,
headers['content-encoding']
will return the value of a'Content-Encoding'
response header, regardless of how the header name was originally stored.If the constructor,
.update
, or equality comparison operations are given keys that have equal.lower()
s, the behavior is undefined.
- jira.utils.json_loads(r: Optional[requests.models.Response]) Any [source]¶
Attempts to load json the result of a response
- Parameters
r (Optional[Response]) – The Response object
- Raises
- Returns
the json
- Return type