### Setup Development Environment

Source: https://github.com/dbinfrago/polarion-rest-api-client/blob/main/README.md

Clones the repository and installs the project with development dependencies using uv. This is for setting up a local development environment.

```zsh
git clone https://github.com/dbinfrago/polarion-rest-api-client
cd polarion-rest-api-client
uv sync --extra docs --extra test
uvx pre-commit run --all-files
```

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

### Install polarion-rest-api-client

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Install the library using pip or uv. Ensure you are using Python 3.12+.

```bash
uv add polarion-rest-api-client
# or
pip install polarion-rest-api-client
```

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

### Install Python LSP Server with Linting and Formatting Plugins

Source: https://github.com/dbinfrago/polarion-rest-api-client/blob/main/CONTRIBUTING.md

Install the python-lsp-server along with necessary plugins for linting (pylint), formatting (black), import sorting (isort), and type checking (mypy). This command should be run within your virtual environment.

```zsh
pip install "python-lsp-server[pylint]" python-lsp-black pyls-isort pylsp-mypy
```

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

### Install Polarion REST API Client

Source: https://github.com/dbinfrago/polarion-rest-api-client/blob/main/README.md

Installs the latest released version of the Polarion REST API Client using uv. This is the recommended way to add the client to your project.

```zsh
uv add polarion-rest-api-client
```

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

### Initialize High-Level Polarion Client and Get Work Items

Source: https://github.com/dbinfrago/polarion-rest-api-client/blob/main/README.md

Demonstrates how to initialize the high-level Polarion client, generate a project-specific client, check project existence, and retrieve all work items for a project. Handles automatic paging for work item retrieval.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
   polarion_api_endpoint="http://127.0.0.1/api",
   polarion_access_token="PAT123",
)
project_client = client.generate_project_client("PROJ")
project_exists = project_client.exists() # Should be True
work_items = project_client.work_items.get_all()
```

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

### Initialize OpenAPI Client

Source: https://github.com/dbinfrago/polarion-rest-api-client/blob/main/README.md

Demonstrates the basic initialization of the auto-generated OpenAPI client for the Polarion REST API. No authentication is applied in this example.

```python
from polarion_rest_api_client.open_api_client import Client

client = Client(base_url="https://api.example.com")
```

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

### Client Initialization with Custom SSL Certificate

Source: https://github.com/dbinfrago/polarion-rest-api-client/blob/main/README.md

Shows how to initialize the client with a custom SSL certificate bundle for secure communication with internal APIs. Ensure the path to the certificate bundle is correct.

```python
client = AuthenticatedClient(
    base_url="https://internal_api.example.com",
    token="SuperSecretToken",
    verify_ssl="/path/to/certificate_bundle.pem",
)
```

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

### Client Initialization with SSL Verification Disabled

Source: https://github.com/dbinfrago/polarion-rest-api-client/blob/main/README.md

Illustrates how to disable SSL certificate validation. This is a security risk and should be avoided in production environments unless absolutely necessary.

```python
client = AuthenticatedClient(
    base_url="https://internal_api.example.com",
    token="SuperSecretToken",
    verify_ssl=False
)
```

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

### Run Unit Tests

Source: https://github.com/dbinfrago/polarion-rest-api-client/blob/main/CONTRIBUTING.md

Execute unit tests to ensure the development environment is set up correctly. This command should be run after setting up a virtual environment.

```zsh
pytest
```

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

### Initialize Authenticated OpenAPI Client

Source: https://github.com/dbinfrago/polarion-rest-api-client/blob/main/README.md

Shows how to initialize the OpenAPI client with authentication using an access token. This is required for accessing protected API endpoints.

```python
from polarion_rest_api_client.open_api_client import AuthenticatedClient

client = AuthenticatedClient(base_url="https://api.example.com", token="SuperSecretToken")
```

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

### Client Configuration with SSL Verification

Source: https://github.com/dbinfrago/polarion-rest-api-client/blob/main/README.md

Shows how to configure the AuthenticatedClient with custom SSL certificate bundles or disable verification.

```APIDOC
## Client Configuration

### Using a Custom Certificate Bundle
```python
from polarion_rest_api_client.open_api_client.api_client import AuthenticatedClient

client = AuthenticatedClient(
    base_url="https://internal_api.example.com",
    token="SuperSecretToken",
    verify_ssl="/path/to/certificate_bundle.pem",
)
```

