Metadata-Version: 2.4
Name: veeam-spc
Version: 0.4.0
Summary: Veeam Service Provider Console REST API wrapper for Python
Author-email: Jonah May <jonah@mayfamily.me>, Maurice Kevenaar <maurice@kevenaar.name>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Cenvora/veeam-spc
Project-URL: Repository, https://github.com/Cenvora/veeam-spc
Project-URL: Documentation, https://github.com/Cenvora/veeam-spc#readme
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=1.10.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

<h1 align="center">
<br>
<img src="https://raw.githubusercontent.com/Cenvora/veeam-spc/main/media/Veeam_logo_2024_RGB_main_20.png"
     alt="Veeam Logo"
     height="100">
<br>
<br>
Veeam Service Provider Console Python API Wrapper
</h1>

<h4 align="center">
Python package for interacting with the Veeam Service Provider Console REST API
</h4>

<!-- Summary -->
This project is an independent, open source Python client for the Veeam Service Provider Console <a href="https://helpcenter.veeam.com/docs/vac/rest/reference/vspc-rest.html">REST API</a>. It is not affiliated with, endorsed by, or sponsored by Veeam Software.
<!-- Summary -->

## Supported Versions

<table>
  <thead>
    <tr>
      <th>VSPC Version</th>
      <th>API Version</th>
      <th>Supported</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>9.3</td>
      <td>3.7</td>
      <td style="text-align:center;">&#9989;</td>
    </tr>
    <tr>
      <td>9.2</td>
      <td>3.6.2</td>
      <td style="text-align:center;">&#9989;</td>
    </tr>
    <tr>
      <td>9.1</td>
      <td>3.6.1</td>
      <td style="text-align:center;">&#9989;</td>
    </tr>
    <tr>
      <td>9</td>
      <td>3.6</td>
      <td style="text-align:center;">&#9989;</td>
    </tr>
    <tr>
      <td>8.1</td>
      <td>3.5.1</td>
      <td style="text-align:center;">&#9989;</td>
    </tr>
    <tr>
      <td>&lt; 8.1</td>
      <td>&lt; 3.5.1</td>
      <td style="text-align:center;">&#10060;</td>
    </tr>
  </tbody>
</table>

## How to support new API versions
1. Download the OpenAPI JSON spec into openapi_schemas
2. Install the openapi-python-client package
2. If the console gave you a **Swagger 2.0** document rather than an OpenAPI 3 one — check the
   top-level key, 3.7 shipped this way — convert it first, because openapi-python-client
   supports OpenAPI 3 only:
   `npx swagger2openapi@7 --patch --warnOnly --outfile .\openapi_schemas\vspc_rest_{vspc_version}_oas3.json .\openapi_schemas\vspc_rest_{vspc_version}.json`
   Keep both files: the download is what Veeam published, the `_oas3` file is what the rest of
   these steps consume. `--warnOnly` lets the conversion finish when the document references a
   schema it does not define; `fix_openapi_yaml.py` repairs those.
2. Fix the OpenAPI JSON spec to conform to proper standards: `python fix_openapi_yaml.py .\openapi_schemas\vspc_rest_{vspc_version}.json .\openapi_schemas\vspc_rest_{vspc_version}_fixed.json`
3. Run `openapi-python-client generate --path ".\openapi_schemas\vspc_rest_{vspc_version}_fixed.json" --output-path ".\veeam_spc" --overwrite`
4. Fix any warnings/errors (application/binary+base64 can be ignored)
5. Rename the folder to match the API version (i.e., `v3_5_1`)
6. Update versions.py and the main readme for the new version
7. Write pytest tests
8. If an older API has been deprecated, delete its folder and yaml as well as its versions.py reference, then update the supported versions section of the readme

## Install

> **Note:** This package requires **Python 3.10 or later**. If you are on Python 3.9, please use an earlier release of this library.

### From PyPi
`pip install veeam-spc`


### From Source
Clone the repository and install dependencies:
```sh
git clone https://github.com/Cenvora/veeam-spc.git
cd veeam-spc
pip install -e .
```

## Usage Tips
- For endpoints requiring authentication, use `AuthenticatedClient` instead of `Client`.
- To support multiple API versions, import the client and models from the desired versioned subpackage (e.g., `veeam_spc.v3_5_1`).
- For file downloads (PDF, CSV, etc.), access the raw response content: `response.content`.
- Refer to the generated `api` and `models` modules for available endpoints and request/response schemas.


## Usage

### Recommended Usage (Smart Client)

The `VeeamClient` handles:

- API version routing
- Authentication
- Token refresh
- `X-Client-Version` header injection so package API version matches header values
- Async calls
- Operation discovery

Each packaged version can be called independently through separate imports, but this is the **recommended way** to use this library.

#### Create a client and connect

You can authenticate using either **username/password** or a **pre-existing token**.

**Option 1: Username/Password Authentication**

```python
import asyncio
from veeam_spc.client import VeeamClient

async def main():
    vc = VeeamClient(
        host="https://vspc.example.com:1280",
        username="administrator",
        password="SuperSecretPassword",
        api_version="3.6",
        verify_ssl=False,
    )

    await vc.connect()

    # use the client...

    await vc.close()

asyncio.run(main())
```

**Option 2: Token Authentication** (recommended for long-lived access)

VSPC supports permanent tokens that don't expire, making them ideal for service accounts and CI/CD pipelines.

```python
import asyncio
from veeam_spc.client import VeeamClient

async def main():
    vc = VeeamClient(
        host="https://vspc.example.com:1280",
        token="your-permanent-token-here",
        api_version="3.6",
        verify_ssl=False,
    )

    await vc.connect()

    # use the client...

    await vc.close()

asyncio.run(main())
```

