Python Jira

https://jira.readthedocs.io
Admin
A Python library to work with Jira APIs, providing functionalities for managing issues, projects,...
Tokens:182,960
Snippets:1,454
Trust Score:8.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Basic Jira Usage

Source: https://jira.readthedocs.io/_sources/examples.rst.txt

A simple example demonstrating basic interaction with Jira. This snippet requires the jira library to be installed.

```python
from jira import JIRA

jira = JIRA()

```

--------------------------------

### Install and Run Tox for Testing

Source: https://jira.readthedocs.io/_sources/contributing.rst.txt

Install tox and run tests using the tox command. This is the primary method for testing contributions.

```bash
python -m pip install pipx
pipx install tox
tox
```

--------------------------------

### Set up a virtual environment and install jira-python

Source: https://jira.readthedocs.io/_sources/installation.rst.txt

Recommended for standalone client usage. This creates an isolated Python environment to prevent conflicts with system components. Activate the environment before installing.

```bash
python -m venv jira_python
source jira_python/bin/activate
pip install 'jira[cli]'
```

```bash
python -m venv jira_python
jira_python/bin/pip install 'jira[cli]'
```

--------------------------------

### Example config.ini Structure

Source: https://jira.readthedocs.io/_modules/jira/config.html

An example of how to structure the `config.ini` file to store Jira server connection details. The `url` is mandatory, while `user`, `pass`, `appid`, and `verify` are optional.

```none
[jira]
url=https://jira.atlassian.com
# only the `url` is mandatory
user=...
pass=...
appid=...
verify=...
```

--------------------------------

### Example Usage: Get Jira Object

Source: https://jira.readthedocs.io/api.html

Demonstrates how to import and use the `get_jira` function to obtain a Jira object, optionally specifying a profile from the configuration file.

```python
>>> from jira.config import get_jira
>>> 
>>> jira = get_jira(profile='jira')
```

--------------------------------

### Install jira-python with CLI dependencies

Source: https://jira.readthedocs.io/_sources/installation.rst.txt

Use this command to install the jira-python library along with dependencies required for the jirashell binary. Omit `[cli]` if only the library is needed.

```bash
pip install 'jira[cli]'
```

--------------------------------

### Install jirashell

Source: https://jira.readthedocs.io/jirashell.html

Install the jirashell tool using pip. Ensure you include the [cli] extra for command-line interface support.

```bash
pip install jira[cli]

```

--------------------------------

### Authenticate with Custom User Agent

Source: https://jira.readthedocs.io/_sources/examples.rst.txt

Example of authenticating with JIRA using basic authentication and a custom User-Agent header. Ensure 'requests_toolbelt' is installed.

```python
from requests_toolbelt import user_agent

jira = JIRA(
    basic_auth=("email", "API token"),
    options={"headers": {"User-Agent": user_agent("my_package", "0.0.1")}})

```

--------------------------------

### Install Jira Python Library in Virtual Environment (Alternative)

Source: https://jira.readthedocs.io/installation.html

An alternative method to install the library within a virtual environment, using the virtual environment's pip executable directly.

```bash
python -m venv jira_python
jira_python/bin/pip install 'jira[cli]'
```

--------------------------------

### Install Jira CLI

Source: https://jira.readthedocs.io/_sources/jirashell.rst.txt

Install the jira package with CLI support using pip. This command is necessary to enable the jirashell script.

```bash
pip install jira[cli]
```

--------------------------------

### project

Source: https://jira.readthedocs.io/api.html

Get a project Resource from the server.

```APIDOC
## project

### Description
Get a project Resource from the server.

### Parameters
- **id** (str) - ID or key of the project to get
- **expand** (str | None) - Optional - extra information to fetch for the project such as projectKeys and description.

### Returns
Project
```

--------------------------------

### Get All Issue Fields

Source: https://jira.readthedocs.io/_modules/jira/client.html

Retrieves a list of all available issue fields in Jira. No specific setup is required beyond having an authenticated client.

```python
def fields(self) -> list[dict[str, Any]]:
    """Return a list of all issue fields.

    Returns:
        List[Dict[str, Any]]
    """
    return self._get_json("field")
```

--------------------------------

### Project.__init__(self, jira_instance, path)

Source: https://jira.readthedocs.io/api.html

Constructor for the Project class.

```APIDOC
## Project.__init__(self, jira_instance, path)

### Description
Constructor for the Project class.

### Parameters
#### Path Parameters
- **jira_instance** (JIRA) - Required - The JIRA instance object.
- **path** (str) - Required - The API path for the project.
```

--------------------------------

### Get Jira Issue Field

Source: https://jira.readthedocs.io/_modules/jira/resources.html

Retrieves the parsed value of a specific field from an issue. Raises an AttributeError if the field name starts with an underscore.