### Disabling SSL Verification (Security Risk)
```python
from polarion_rest_api_client.open_api_client.api_client import AuthenticatedClient

client = AuthenticatedClient(
    base_url="https://internal_api.example.com",
    token="SuperSecretToken",
    verify_ssl=False
)
```
```

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

### PolarionClient Initialization

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Initializes the main PolarionClient, managing sessions, authentication, and request configurations. Supports basic and advanced configurations including custom SSL, pagination, and concurrency settings.

```APIDOC
## PolarionClient

Manages the HTTP session, authentication token, SSL verification, batching limits, and the asyncio semaphore for concurrent requests. All project-specific sub-clients share the same session.

### Basic Usage
```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
```

### Advanced Usage
```python
import ssl
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
    verify_ssl="/etc/ssl/certs/ca-bundle.crt",   # or False to disable (insecure)
    page_size=50,                                 # items per page when paginating
    batch_size=200,                               # items per bulk write request
    max_content_size=4 * 1024 ** 2,              # 4 MB max body
    max_async_in_flight_requests=8,              # concurrent async requests
)
```
```

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

### Create PolarionClient instance

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Instantiate the main client with your Polarion API endpoint and access token. Advanced options include custom SSL verification, page and batch sizes, content size limits, and concurrency settings.

```python
import ssl
import polarion_rest_api_client as polarion_api

# Basic usage with a Personal Access Token
client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
```

```python
# Advanced: custom SSL bundle, larger pages, more concurrency
client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
    verify_ssl="/etc/ssl/certs/ca-bundle.crt",   # or False to disable (insecure)
    page_size=50,                                 # items per page when paginating
    batch_size=200,                               # items per bulk write request
    max_content_size=4 * 1024 ** 2,              # 4 MB max body
    max_async_in_flight_requests=8,              # concurrent async requests
)
```

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

### Manage Test Runs with Polarion API Client

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Demonstrates creating, querying, and updating test runs. Ensure the PolarionClient is initialized with correct endpoint and access token.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

# Create a test run
test_run = polarion_api.TestRun(
    id="TR-001",
    title="Regression Suite Sprint 42",
    type="regression",
    status="inprogress",
    select_test_cases_by=polarion_api.SelectTestCasesBy.DYNAMICQUERYRESULT,
    query="type:testcase AND status:active",
)
project_client.test_runs.create(test_run)
print(test_run.id)  # Polarion-assigned ID

# Query test runs
runs, _ = project_client.test_runs.get_multi(query="status:inprogress")
for run in runs:
    print(run.id, run.title, run.status)

# Update a test run's status
test_run.status = "passed"
project_client.test_runs.update(test_run)
```

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

### Build Low-Level Authenticated Client

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Constructs a low-level authenticated client for direct API interaction. Ensure the base URL, token, and SSL verification path are correctly configured.

```python
low_level_client = AuthenticatedClient(
    base_url="https://polarion.example.com/polarion/rest/v1",
    token="PAT-abc123",
    verify_ssl="/etc/ssl/certs/ca-bundle.crt",
)
```

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

### Call OpenAPI Endpoint and Use Models

Source: https://github.com/dbinfrago/polarion-rest-api-client/blob/main/README.md

Illustrates how to call a specific API endpoint using the initialized OpenAPI client and how to use the generated data models for request and response handling.

```python
from polarion_rest_api_client.open_api_client.models import MyDataModel
from polarion_rest_api_client.open_api_client.api.my_tag import get_my_data_model
from polarion_rest_api_client.open_api_client.types import Response

my_data: MyDataModel = get_my_data_model.sync(client=client)
```

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

### Synchronous and Asynchronous API Calls

Source: https://github.com/dbinfrago/polarion-rest-api-client/blob/main/README.md

Demonstrates how to fetch data using both synchronous and asynchronous methods, including detailed response handling.

```APIDOC
## Fetching Data

### Synchronous Call
```python
from polarion_rest_api_client.open_api_client.models import MyDataModel
from polarion_rest_api_client.open_api_client.api.my_tag import get_my_data_model
from polarion_rest_api_client.open_api_client.types import Response

# Get parsed data
my_data: MyDataModel = get_my_data_model.sync(client=client)

# Get detailed response object
response: Response[MyDataModel] = get_my_data_model.sync_detailed(client=client)
```

### Asynchronous Call
```python
from polarion_rest_api_client.open_api_client.models import MyDataModel
from polarion_rest_api_client.open_api_client.api.my_tag import get_my_data_model
from polarion_rest_api_client.open_api_client.types import Response