#### Detect the API version a console serves

Unlike the other Veeam products, VSPC does not version its URLs: every release since 8.1
answers on `/api/v3`, and the client declares what it understands with an `X-Client-Version`
header. So there is nothing to probe — what the console reports instead is its own build,
from `/api/v3/about`, and each console release corresponds to exactly one API version.
`detect_api_version` reads that and maps it:

```python
import asyncio
from veeam_spc.client import VeeamClient
from veeam_spc.discovery import detect_api_version

async def main():
    host = "https://vspc.example.com:1280"

    api_version = await detect_api_version(
        host,
        username="administrator",
        password="SuperSecretPassword",
        verify_ssl=False,
    )
    if api_version is None:
        # Unreachable, refused, or a console older than this library supports. Unlike the
        # other Veeam products there is no safe default to fall back on: every version
        # answers on /api/v3, so a wrong guess connects and then misparses responses
        raise RuntimeError("Could not determine the API version; set one explicitly")

    vc = VeeamClient(
        host=host,
        username="administrator",
        password="SuperSecretPassword",
        api_version=api_version,
        verify_ssl=False,
    )
    await vc.connect()

asyncio.run(main())
```

Because `/about` needs a bearer token, this is the one Veeam product where detection cannot
run before credentials exist. Detection logs in declaring the oldest version this library
ships, since an older `X-Client-Version` is the one an older console will accept; pass a
`client=` you have already connected to skip the extra login.

A console newer than anything packaged here maps to the newest version this library speaks —
VSPC keeps older `X-Client-Version` values working. A console older than 8.1 returns `None`
rather than a guess. The mapping itself is `SERVER_TO_API_VERSION`, and
`api_version_for_server("9.2.0.32907")` applies it to a version string you already have.

Resolve it once and store the result rather than detecting on every start: a console upgrade
would otherwise silently move you onto a newer version, and versions rename enum values and
add required fields.

#### Call an API endpoint (async)

```python
provider = await vc.call(
    vc.api("provider").get_provider
)

# provider is a Provider model
print(provider.name)
```

#### Call any endpoint

Operations map directly to the OpenAPI layout:

```
api/
└── provider/
    └── get_provider.py
```

Call it like this:

```python
await vc.call(
    vc.api("provider").get_provider
)
```

Or explicitly:

```python
await vc.call(
    vc.api("provider.get_provider")
)
```

#### Pagination example

```python
result = await vc.call(
    vc.api("companies").get_companies,
    limit=50,
    offset=0,
)
```

#### Close the client

```python
await vc.close()
```

### Basic Usage (Direct API Access)

If you prefer to use the versioned packages directly without the SmartClient:

First, create a client from the appropriate API version:

```python
from veeam_spc.v3_5_1 import Client

client = Client(base_url="https://server:1280/api/v3")
```

If the endpoints you're going to hit require authentication, use `AuthenticatedClient`:

```python
from veeam_spc.v3_5_1 import AuthenticatedClient

client = AuthenticatedClient(base_url="https://server:1280/api/v3", token="SuperSecretToken")
```

Now call your endpoint and use your models:

```python
from veeam_spc.v3_5_1.models import About
from veeam_spc.v3_5_1.api.about import get_about_information
from veeam_spc.v3_5_1.types import Response

with client:
    about_info: About = get_about_information.sync(client=client, x_client_version="3.5.1")
    # or if you need more info (e.g. status_code)
    response: Response[About] = get_about_information.sync_detailed(client=client, x_client_version="3.5.1")
```

#### Async Usage
Or do the same thing with an async version:

```python
from veeam_spc.v3_5_1.models import About
from veeam_spc.v3_5_1.api.about import get_about_information
from veeam_spc.v3_5_1.types import Response

client = AuthenticatedClient(base_url="https://server:1280/api/v3", token="SuperSecretToken")

async with client:
    about_info = await get_about_information.asyncio(client=client, x_client_version="3.5.1")
    response: Response[About] = await get_about_information.asyncio_detailed(client=client, x_client_version="3.5.1")
```

### SSL Verification
By default, HTTPS APIs will verify SSL certificates. You can pass a custom certificate bundle or disable verification (not recommended):

```python
from veeam_spc.v3_5_1 import AuthenticatedClient

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

# Disable SSL verification (security risk)
client = AuthenticatedClient(
    base_url="https://internal_api.example.com/api/v3",
    token="SuperSecretToken",
    verify_ssl=False
)
```

### Advanced Customizations
You can customize the underlying `httpx.Client` or `httpx.AsyncClient`:

```python
from veeam_spc.v3_5_1 import Client

def log_request(request):
    print(f"Request event hook: {request.method} {request.url} - Waiting for response")

def log_response(response):
    request = response.request
    print(f"Response event hook: {request.method} {request.url} - Status {response.status_code}")

client = Client(
    base_url="https://server:1280/api/v3",
    httpx_args={"event_hooks": {"request": [log_request], "response": [log_response]}},
)
# Or get the underlying httpx client to modify directly with client.get_httpx_client() or client.get_async_httpx_client()
```

## Contributing
Contributions are welcome! To contribute:
- Fork the repository
- Create a feature branch
- Make your changes and add tests
- Submit a pull request with a clear description

Please follow PEP8 style and include docstrings for new functions/classes.

## 🤝 Core Contributors
This project is made possible thanks to the efforts of our core contributors:

- [Jonah May](https://github.com/JonahMMay)  
- [Maurice Kevenaar](https://github.com/mkevenaar)  

We’re grateful for their continued support and contributions.