```python
def get_field(self, field_name: str) -> Any:
        """Obtain the (parsed) value from the Issue's field.

        Args:
            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:
            Any: Returns the parsed data stored in the field. For example, "project" would be of class :py:class:`Project`
        """
        if field_name.startswith("_"):
            raise AttributeError(
                f"An issue field_name cannot start with underscore (_): {field_name}",
                field_name,
            )
        else:
            return getattr(self.fields, field_name)
```

--------------------------------

### Resource.__init__(self, jira_instance, path)

Source: https://jira.readthedocs.io/api.html

Constructor for the Resource class.

```APIDOC
## Resource.__init__(self, jira_instance, path)

### Description
Constructor for the Resource class.

### Parameters
#### Path Parameters
- **jira_instance** (JIRA) - Required - The JIRA instance object.
- **path** (str) - Required - The API path for the resource.
```

--------------------------------

### Instantiate Jira Client with Options

Source: https://jira.readthedocs.io/_modules/jira/client.html

You can specify server details and other properties using the 'options' argument. This allows for custom configurations like rest_path and verify.

```python
options = {
    "server": "http://localhost:2990/jira",
    "rest_path": "api",
    "rest_api_version": "2",
    "verify": True,
    "headers": {
        "X-Atlassian-Token": "no-check"
    }
}
j = JIRA(options=options)
```

--------------------------------

### Get Jira Dashboards

Source: https://jira.readthedocs.io/_modules/jira/client.html

Retrieves a paginated list of Jira dashboards. You can filter the results by 'favourite' or 'my' dashboards, and control the starting index and maximum number of results returned. If `maxResults` is set to `False`, it attempts to fetch all items in batches.

```python
    def dashboards(
        self, filter=None, startAt=0, maxResults=20
    ) -> ResultList[Dashboard]:
        """Return a ResultList of Dashboard resources and a ``total`` count.

        Args:
            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 set to False, it will try to get all items in batches. (Default: ``20``)
        """
        return self._get_json("dashboards", filter=filter, startAt=startAt, maxResults=maxResults)
```

--------------------------------

### Component.__init__(self, jira_instance, path)

Source: https://jira.readthedocs.io/api.html

Constructor for the Component class.

```APIDOC
## Component.__init__(self, jira_instance, path)

### Description
Constructor for the Component class.

### Parameters
#### Path Parameters
- **jira_instance** (JIRA) - Required - The JIRA instance object.
- **path** (str) - Required - The API path for the component.
```

--------------------------------

### Initialize Agile Resource

Source: https://jira.readthedocs.io/_modules/jira/resources.html

Base initialization for Agile resources, setting up path, options, session, and base URL.

```python
def __init__(
        self,
        path: str,
        options: dict[str, str],
        session: ResilientSession,
        raw: dict[str, Any] | None = None,
    ):
        self.self = ""

        Resource.__init__(self, path, options, session, self.AGILE_BASE_URL)
        if raw:
            self._parse_raw(raw)
        self.raw: dict[str, Any] = cast(dict[str, Any], self.raw)
```

--------------------------------

### add_issues_to_sprint

Source: https://jira.readthedocs.io/api.html

Adds a list of issues to a specified sprint. The sprint must be started but not completed. If the sprint is completed or not started, specific actions are required.

```APIDOC
## add_issues_to_sprint

### Description
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** (_int_) – the sprint to add issues to
* **issue_keys** (_List_[str]_) – the issues to add to the sprint

### Returns
Response[source]
```

--------------------------------

### Instantiate Jira Client with Server URL

Source: https://jira.readthedocs.io/_modules/jira/client.html

The easiest way to instantiate a Jira client is by providing the server URL. This example shows a basic instantiation.

```python
j = JIRA("https://jira.atlassian.com")
```

--------------------------------

### Start Jira Shell

Source: https://jira.readthedocs.io/_sources/jirashell.rst.txt

Launch the jirashell script and connect to a Jira instance. The script will provide a prompt for interactive commands.

```bash
jirashell -s https://jira.atlassian.com
<Jira Shell (https://jira.atlassian.com)>

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

In [1]:
```

--------------------------------

### Dashboard.__init__(self, jira_instance, path)

Source: https://jira.readthedocs.io/api.html

Constructor for the Dashboard class.

```APIDOC
## Dashboard.__init__(self, jira_instance, path)

### Description
Constructor for the Dashboard class.

### Parameters
#### Path Parameters
- **jira_instance** (JIRA) - Required - The JIRA instance object.
- **path** (str) - Required - The API path for the dashboard.
```

--------------------------------

### DashboardItemProperty.__init__(self, jira_instance, path)

Source: https://jira.readthedocs.io/api.html

Constructor for the DashboardItemProperty class.

```APIDOC
## DashboardItemProperty.__init__(self, jira_instance, path)

### Description
Constructor for the DashboardItemProperty class.

### Parameters
#### Path Parameters
- **jira_instance** (JIRA) - Required - The JIRA instance object.
- **path** (str) - Required - The API path for the dashboard item property.
```

--------------------------------

### Get Project Details

Source: https://jira.readthedocs.io/_sources/examples.rst.txt

Access detailed information about a specific project, including its name and lead.