# Get parsed data asynchronously
my_data: MyDataModel = await get_my_data_model.asyncio(client=client)

# Get detailed response object asynchronously
response: Response[MyDataModel] = await get_my_data_model.asyncio_detailed(client=client)
```
```

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

### Fetch all Work Items with auto-pagination

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Use `get_all` to retrieve all Work Items matching a query, handling pagination automatically. Specify fields to retrieve for efficiency.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

# Get every work item in the project
all_items = project_client.work_items.get_all()

# Filter with a Polarion query
requirements = project_client.work_items.get_all(
    query="type:requirement AND status:open",
    fields={"workitems": "id,title,status,description"},
)

for wi in requirements:
    print(wi.id, wi.title, wi.status)
# Expected output:
# REQ-001  System shall boot in 5 s  open
# REQ-002  System shall support IPv6  open
```

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

### Configure Default Sparse Field Sets

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Allows configuring default fields fetched for resource types globally. Adjust before making requests to include or exclude specific fields.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)

# Fetch only id + title + status by default for work items
client.default_fields.workitems = "id,title,status"

# Fetch all fields for linked work items
client.default_fields.linkedworkitems = "@all"

# Use the merged dict directly in a request
project_client = client.generate_project_client("MY_PROJECT")
items = project_client.work_items.get_all(
    fields=client.default_fields.all_types   # combined dict for all resource types
)
```

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

### ProjectClient.work_items.get_all

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Fetches all Work Items within a project, automatically handling pagination. Allows filtering with Polarion queries and specifying fields to retrieve.

```APIDOC
## ProjectClient.work_items.get_all

`get_all` transparently pages through all results using `get_multi` under the hood, accumulating every item that matches the Polarion query string.

### Fetch All Work Items
```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

all_items = project_client.work_items.get_all()
```

### Fetch Filtered Work Items
```python
requirements = project_client.work_items.get_all(
    query="type:requirement AND status:open",
    fields={"workitems": "id,title,status,description"},
)

for wi in requirements:
    print(wi.id, wi.title, wi.status)
```
```

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

### Synchronous and Asynchronous Data Fetching

Source: https://github.com/dbinfrago/polarion-rest-api-client/blob/main/README.md

Demonstrates how to fetch data using both synchronous and asynchronous methods. The `sync_detailed` method returns a detailed response object, while `asyncio` and `asyncio_detailed` are for asynchronous operations.

```python
from polarion_rest_api_client.open_api_client.models import MyDataModel
from polarion_rest_api_client.open_api_client.api.my_tag import get_my_data_model
from polarion_rest_api_client.open_api_client.types import Response

response: Response[MyDataModel] = get_my_data_model.sync_detailed(client=client)

my_data: MyDataModel = await get_my_data_model.asyncio(client=client)
response: Response[MyDataModel] = await get_my_data_model.asyncio_detailed(client=client)
```

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

### Create Work Items

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Creates one or a list of WorkItem objects. The client automatically handles batching to respect server limits. Server-assigned IDs are written back to the objects.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

new_item = polarion_api.WorkItem(
    title="New requirement",
    type="requirement",
    status="draft",
    description=polarion_api.TextContent("text/html", "<p>The system shall...</p>"),
)
project_client.work_items.create(new_item)
print(new_item.id)  # "REQ-042"  (assigned by Polarion)

# Bulk create
items = [
    polarion_api.WorkItem(title=f"Task {i}", type="task")
    for i in range(50)
]
project_client.work_items.create(items)
```

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

### Record Test Execution Results with Polarion API Client

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Shows how to create and fetch test records for a given test run. Requires a valid test run ID and work item ID.

```python
import datetime
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

record = polarion_api.TestRecord(
    test_run_id="TR-001",
    work_item_project_id="MY_PROJECT",
    work_item_id="TC-010",
    result="passed",
    duration=12.5,
    executed=datetime.datetime(2024, 6, 1, 10, 30, 0),
    executed_by="jsmith",
    comment=polarion_api.HtmlContent("<p>All assertions passed.</p>"),
)
project_client.test_runs.records.create(record)

# Fetch all records for a test run
records = project_client.test_runs.records.get_all("TR-001")
for rec in records:
    print(rec.work_item_id, rec.result, rec.duration)
