Metadata-Version: 2.4
Name: blackduck-sca-api-client
Version: 0.3.1
Summary: Standalone Python client library for Black Duck BDSCA and BDBA APIs.
Author-email: Bogdan Mihaila <bmihaila@blackduck.com>, Matti Siipola <matti@blackduck.com>, Jussi Polet <polet@blackduck.com>
License-Expression: Apache-2.0
Keywords: blackduck,bdsca,bdba,api,client
Classifier: Programming Language :: Python
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Other Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2
Requires-Dist: structlog>=20.1.0
Requires-Dist: pydantic>=2
Requires-Dist: requests_toolbelt>=1.0.0
Requires-Dist: semantic_version>=2
Requires-Dist: protobuf<7,>=6.32.0
Dynamic: license-file

# Black Duck SCA API client

Standalone Python client library for Black Duck BDSCA and BDBA APIs.

This package provides a typed, composable API client for common Black Duck BDSCA workflows such as:

- project and version management
- BOM and component queries
- vulnerability and policy queries
- report generation and download
- scan orchestration (binary, container, SBOM, BDIO)
- users, groups, system, jobs, and custom fields

## Requirements

- Python 3.13+

## Installation
Using [pip](https://packaging.python.org/en/latest/guides/tool-recommendations/#installing-packages) or [uv](https://docs.astral.sh/uv/getting-started/installation/)

Install from local source:

```bash
pip install .
```

```bash
uv pip install .
```

Or install in editable mode for development:

```bash
pip install --editable .
```

```bash
uv sync
```

## Quick Start

### 1) Initialize client and authenticate

```python
from blackduck.bdsca.client import BDScaClient

HOST = "https://your-blackduck.example.com"
TOKEN = "your-api-token"

client = BDScaClient.from_params(
	host=HOST,
	token=TOKEN,
	max_requests_per_sec=10,
)

# Exchange token for bearer auth and store it in session headers
client.authenticate()

## Call a few common endpoints

# Current user
me = client.users.get_current_user()
print("Current user:", me.user_name)

# System status
health = client.system.liveness_check()
print("Liveness:", health.status)

# List projects (first page)
projects = client.projects.list_projects(limit=10)
for p in projects.items:
	print(p.project_id, p.name)
```

## Client Structure

The top-level BDScaClient exposes domain clients as attributes:

- client.projects
- client.projectgroups
- client.codelocations
- client.components
- client.customfields
- client.jobs
- client.licenses
- client.policies
- client.reports
- client.scans
- client.snippets
- client.system
- client.users
- client.usergroups
- client.vulnerabilities

## Error Handling

Client methods usually raise requests exceptions via response.raise_for_status() on non-2xx responses.

Typical pattern:

```python
import requests

try:
	client.authenticate()
	projects = client.projects.list_projects(limit=5)
except requests.HTTPError as exc:
	print("HTTP error:", exc)
except requests.RequestException as exc:
	print("Request error:", exc)
```

## Development

Common tasks with just:

```bash
just setup-dev
just lint
just test
```

## Notes

- Host values with or without scheme are supported; the transport normalizes the host URL.
- Authentication is explicit: call client.authenticate() before making API calls.
- The transport includes resilient adapter wiring for retries, throttling, and reauthentication callback support.