```python
jra = jira.project('JRA')
print(jra.name)                 # 'JIRA'
print(jra.lead.displayName)     # 'John Doe [ACME Inc.]'
```

--------------------------------

### Jira Client: Get URL and Make Request

Source: https://jira.readthedocs.io/_modules/jira/client.html

Constructs a Jira URL and makes a GET or POST request based on the use_post flag. Handles JSON parsing and logs errors.

```python
def _get_url(self, path, base=None):
    # ... implementation details ...
    pass

def _request(self, path, params=None, base=None, use_post=False):
    """Make a request to the Jira API.

    Args:
        path (str): The subpath required
        params (Optional[Dict[str, Any]]): Parameters to filter the json query.
        base (Optional[str]): The Base Jira URL, defaults to the instance base.
        use_post (bool): Use POST endpoint instead of GET endpoint.

    Returns:
        Union[Dict[str, Any], List[Dict[str, str]]]
    """
    url = self._get_url(path, base)
    r = (
        self._session.post(url, data=json.dumps(params))
        if use_post
        else self._session.get(url, params=params)
    )
    try:
        r_json = json_loads(r)
    except ValueError as e:
        self.log.error(f"{e}\n{r.text if r else r}")
        raise e
    return r_json
```

--------------------------------

### Get Project Components, Roles, and Versions

Source: https://jira.readthedocs.io/_sources/examples.rst.txt

Retrieve lists of components, roles, and versions for a given project, provided the user has permission.

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

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

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

--------------------------------

### Add Issues to a Sprint

Source: https://jira.readthedocs.io/api.html

Adds a list of issues to a specified sprint. The sprint must be started but not completed. Ensure issues have a resolution set before the completion date if the sprint was completed, or adjust the rank if the sprint was not started.

```python
add_issues_to_sprint(_sprint_id : int_, _issue_keys : list[str]_) → Response[source]
```

--------------------------------

### Initialize Board Resource

Source: https://jira.readthedocs.io/_modules/jira/resources.html

Initializes a Board resource with its specific path pattern.

```python
def __init__(
        self,
        options: dict[str, str],
        session: ResilientSession,
        raw: dict[str, Any] | None = None,
    ):
        AgileResource.__init__(self, "board/{id}", options, session, raw)
```

--------------------------------

### JIRA.create_project(name, key, lead, ptype, template_key)

Source: https://jira.readthedocs.io/api.html

Creates a new project in JIRA.

```APIDOC
## JIRA.create_project(name, key, lead, ptype, template_key)

### Description
Creates a new project in JIRA.

### Method
POST

### Endpoint
/rest/api/2/project

### Parameters
#### Request Body
- **name** (string) - Required - The name of the project.
- **key** (string) - Required - The key for the project.
- **lead** (string) - Required - The username of the project lead.
- **ptype** (string) - Required - The project type.
- **template_key** (string) - Optional - The template key for the project.
```

--------------------------------

### priority

Source: https://jira.readthedocs.io/api.html

Get a priority Resource from the server.

```APIDOC
## priority

### Description
Get a priority Resource from the server.

### Parameters
- **id** (str) - ID of the priority to get

### Returns
Priority
```

--------------------------------

### Basic Jira Client Operations

Source: https://jira.readthedocs.io/examples.html

Demonstrates connecting to Jira anonymously, retrieving projects, issues, adding comments, updating issues, and deleting issues. Ensure you have the 'jira' library installed.

```python
# This script shows how to use the client in anonymous mode
# against jira.atlassian.com.
from __future__ import annotations

import re

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(server="https://jira.atlassian.com")

# 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.
atl_comments = [
    comment
    for comment in issue.fields.comment.comments
    if re.search(r"@atlassian.com$", comment.author.key)
]

# 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."
)

# Change the issue without sending updates
issue.update(notify=False, description="Quiet summary update.")

# You can update the entire labels field like this
issue.update(fields={"labels": ["AAA", "BBB"]})

# Or modify the List of existing labels. The new label is unicode with no
# spaces
issue.fields.labels.append("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 = jira.issue("XX-23")  # could also be another instance
jira.add_remote_link(issue.id, issue2)

```

--------------------------------

### client_info()

Source: https://jira.readthedocs.io/api.html

Get the server this client is connected to.

```APIDOC
## client_info()

### Description
Get the server this client is connected to.

### Method
GET (assumed)

### Endpoint
/rest/api/2/server/info (assumed)

### Response
#### Success Response (200)
- **info** (str) - Server connection information
```

--------------------------------

### Get All Projects

Source: https://jira.readthedocs.io/_modules/jira/client.html

Fetches a list of all project resources visible to the currently authenticated user. Supports expanding project details like keys and descriptions.

```python
def projects(self, expand: str | None = None) -> list[Project]:
        """Get a list of project Resources from the server visible to the current authenticated user.

        Args:
            expand (Optional[str]): extra information to fetch for each project such as projectKeys and description.

        Returns:
            List[Project]
        """
        params = {}
        if expand is not None:
            params["expand"] = expand
        r_json = self._get_json("project", params=params)
        projects = [
            Project(self._options, self._session, raw_project_json)
            for raw_project_json in r_json
        ]
        return projects
```