```

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

### Manage Polarion Live Documents

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Access Polarion Live Documents via `project_client.documents`. Documents are identified by `space_id` and `document_name`. Supports fetching, creating, and updating documents.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

# Fetch a document
doc = project_client.documents.get(
    space_id="_default",
    document_name="SystemRequirements",
)
if doc:
    print(doc.title, doc.status)

# Create a new document
new_doc = polarion_api.Document(
    module_folder="_default",
    module_name="NewSpec",
    title="New Specification",
    type="specification",
    status="draft",
    home_page_content=polarion_api.HtmlContent("<h1>Introduction</h1>"),
    outline_numbering=True,
)
project_client.documents.create(new_doc)

# Update a document's status and title
doc.status = "approved"
doc.title = "System Requirements v2"
project_client.documents.update(doc)
```

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

### Paginated Work Item query

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Use `get_multi` for manual control over pagination, returning a page of items and a flag indicating if more pages exist. Useful for streaming results.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

page = 1
while True:
    items, has_next = project_client.work_items.get_multi(
        query="type:task",
        page_size=25,
        page_number=page,
        fields={"workitems": "id,title,status"},
    )
    for wi in items:
        print(wi.id, wi.title)
    if not has_next:
        break
    page += 1
```

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

### ProjectClient.work_items.get_multi

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Retrieves a single page of Work Items based on a Polarion query, returning the items and a flag indicating if more pages are available. Useful for manual pagination or streaming results.

```APIDOC
## ProjectClient.work_items.get_multi

Returns one page of Work Items plus a boolean indicating whether a next page exists. Use this when you need manual control over pagination or want to stream results.

### Paginated Query
```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

page = 1
while True:
    items, has_next = project_client.work_items.get_multi(
        query="type:task",
        page_size=25,
        page_number=page,
        fields={"workitems": "id,title,status"},
    )
    for wi in items:
        print(wi.id, wi.title)
    if not has_next:
        break
    page += 1
```
```

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

### Manage Work Item Attachments

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Use `project_client.work_items.attachments` to upload, list, and delete binary attachments. Ensure `content_bytes`, `file_name`, and `mime_type` are provided for uploads.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

# Upload a new attachment
with open("diagram.png", "rb") as f:
    data = f.read()

attachment = polarion_api.WorkItemAttachment(
    work_item_id="REQ-001",
    id="",                   # assigned by Polarion on creation
    title="Architecture Diagram",
    content_bytes=data,
    file_name="diagram.png",
    mime_type="image/png",
)
project_client.work_items.attachments.create(attachment)
print(attachment.id)  # "diagram.png" or server-assigned ID

# List attachments for a work item
attachments, _ = project_client.work_items.attachments.get_multi("REQ-001")
for att in attachments:
    print(att.id, att.title, att.file_name)

# Delete an attachment
project_client.work_items.attachments.delete(attachment)
```

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

### Generate ProjectClient

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Obtain a project-specific client from the main PolarionClient. Supports hard-deletion (default) or soft-deletion by setting a status.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)

# Hard-delete mode (default)
project_client = client.generate_project_client("MY_PROJECT")

# Soft-delete mode: sets status to "obsolete" instead of deleting
project_client = client.generate_project_client(
    "MY_PROJECT", delete_status="obsolete"
)

if project_client.exists():
    print("Project found.")
else:
    print("Project not found.")
```

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

### PolarionClient.generate_project_client

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Generates a ProjectClient instance for a specific Polarion project. Supports both hard-delete and soft-delete modes for Work Items.

```APIDOC
## PolarionClient.generate_project_client

Returns a `ProjectClient` bound to a specific Polarion project. Optionally supply `delete_status` to soft-delete Work Items by status instead of hard-deleting them.

### Hard-delete Mode (Default)
```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")
```

### Soft-delete Mode
```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client(
    "MY_PROJECT", delete_status="obsolete"
)
```

### Check Project Existence
```python
if project_client.exists():
    print("Project found.")
else:
    print("Project not found.")
```
```

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

### Define and Use Custom Work Item Class

Source: https://github.com/dbinfrago/polarion-rest-api-client/blob/main/README.md

Shows how to define a custom Work Item class inheriting from the base class to include custom fields. This allows direct attribute access to custom fields instead of accessing them through 'additional_attributes'.

```python
import polarion_rest_api_client as polarion_api
import dataclasses

@dataclasses.dataclass
class CustomWorkItem(polarion_api.WorkItem):
   capella_uuid: str | None = None

client = polarion_api.PolarionClient(
   polarion_api_endpoint="http://127.0.0.1/api",
   polarion_access_token="PAT123",
)
project_client = client.generate_project_client("PROJ")
work_items = project_client.work_items.get_all(work_item_cls=CustomWorkItem)
uuid = work_items[0].capella_uuid # the value of the custom field capella_uuid can be accessed this way
```

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

### ProjectClient.work_items.create

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Creates one or a list of WorkItem objects. The method handles batching to respect server limits and writes the server-assigned IDs back into the objects after creation.

```APIDOC
## ProjectClient.work_items.create — create Work Items

### Description
Creates one or a list of `WorkItem` objects, automatically splitting into batches that respect the server's maximum body size. The server-assigned IDs are written back into the passed objects after creation.

### Method
`create(work_item: WorkItem | list[WorkItem])`

### Parameters
#### Request Body
- **work_item** (WorkItem or list[WorkItem]) - Required - The WorkItem object(s) to create.

### Request Example
```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

new_item = polarion_api.WorkItem(
    title="New requirement",
    type="requirement",
    status="draft",
    description=polarion_api.TextContent("text/html", "<p>The system shall...</p>"),
)
project_client.work_items.create(new_item)
print(new_item.id)  # "REQ-042"  (assigned by Polarion)

# Bulk create
items = [
    polarion_api.WorkItem(title=f"Task {i}", type="task")
    for i in range(50)
]
project_client.work_items.create(items)
```

### Response
#### Success Response (200)
- **None** - The creation is confirmed, and IDs are updated in the passed objects.

#### Response Example
(No explicit response body example provided, success is indicated by updated object IDs)
```

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

### TestRuns Management

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Manage test runs and their lifecycle, including creation, querying, updating, and deletion. Each TestRun exposes sub-clients for records and parameters.

```APIDOC
## TestRuns — manage test runs and their lifecycle

`project_client.test_runs` supports creating, querying, updating, and deleting test runs. Each `TestRun` exposes sub-clients `.records` and `.parameters`.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_rest_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

# Create a test run
test_run = polarion_api.TestRun(
    id="TR-001",
    title="Regression Suite Sprint 42",
    type="regression",
    status="inprogress",
    select_test_cases_by=polarion_api.SelectTestCasesBy.DYNAMICQUERYRESULT,
    query="type:testcase AND status:active",
)
project_client.test_runs.create(test_run)
print(test_run.id)  # Polarion-assigned ID

# Query test runs
runs, _ = project_client.test_runs.get_multi(query="status:inprogress")
for run in runs:
    print(run.id, run.title, run.status)

# Update a test run's status
test_run.status = "passed"
project_client.test_runs.update(test_run)
```
```

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

### DefaultFields Configuration

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Configure default sparse field sets for resource types. Adjust before making requests to include or exclude specific fields globally.

```APIDOC
## DefaultFields — configure default sparse field sets

`client.default_fields` controls which fields are fetched by default for each resource type. Adjust before making requests to include or exclude specific fields globally.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_rest_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)

# Fetch only id + title + status by default for work items
client.default_fields.workitems = "id,title,status"

# Fetch all fields for linked work items
client.default_fields.linkedworkitems = "@all"

# Use the merged dict directly in a request
project_client = client.generate_project_client("MY_PROJECT")
items = project_client.work_items.get_all(
    fields=client.default_fields.all_types   # combined dict for all resource types
)
```
```

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

### Perform Async Operations on Work Items

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Use async counterparts for bulk operations like get_all, update, and create. Configure `max_async_in_flight_requests` on the client for concurrency control.

```python
import asyncio
import polarion_rest_api_client as polarion_api

async def sync_work_items() -> None:
    client = polarion_api.PolarionClient(
        polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
        polarion_access_token="PAT-abc123",
        max_async_in_flight_requests=4,
    )
    project_client = client.generate_project_client("MY_PROJECT")

    # Fetch all requirements asynchronously
    items = await project_client.work_items.async_get_all(query="type:requirement")

    # Bulk update asynchronously (batches run concurrently)
    for wi in items:
        wi.status = "reviewed"
    await project_client.work_items.async_update(items)

    # Async create
    new_items = [polarion_api.WorkItem(title=f"New-{i}", type="task") for i in range(20)]
    await project_client.work_items.async_create(new_items)