--------------------------------

### user_avatars

Source: https://jira.readthedocs.io/api.html

Get a dict of avatars for the specified user.

```APIDOC
## user_avatars

### Description
Get a dict of avatars for the specified user.

### Parameters
#### Query Parameters
- **username** (str) - the username to get avatars for

### Returns
Dict[str, Any]
```

--------------------------------

### priorities

Source: https://jira.readthedocs.io/api.html

Get a list of priority Resources from the server.

```APIDOC
## priorities

### Description
Get a list of priority Resources from the server.

### Returns
List[Priority]
```

--------------------------------

### Initialize Dashboard Resource

Source: https://jira.readthedocs.io/_modules/jira/resources.html

Initializes a Dashboard resource.

```python
def __init__(
        self,
        options: dict[str, str],
        session: ResilientSession,
        raw: dict[str, Any] | None = None,
    ):
        Resource.__init__(self, "dashboard/{0}", options, session)
        if raw:
            self._parse_raw(raw)
        self.raw: dict[str, Any] = cast(dict[str, Any], self.raw)
```

--------------------------------

### Initialize Project Resource

Source: https://jira.readthedocs.io/_modules/jira/resources.html

Initializes the Project resource with options, session, and raw data. Represents a Jira project.

```python
def __init__(
        self,
        options: dict[str, str],
        session: ResilientSession,
        raw: dict[str, Any] | None = None,
    ):
        Resource.__init__(self, "project/{0}", options, session)
        if raw:
            self._parse_raw(raw)
        self.raw: dict[str, Any] = cast(dict[str, Any], self.raw)
```

--------------------------------

### issue_type

Source: https://jira.readthedocs.io/api.html

Get an issue type Resource from the server.

```APIDOC
## issue_type

### Description
Get an issue type Resource from the server.

### Parameters
- **id** (str) - ID of the issue type to get

### Returns
IssueType
```

--------------------------------

### component(_id)

Source: https://jira.readthedocs.io/api.html

Get a component Resource from the server.

```APIDOC
## component(_id)

### Description
Get a component Resource from the server.

### Parameters
#### Path Parameters
- **id** (str) - Required - ID of the component to get

### Response
#### Success Response (200)
- **component** (Component) - The Component Resource object
```

--------------------------------

### jira.client Module Initialization

Source: https://jira.readthedocs.io/api.html

This section details the parameters available when initializing the jira.client module, covering server configuration, various authentication methods (basic, token, OAuth, Kerberos, JWT), and other client options.

```APIDOC
## jira.client Module Initialization

### Description
Initializes the jira.client module with various configuration options for connecting to a Jira server.

### Parameters
* **server** (_Optional_ _[__str_ _]_) – The server address and context path to use. Defaults to `http://localhost:2990/jira`.
* **options** (_Optional_ _[__Dict_ _[__str_ _,__bool_ _,__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 `agile`.
    * verify (Union[bool, str]) – Verify SSL certs. (Default: `True`). Or path 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)
    * signature_method (Optional) – The signature method to use with OAuth. Defaults to oauthlib.oauth1.SIGNATURE_HMAC_SHA1
* **kerberos** (_bool_) – True to enable Kerberos authentication. (Default: `False`)
* **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_) – True makes your credentials first to be validated. Remember that if you are accessing Jira as anonymous it will fail. (Default: `False`).
* **get_server_info** (_bool_) – True fetches server version info first to determine if some API calls are available. (Default: `True`).
* **async** (_bool_) – True enables async requests for those actions where we implemented it, like issue update() or delete(). (Default: `False`).
* **async_workers** (_int_) – Set the number of worker threads for async operations.
* **timeout** (_Optional_ _[__Union_ _[__Union_ _[__float_ _,__int_ _]__,__Tuple_ _[__float_ _,__float_ _]__]__]_) – Set a connect/read timeout for the underlying calls to Jira. 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_) – True enables loglevel to info => else critical. (Default: `True`)
* **default_batch_sizes** (_Optional_ _[__Dict_ _[__Type_ _[__Resource_ _]__,__Optional_ _[__int_ _]__]__]_) – Manually specify the batch-sizes for the paginated retrieval of different item types. Resource is used as a fallback for every item type not specified. If an item type is mapped to None no fallback occurs, instead the JIRA-backend will use its default batch-size. By default all Resources will be queried in batches of 100. E.g., setting this to `{Issue: 500, Resource: None}` will make `search_issues()` query Issues in batches of 500, while every other item type’s batch-size will be controlled by the backend. (Default: None)
```

--------------------------------

### jira.jirashell.oauth_dance

Source: https://jira.readthedocs.io/api.html

Starts an interactive Jira session with OAuth dance.

```APIDOC
## Function: jira.jirashell.oauth_dance