asyncio.run(sync_work_items())
```

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

### Create and Manage Work Item Links

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Utilize `project_client.work_items.links` for CRUD operations on `WorkItemLink` objects. Links define directional, typed relationships between Work Items.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

# Create a link: REQ-001 "verifies" TEST-005
link = polarion_api.WorkItemLink(
    primary_work_item_id="REQ-001",
    secondary_work_item_id="TEST-005",
    role="verifies",
    suspect=False,
    secondary_work_item_project="MY_PROJECT",
)
project_client.work_items.links.create(link)

# Get all links for a work item
links, has_next = project_client.work_items.links.get_multi("REQ-001")
for lnk in links:
    print(lnk.role, lnk.secondary_work_item_id)

# Delete a specific link
project_client.work_items.links.delete(link)
```

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

### WorkItemAttachments

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Manage binary attachments on Work Items, including uploading, updating, and deleting. Requires `content_bytes`, `file_name`, and `mime_type` for uploads.

```APIDOC
## WorkItemAttachments — upload, update, and delete attachments

`project_client.work_items.attachments` manages binary attachments on Work Items. The `content_bytes`, `file_name`, and `mime_type` fields are required for upload.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

# Upload a new attachment
with open("diagram.png", "rb") as f:
    data = f.read()

attachment = polarion_api.WorkItemAttachment(
    work_item_id="REQ-001",
    id="",                   # assigned by Polarion on creation
    title="Architecture Diagram",
    content_bytes=data,
    file_name="diagram.png",
    mime_type="image/png",
)
project_client.work_items.attachments.create(attachment)
print(attachment.id)  # "diagram.png" or server-assigned ID

# List attachments for a work item
attachments, _ = project_client.work_items.attachments.get_multi("REQ-001")
for att in attachments:
    print(att.id, att.title, att.file_name)

# Delete an attachment
project_client.work_items.attachments.delete(attachment)
```
```

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

### Configure VS Code for Python Linting and Formatting

Source: https://github.com/dbinfrago/polarion-rest-api-client/blob/main/CONTRIBUTING.md

Set up Visual Studio Code to automatically organize Python imports on save. Ensure your VS Code settings are correctly configured for this feature.

```json
{
    "[python]": {
        "editor.codeActionsOnSave": {
            "source.organizeImports": true
        }
    }
}
```

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

### Documents

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Access and manage Polarion Live Documents (module documents) using `project_client.documents`. Documents are identified by `space_id` and `document_name`.

```APIDOC
## Documents — get, create, and update Polarion Live Documents

`project_client.documents` provides access to Polarion Live Documents (module documents). Documents are addressed by `space_id` (module folder) and `document_name`.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

# Fetch a document
doc = project_client.documents.get(
    space_id="_default",
    document_name="SystemRequirements",
)
if doc:
    print(doc.title, doc.status)

# Create a new document
new_doc = polarion_api.Document(
    module_folder="_default",
    module_name="NewSpec",
    title="New Specification",
    type="specification",
    status="draft",
    home_page_content=polarion_api.HtmlContent("<h1>Introduction</h1>"),
    outline_numbering=True,
)
project_client.documents.create(new_doc)

# Update a document's status and title
doc.status = "approved"
doc.title = "System Requirements v2"
project_client.documents.update(doc)
```
```

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

### WorkItemLinks

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Create and manage directional, typed relationships between Work Items using the `project_client.work_items.links` interface.

```APIDOC
## WorkItemLinks — create and manage links between Work Items

`project_client.work_items.links` provides CRUD for `WorkItemLink` objects, which represent directional, typed relationships between Work Items.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

# Create a link: REQ-001 "verifies" TEST-005
link = polarion_api.WorkItemLink(
    primary_work_item_id="REQ-001",
    secondary_work_item_id="TEST-005",
    role="verifies",
    suspect=False,
    secondary_work_item_project="MY_PROJECT",
)
project_client.work_items.links.create(link)

# Get all links for a work item
links, has_next = project_client.work_items.links.get_multi("REQ-001")
for lnk in links:
    print(lnk.role, lnk.secondary_work_item_id)

# Delete a specific link
project_client.work_items.links.delete(link)
```
```

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

### Error Handling

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Understand the exception hierarchy for API errors and internal problems. The library handles retries for certain errors with exponential backoff.

```APIDOC
## Error handling — exception hierarchy

The library raises structured exceptions for API errors and internal problems. Non-retriable errors (400, 404, 418) are raised immediately; other errors are retried up to 5 times with exponential backoff.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_rest_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

try:
    wi = polarion_api.WorkItem(title="Bad item")  # missing required "type"
    project_client.work_items.create(wi)
except polarion_api.PolarionWorkItemException as e:
    # Raised for item-level validation problems; exposes the offending WorkItem
    print("WorkItem error:", e, "| item:", e.work_item.title)
except polarion_api.PolarionApiException as e:
    # Raised for HTTP 4xx/5xx responses with structured error details from Polarion
    print("API error (status", e.args[0], "):", e.args[1:])
except polarion_api.PolarionApiUnexpectedException as e:
    # Raised for unexpected non-JSON error responses
    print("Unexpected error:", e)
except polarion_api.PolarionApiBaseException as e:
    # Catch-all for any polarion API error
    print("Base API error:", e)
```
```

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

### Asynchronously Fetch Work Items

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Fetches work items using the asynchronous detailed method. This is suitable for non-blocking operations within an asyncio event loop. Requires the `asyncio` library.

```python
import asyncio
async def fetch():
    resp = await get_work_items.asyncio_detailed(
        project_id="MY_PROJECT",
        client=low_level_client,
        query="type:task",
    )
    return resp

asyncio.run(fetch())
```

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

### Handle Polarion API Errors

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Illustrates the exception hierarchy for API errors. Non-retriable errors are raised immediately, while others are retried with exponential backoff.

```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

try:
    wi = polarion_api.WorkItem(title="Bad item")  # missing required "type"
    project_client.work_items.create(wi)
except polarion_api.PolarionWorkItemException as e:
    # Raised for item-level validation problems; exposes the offending WorkItem
    print("WorkItem error:", e, "| item:", e.work_item.title)
except polarion_api.PolarionApiException as e:
    # Raised for HTTP 4xx/5xx responses with structured error details from Polarion
    print("API error (status", e.args[0], "):", e.args[1:])
except polarion_api.PolarionApiUnexpectedException as e:
    # Raised for unexpected non-JSON error responses
    print("Unexpected error:", e)
except polarion_api.PolarionApiBaseException as e:
    # Catch-all for any polarion API error
    print("Base API error:", e)
```

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

### Low-level OpenAPI Client Access

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Provides direct access to every Polarion REST endpoint via the auto-generated open_api_client. Each endpoint has sync and async functions.

```python
from polarion_rest_api_client.open_api_client import AuthenticatedClient
from polarion_rest_api_client.open_api_client.api.work_items import get_work_items
from polarion_rest_api_client.open_api_client.types import Response

```

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

### Synchronously Fetch Work Items

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Fetches work items using the synchronous detailed method. The response object contains status code, headers, content, and parsed data. Handles pagination and filtering via query parameters.

```python
response: Response = get_work_items.sync_detailed(
    project_id="MY_PROJECT",
    client=low_level_client,
    query="type:requirement",
    pagesize=10,
    pagenumber=1,
)

print(response.status_code)   # 200
if response.parsed and response.parsed.data:
    for item in response.parsed.data:
        print(item.id, item.attributes.title if item.attributes else "")
```

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

### Low-level OpenAPI Client

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Access every Polarion REST endpoint directly using the auto-generated OpenAPI client layer. Each endpoint has sync and async functions.

```APIDOC
## Low-level OpenAPI client — direct endpoint access

The auto-generated `open_api_client` layer exposes every Polarion REST endpoint as a Python module with four functions each: `sync`, `sync_detailed`, `asyncio`, and `asyncio_detailed`.

```python
from polarion_rest_api_client.open_api_client import AuthenticatedClient
from polarion_rest_api_client.open_api_client.api.work_items import get_work_items
from polarion_rest_api_client.open_api_client.types import Response
```
```

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

### Custom WorkItem subclass

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Demonstrates how to create typed custom fields for Work Items by inheriting from `WorkItem` and declaring custom Polarion fields as dataclass fields.

```APIDOC
## Custom WorkItem subclass — typed custom fields

### Description
Inherit from `WorkItem` and declare custom Polarion fields as dataclass fields. These become first-class attributes instead of being hidden in `additional_attributes`.

### Usage
Define a new class inheriting from `polarion_api.WorkItem` and use dataclasses to define custom fields.

### Request Example
```python
import dataclasses
import polarion_rest_api_client as polarion_api

@dataclasses.dataclass
class MyWorkItem(polarion_api.WorkItem):
    capella_uuid: str | None = None
    risk_level: str | None = None

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

items = project_client.work_items.get_all(
    query="type:requirement",
    work_item_cls=MyWorkItem,
)
for wi in items:
    print(wi.capella_uuid, wi.risk_level)  # typed attribute access