### Description
Starts an interactive Jira session in an ipython terminal using OAuth.

### Parameters
- **server** (str) - The Jira server URL.
- **consumer_key** (str) - The consumer key for OAuth.
- **key_cert_data** (str) - The key and certificate data for OAuth.
- **print_tokens** (bool, optional) - Whether to print tokens. Defaults to False.
- **verify** (bool or str, optional) - Whether to verify SSL certificates. Defaults to None.
```

--------------------------------

### create_board()

Source: https://jira.readthedocs.io/genindex.html

Creates a new board.

```APIDOC
## create_board()

### Description
Creates a new board.

### Method
(Not specified, assumed to be a client method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
```python
jira.create_board(board_details)
```

### Response
(Response details not specified)
```

--------------------------------

### comments

Source: https://jira.readthedocs.io/api.html

Get a list of comment Resources of the issue provided.

```APIDOC
## comments

### Description
Get a list of comment Resources of the issue provided.

### Parameters
#### Path Parameters
- **issue** (Union[int, str]) - Required - the issue ID or key to get the comments from
- **expand** (Optional[str]) - Optional - extra information to fetch for each comment such as renderedBody and properties.
- **start_at** (Optional[int]) - Optional - index of the first comment to return (page offset)
- **max_results** (Optional[int]) - Optional - maximum number of comments to return
- **order_by** (Optional[str]) - Optional - order of the comments to return; should be ‘created’, ‘+created’ or ‘-created’.

### Returns
List[Comment]
```

--------------------------------

### JIRA.backup()

Source: https://jira.readthedocs.io/index.html

Initiates a backup of the Jira instance.

```APIDOC
## JIRA.backup()

### Description
Initiates a full backup of the Jira instance, including all data and configurations.

### Method
POST

### Endpoint
/rest/api/2/backup
```

--------------------------------

### backup()

Source: https://jira.readthedocs.io/genindex.html

Initiates a backup process for Jira data.

```APIDOC
## backup()

### Description
Initiates a backup process for Jira data.

### Method
(Not specified, assumed to be a client method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
```python
jira.backup()
```

### Response
(Response details not specified)
```

--------------------------------

### component_count_related_issues(_id)

Source: https://jira.readthedocs.io/api.html

Get the count of related issues for a component.

```APIDOC
## component_count_related_issues(_id)

### Description
Get the count of related issues for a component.

### Parameters
#### Path Parameters
- **id** (str) - Required - ID of the component to use

### Response
#### Success Response (200)
- **count** (int) - The count of related issues
```

--------------------------------

### get()

Source: https://jira.readthedocs.io/genindex.html

Retrieves an attachment. This method is part of the jira.resources.Attachment class.

```APIDOC
## get()

### Description
Retrieves an attachment.

### Method
Not specified (assumed to be a client method call).

### Endpoint
Not specified.

### Parameters
None explicitly documented.

### Request Example
```python
attachment_resource.get()
```

### Response
Details not specified.
```

--------------------------------

### Comment.__init__(self, jira_instance, path)

Source: https://jira.readthedocs.io/api.html

Constructor for the Comment class.

```APIDOC
## Comment.__init__(self, jira_instance, path)

### Description
Constructor for the Comment class.

### Parameters
#### Path Parameters
- **jira_instance** (JIRA) - Required - The JIRA instance object.
- **path** (str) - Required - The API path for the comment.
```

--------------------------------

### Instantiate Jira Client with Basic Authentication

Source: https://jira.readthedocs.io/_modules/jira/client.html

Use the 'basic_auth' argument to provide a username and password for HTTP BASIC authentication.

```python
j = JIRA(basic_auth=('user', 'pass'), options={"server": "https://jira.atlassian.com"})
```

--------------------------------

### Get Workflows

Source: https://jira.readthedocs.io/_modules/jira/client.html

Retrieves all workflows from Jira. This method is cached for performance.

```python
from jira import JIRA

# Assuming 'jira' is an instance of the JIRA client
# Example usage:
# jira_client = JIRA(server='https://your-jira-instance.atlassian.net')
# workflows = jira_client.workflows()
```

--------------------------------

### Main Jira Shell Execution Logic

Source: https://jira.readthedocs.io/_modules/jira/jirashell.html

Sets up and runs the Jira shell. It handles configuration, authentication (basic, OAuth, Kerberos), and initializes an IPython interactive shell. Exits if run inside an existing IPython session.

```python
def main():
    try:
        try:
            get_ipython  # type: ignore[name-defined] # exists in ipython
        except NameError:
            pass
        else:
            sys.exit("Running ipython inside ipython isn't supported. :(")

        options, basic_auth, oauth, kerberos_auth = get_config()

        if basic_auth:
            basic_auth = handle_basic_auth(auth=basic_auth, server=options["server"])

        if oauth.get("oauth_dance") is True:
            oauth = oauth_dance(
                options["server"],
                oauth["consumer_key"],
                oauth["key_cert"],
                oauth["print_tokens"],
                options["verify"],
            )
        elif not all(
            (
                oauth.get("access_token"),
                oauth.get("access_token_secret"),
                oauth.get("consumer_key"),
                oauth.get("key_cert"),
            )
        ):
            oauth = None

        use_kerberos = kerberos_auth.get("use_kerberos", False)
        del kerberos_auth["use_kerberos"]

        jira = JIRA(
            options=options,
            basic_auth=basic_auth,
            kerberos=use_kerberos,
            kerberos_options=kerberos_auth,
            oauth=oauth,
        )

        import IPython

        # The top-level `frontend` package has been deprecated since IPython 1.0.
        if IPython.version_info[0] >= 1:
            from IPython.terminal.embed import InteractiveShellEmbed
        else:
            from IPython.frontend.terminal.embed import InteractiveShellEmbed

        ip_shell = InteractiveShellEmbed(
            banner1="<Jira Shell " + __version__ + " (" + jira.server_url + ")>"
        )
        ip_shell("*** Jira shell active; client is in 'jira'. Press Ctrl-D to exit.")
    except Exception as e:
        print(e, file=sys.stderr)
        return 2




if __name__ == "__main__":
    status = main()
    sys.exit(status)
```

--------------------------------

### Get Project Categories

Source: https://jira.readthedocs.io/_modules/jira/client.html

Retrieves all project categories. This method is cached.

```python
@cache
def projectcategories(self):
    url = self._get_url("projectCategory")

    r = self._session.get(url)
    data = json_loads(r)

    return data
```

--------------------------------

### Instantiate Jira Client with OAuth

Source: https://jira.readthedocs.io/_modules/jira/client.html

Authentication can also be handled using OAuth by providing a dictionary with OAuth credentials.

```python
oauth = {
    "consumer_key": "my-consumer-key",
    "consumer_secret": "my-consumer-secret",
    "access_token": "my-access-token",
    "access_token_secret": "my-access-token-secret"
}
j = JIRA(oauth=oauth, options={"server": "https://jira.atlassian.com"})
```

--------------------------------

### Get a Specific Priority

Source: https://jira.readthedocs.io/_modules/jira/client.html

Retrieves a single priority resource by its ID.

```python
def priority(self, id: str) -> Priority:
        """Get a priority Resource from the server.

        Args:
            id (str): ID of the priority to get

        Returns:
            Priority
        """
        return self._find_for_resource(Priority, id)
```

--------------------------------

### main()

Source: https://jira.readthedocs.io/index.html

The main entry point of the Jira shell application.

```APIDOC
## main()

### Description
The primary function that executes the Jira shell application, handling initialization and command processing.

### Method
N/A (Function Call)

### Parameters
None
```

--------------------------------

### permalink

Source: https://jira.readthedocs.io/api.html

Get the URL of the issue, the browsable one not the REST one.

```APIDOC
## permalink()

### Description
Get the URL of the issue, the browsable one not the REST one.

### Returns
- _str_ – URL of the issue
```

--------------------------------

### Setting a Specific Jira Server

Source: https://jira.readthedocs.io/_sources/examples.rst.txt

Demonstrates how to manually set the Jira server URL during initialization. This is useful when Jira is not running on the default local address.

```python
from jira import JIRA

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

```

--------------------------------

### Get Component

Source: https://jira.readthedocs.io/_modules/jira/client.html

Retrieves a component resource from the Jira server by its ID.

```APIDOC
## component

### Description
Get a component Resource from the server.

### Method
GET

### Endpoint
/rest/api/2/component/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - ID of the component to get

### Returns
- **Component** - A Component resource object.
```

--------------------------------

### custom_field_option(_id)

Source: https://jira.readthedocs.io/api.html

Get a custom field option Resource from the server.

```APIDOC
## custom_field_option(_id)

### Description
Get a custom field option Resource from the server.

### Parameters
#### Path Parameters
- **id** (str) - Required - ID of the custom field to use

### Response
#### Success Response (200)
- **option** (CustomFieldOption) - The CustomFieldOption Resource object
```

--------------------------------

### Issue.__init__(self, jira_instance, path)

Source: https://jira.readthedocs.io/api.html

Constructor for the Issue class.

```APIDOC
## Issue.__init__(self, jira_instance, path)

### Description
Constructor for the Issue class.

### Parameters
#### Path Parameters
- **jira_instance** (JIRA) - Required - The JIRA instance object.
- **path** (str) - Required - The API path for the issue.
```

--------------------------------

### attachment(_id)

Source: https://jira.readthedocs.io/api.html

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

```APIDOC
## attachment(_id)

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

### Parameters
#### Path Parameters
- **id** (str) - Required - The Attachment ID

### Response
#### Success Response (200)
- **attachment** (Attachment) - The Attachment Resource object
```

--------------------------------

### JIRA.create_board()

Source: https://jira.readthedocs.io/index.html

Creates a new board in Jira.

```APIDOC
## JIRA.create_board()

### Description
Creates a new board in Jira.

### Method
POST

### Endpoint
/rest/agile/1.0/board

### Parameters
#### Request Body
- **name** (string) - Required - The name of the new board.
- **type** (string) - Required - The type of the board (e.g., 'scrum', 'kanban').
- **filterId** (integer) - Required - The ID of the filter that defines the issues for the board.
- **location** (object) - Optional - Specifies where the board should be created (e.g., in a specific project).
```

--------------------------------

### Get Attachment Content

Source: https://jira.readthedocs.io/_modules/jira/resources.html

Retrieves the full content of an attachment as a string.

```python
def get(self):
        """Return the file content as a string."""
        r = self._session.get(self.content, headers={"Accept": "*/*"})
        return r.content
```

--------------------------------

### QshGenerator Initialization

Source: https://jira.readthedocs.io/api.html

Initializes the QshGenerator with a context path.

```python
class jira.client.QshGenerator(_context_path_)[source]¶
    
    Bases: `object` 

    __init__(_context_path_)[source]¶
     
```

--------------------------------

### Initialize Permission Scheme Resource

Source: https://jira.readthedocs.io/_modules/jira/resources.html

Initializes a resource for project permission schemes. Requires options, session, and optionally raw data.

```python
def __init__(self, options, session, raw=None):
    Resource.__init__(self, "project/{0}/permissionscheme?expand=user", options, session)
    if raw:
        self._parse_raw(raw)
    self.raw: dict[str, Any] = cast(dict[str, Any], self.raw)
```

--------------------------------

### JIRA.approximate_issue_count()

Source: https://jira.readthedocs.io/index.html

Gets an approximate count of issues matching a JQL query.

```APIDOC
## JIRA.approximate_issue_count()

### Description
Retrieves an approximate count of issues that match a given JQL query. This is often faster than a full search.

### Method
GET

### Endpoint
/rest/api/2/search

### Parameters
#### Query Parameters
- **jql** (string) - Required - The JQL query string.
```

--------------------------------

### Get Session

Source: https://jira.readthedocs.io/_modules/jira/client.html

Retrieves information about the current authenticated user's session.

```APIDOC
## GET /rest/auth/latest/session

### Description
Get a dict of the current authenticated user's session information.

### Method
GET

### Endpoint
/rest/auth/latest/session
```

--------------------------------

### Get Resolution

Source: https://jira.readthedocs.io/_modules/jira/client.html

Retrieves a specific resolution resource from the Jira server by its ID.

```APIDOC
## GET /resolution/{id}

### Description
Gets a resolution Resource from the server.

### Method
GET

### Endpoint
/resolution/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - ID of the resolution to get

### Response
#### Success Response (200)
- **resolution** (Resolution) - The Resolution object.
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://jira.readthedocs.io/installation.html

Recommended for standalone client usage. This creates an isolated Python environment and activates it before installing the library.

```bash
python -m venv jira_python
source jira_python/bin/activate
pip install 'jira[cli]'
```

--------------------------------

### Get Resolutions

Source: https://jira.readthedocs.io/_modules/jira/client.html

Retrieves a list of all available resolution resources from the Jira server.

```APIDOC
## GET /resolution

### Description
Gets a list of resolution Resources from the server.

### Method
GET

### Endpoint
/resolution

### Response
#### Success Response (200)
- **resolutions** (list[Resolution]) - A list of Resolution objects.
```

--------------------------------

### Instantiate Jira Client with Client Certificate

Source: https://jira.readthedocs.io/_modules/jira/client.html

For client-side SSL authentication, provide the path to your certificate file (containing both cert and key) or a tuple of (cert, key) paths using the 'client_cert' option.

```python
options = {
    "server": "https://jira.atlassian.com",
    "client_cert": "/path/to/client.pem"
}
j = JIRA(options=options)
```

--------------------------------

### Get All Priorities

Source: https://jira.readthedocs.io/_modules/jira/client.html

Fetches a list of all available priority resources from the Jira server.

```python
def priorities(self) -> list[Priority]:
        """Get a list of priority Resources from the server.

        Returns:
            List[Priority]
        """
        r_json = self._get_json("priority")
        priorities = [
            Priority(self._options, self._session, raw_priority_json)
            for raw_priority_json in r_json
        ]
        return priorities
```

--------------------------------

### create_component(_name, _project, _description, _leadUserName, _assigneeType, _isAssigneeTypeValid)

Source: https://jira.readthedocs.io/api.html

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

```APIDOC
## create_component(_name, _project, _description, _leadUserName, _assigneeType, _isAssigneeTypeValid)

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

### Parameters
#### Path Parameters
- **name** (str) - Required - name of the component
- **project** (str) - Required - key of the project to create the component in
- **description** (Optional[str]) - Optional - a description of the component
- **leadUserName** (Optional[str]) - Optional - the username of the user responsible for this component
- **assigneeType** (Optional[str]) - Optional - see the ComponentBean.AssigneeType class for valid values
- **isAssigneeTypeValid** (bool) - Optional - True specifies whether the assignee type is acceptable (Default: `False`)

### Response
#### Success Response (200)
- **component** (Component) - The created Component Resource object
```

--------------------------------

### editmeta

Source: https://jira.readthedocs.io/_modules/jira/client.html

Get the edit metadata for an issue, which includes information about fields that can be edited.

```APIDOC
## editmeta issue

### Description
Get the edit metadata for an issue.

### Method
GET

### Endpoint
/rest/api/2/issue/{issue}/editmeta

### Parameters
#### Path Parameters
- **issue** (Union[str, int]) - Required - The issue to get metadata for.

### Response
#### Success Response (200)
- **Dict[str, Dict[str, Dict[str, Any]]])** - A dictionary containing the edit metadata for the issue.
```

--------------------------------

### JIRA.project_components()

Source: https://jira.readthedocs.io/index.html

Lists all components for a specific project.

```APIDOC
## JIRA.project_components()

### Description
Retrieves a list of all components associated with a specific project.

### Method
GET

### Endpoint
/rest/api/2/project/{projectIdOrKey}/components

### Parameters
#### Path Parameters
- **projectIdOrKey** (string) - Required - The ID or key of the project.
```

--------------------------------

### Get Issue

Source: https://jira.readthedocs.io/_modules/jira/client.html

Retrieves an issue resource from the Jira server by its ID or key.

```APIDOC
## issue

### Description
Retrieves an issue resource from the Jira server by its ID or key.

### Parameters
#### Path Parameters
- **id** (Union[Issue, str]) - Required - ID or key of the issue to get
#### Query Parameters
- **fields** (Optional[str]) - Optional - comma-separated string of issue fields to include in the results
- **expand** (Optional[str]) - Optional - extra information to fetch inside each resource
- **properties** (Optional[str]) - Optional - extra properties to fetch inside each result

### Returns
Issue
```

--------------------------------

### Instantiate Jira Client with Token Authentication

Source: https://jira.readthedocs.io/_modules/jira/client.html

Use the 'token_auth' argument to provide an API token for authentication.

```python
j = JIRA(token_auth='my_api_token', options={"server": "https://jira.atlassian.com"})
```

--------------------------------

### Get Dashboard Gadgets

Source: https://jira.readthedocs.io/_modules/jira/client.html

Retrieves a list of DashboardGadget resources for a specified dashboard.

```APIDOC
## GET /rest/api/2/dashboard/{dashboard_id}/gadget

### Description
Return a list of DashboardGadget resources for the specified dashboard.

### Method
GET

### Endpoint
/rest/api/2/dashboard/{dashboard_id}/gadget

### Parameters
#### Path Parameters
- **dashboard_id** (str) - Required - The ID of the dashboard to get gadgets for.

### Response
#### Success Response (200)
- **gadgets** (list[DashboardGadget]) - A list of DashboardGadget resources.
```

--------------------------------

### Create Project with Default Settings

Source: https://jira.readthedocs.io/_modules/jira/client.html

Creates a new Jira project using default settings for notification and permission schemes if not specified. It attempts to find a 'Default Permission Scheme' or uses the first available one.

```python
from jira import JIRA

# Assuming 'jira' is an instance of the JIRA client
# Example usage:
# jira_client = JIRA(server='https://your-jira-instance.atlassian.net')
# try:
#     project_id = jira_client.create_project(
#         key='NEWPROJ',
#         name='New Project',
#         assignee='user1',
#         ptype='software'
#     )
#     print(f"Project created with ID: {project_id}")
# except RuntimeError as e:
#     print(f"Error creating project: {e}")
```

--------------------------------

### Get Dashboard Item Property

Source: https://jira.readthedocs.io/_modules/jira/client.html

Retrieves a specific property for a dashboard item.

```APIDOC
## GET /rest/api/2/dashboard/{dashboard_id}/items/{item_id}/properties/{property_key}

### Description
Get the item property for a specific dashboard item.

### Method
GET

### Endpoint
/rest/api/2/dashboard/{dashboard_id}/items/{item_id}/properties/{property_key}

### Parameters
#### Path Parameters
- **dashboard_id** (str) - Required - The ID of the dashboard.
- **item_id** (str) - Required - ID of the item on the dashboard.
- **property_key** (str) - Required - KEY of the gadget property.

### Response
#### Success Response (200)
- **DashboardItemProperty** - The dashboard item property object.
```

--------------------------------

### Get Dashboard by ID

Source: https://jira.readthedocs.io/_modules/jira/client.html

Retrieves a specific dashboard by its ID and includes its gadgets.

```APIDOC
## dashboard

### Description
Get a dashboard Resource from the server by its ID. This method also fetches all associated gadgets for the dashboard.

### Method
GET (assumed based on _find_for_resource and dashboard_gadgets)

### Endpoint
/rest/api/2/dashboard/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - ID of the dashboard to get.

### Returns
- **Dashboard** - The retrieved dashboard object with its gadgets.
```
Tokens:
Raw