```

### Response
#### Success Response (200)
- **WorkItem** - WorkItem objects with custom fields accessible as direct attributes.

#### Response Example
```json
{
  "id": "REQ-001",
  "title": "Example Requirement",
  "type": "requirement",
  "capella_uuid": "some-uuid-123",
  "risk_level": "high"
}
```
```

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

### Async Operations

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Perform bulk operations asynchronously for creating, updating, and retrieving work items. The client manages concurrency with `max_async_in_flight_requests`.

```APIDOC
## Async operations — async_create, async_update, async_get_all

Every high-level operation has an `async_` counterpart. Async bulk operations execute batches concurrently, limited by `max_async_in_flight_requests`.

```python
import asyncio
import polarion_rest_api_client as polarion_api

async def sync_work_items() -> None:
    client = polarion_api.PolarionClient(
        polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
        polarion_access_token="PAT-abc123",
        max_async_in_flight_requests=4,
    )
    project_client = client.generate_project_client("MY_PROJECT")

    # Fetch all requirements asynchronously
    items = await project_client.work_items.async_get_all(query="type:requirement")

    # Bulk update asynchronously (batches run concurrently)
    for wi in items:
        wi.status = "reviewed"
    await project_client.work_items.async_update(items)

    # Async create
    new_items = [polarion_api.WorkItem(title=f"New-{i}", type="task") for i in range(20)]
    await project_client.work_items.async_create(new_items)

asyncio.run(sync_work_items())
```
```

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

### ProjectClient.work_items.get

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Fetches a single Work Item by its ID. It returns a fully populated WorkItem object, including linked items, attachments, and custom fields. It also indicates if relationship collections are truncated.

```APIDOC
## ProjectClient.work_items.get — fetch a single Work Item by ID

### Description
Returns a fully populated `WorkItem` including all linked work items, attachments, and custom fields. Sets `linked_work_items_truncated` or `attachments_truncated` to `True` when the relationship collections exceed the API's inline limit.

### Method
`get(id: str, revision: str | None = None)`

### Parameters
#### Path Parameters
- **id** (str) - Required - The ID of the Work Item to fetch.
- **revision** (str, optional) - The specific revision of the Work Item to fetch.

### Request Example
```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

wi = project_client.work_items.get("REQ-001")
if wi:
    print(wi.id)           # "REQ-001"
    print(wi.title)        # "System shall boot in 5 s"
    print(wi.status)       # "open"
    print(wi.description)  # TextContent(type="text/html", value="<p>...</p>")
    print(wi.linked_work_items_truncated)  # True if too many to inline

# Fetch a specific historical revision
wi_v3 = project_client.work_items.get("REQ-001", revision="3")
```

### Response
#### Success Response (200)
- **WorkItem** - A WorkItem object with its attributes populated.

#### Response Example
```json
{
  "id": "REQ-001",
  "title": "System shall boot in 5 s",
  "status": "open",
  "description": {
    "type": "text/html",
    "value": "<p>...</p>"
  },
  "linked_work_items_truncated": false
}
```
```

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

### ProjectClient.work_items.update

Source: https://context7.com/dbinfrago/polarion-rest-api-client/llms.txt

Updates the provided WorkItem or a list of WorkItems. Only fields that are set (non-None) are sent to the server, and the method respects the server's bulk request body limit.

```APIDOC
## ProjectClient.work_items.update — update Work Items

### Description
Updates the provided `WorkItem` or list of items. Only fields that are set (non-`None`) are sent. Respects the server's bulk request body limit.

### Method
`update(work_item: WorkItem | list[WorkItem])`

### Parameters
#### Request Body
- **work_item** (WorkItem or list[WorkItem]) - Required - The WorkItem object(s) to update.

### Request Example
```python
import polarion_rest_api_client as polarion_api

client = polarion_api.PolarionClient(
    polarion_api_endpoint="https://polarion.example.com/polarion/rest/v1",
    polarion_access_token="PAT-abc123",
)
project_client = client.generate_project_client("MY_PROJECT")

wi = project_client.work_items.get("REQ-001")
if wi:
    wi.status = "approved"
    wi.title = "System shall boot in under 5 s"
    project_client.work_items.update(wi)

# Bulk status update
all_drafts = project_client.work_items.get_all(query="status:draft")
for item in all_drafts:
    item.status = "review"
project_client.work_items.update(all_drafts)
```

### Response
#### Success Response (200)
- **None** - The update is confirmed.

#### Response Example
(No explicit response body example provided, success is indicated by the update operation completing.)
```