Metadata-Version: 2.3
Name: client-for-vantage
Version: 1.2.0
Summary: An SDK for interacting with the Vantage API, attempts to maintain parity with the API, provides type safety via codegen Pydantic classes and manages pagination
Keywords: vantage,api,sdk
Author: Orest Tokovenko
Author-email: Orest Tokovenko <oresttokovenko@block.xyz>
License: Apache-2.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: pydantic>=2.10.6
Requires-Dist: pydantic-settings>=2.7.1
Requires-Dist: pydantic-extra-types>=2.10.2
Requires-Dist: httpx>=0.28.1
Requires-Python: >=3.10, <3.13
Project-URL: Homepage, https://github.com/block/client-for-vantage
Project-URL: Issues, https://github.com/block/client-for-vantage/issues
Project-URL: Repository, https://github.com/block/client-for-vantage
Description-Content-Type: text/markdown

<h1 align="center">Client for Vantage</h1>

<p align="center">
<a href="https://github.com/block/client-for-vantage/actions/workflows/python-test.yml?query=event%3Apush+branch%3Amain" target="_blank">
    <img src="https://github.com/block/client-for-vantage/actions/workflows/python-test.yml/badge.svg?event=push&branch=main" alt="Tests">
</a>
<a href="https://pypi.org/project/client-for-vantage" target="_blank">
    <img src="https://img.shields.io/pypi/v/client-for-vantage?color=%2334D058&label=pypi%20package" alt="Package version">
</a>
<a href="https://pypi.org/project/client-for-vantage" target="_blank">
    <img src="https://img.shields.io/pypi/pyversions/client-for-vantage.svg?color=%2334D058" alt="Supported Python versions">
</a>
<a href="https://github.com/block/client-for-vantage/blob/main/LICENSE" target="_blank">
    <img src="https://img.shields.io/pypi/l/client-for-vantage?color=%2334D058" alt="License">
</a>
<a href="https://docs.pydantic.dev" target="_blank">
    <img src="https://img.shields.io/badge/Pydantic-v2-%23D338E2" alt="Pydantic v2">
</a>
</p>

This SDK is a Python client built around the [Vantage API], providing a streamlined interface to work with numerous API endpoints. It leverages asynchronous programming and concurrency to efficiently handle data retrieval across multiple pages, significantly reducing wait times through parallel request processing. It also provides comprehensive type support through Pydantic 2.0 BaseModels, which were generated by parsing the API's OpenAPI spec. This ensures type safety and provides excellent IDE autocompletion while maintaining strict validation of request and response data - no need to constantly refer to the API documentation.

[Vantage API]: https://vantage.readme.io/reference/general

## Usage

### Install the library

`uv add client-for-vantage`

### Inititate the SDK

```python
from vantage_sdk import VantageSDK
from vantage_sdk.models import (
    CreateCostReport,
    CreateCostReportChartType,
    CreateCostReportDateBin,
)

vantage = VantageSDK(vantage_api_key)

cost_report = CreateCostReport(
    title="Test Cost Report",
    workspace_token="workspace_abcdef123456",
    groupings="provider,service,region",
    filter="costs.provider = 'aws'",
    saved_filter_tokens=["sf_1", "sf_2"],
    business_metric_tokens_with_metadata=[business_metric_1, business_metric_2],
    folder_token="folder_abcdef123456",
    settings=settings,
    previous_period_start_date="2024-01-01",
    previous_period_end_date="2024-01-31",
    start_date="2024-02-01",
    end_date="2024-02-28",
    chart_type=CreateCostReportChartType.line,
    date_bin=CreateCostReportDateBin.cumulative,
)

response = vantage.create_cost_report(cost_report)
```

## Supported Endpoints

This SDK supports all endpoints from the Vantage API. Most endpoints are covered by live API tests, but a small set of methods are skipped in CI because they require special permissions or account configuration. Those skipped methods are expected to work based on the OpenAPI spec and we keep the request and response models aligned with it, but we cannot validate them in automated tests. The remaining methods are verified against the live API and are expected to work as implemented.

### Endpoints with Testing Limitations

The following endpoints are available but should be used with caution as they have limited automated test coverage

- **Anomaly Alerts**: API access is limited as these can only be created via the UI
- **Billing Rules**: Requires special enterprise permissions
- **Managed Accounts**: Requires special enterprise permissions
- **Resources**: Performance issues with bulk operations
- **Tags**: Limited test coverage
- **Unit Costs**: Requires actual cost data for exports
- **User Feedback**: Limited testing to avoid creating test data in production
- **Workspaces**: Limited testing to avoid affecting production workspaces
- **Teams**: Sandbox account lacks team permissions, so related tests are skipped in VCR recordings
- **Tags**: Sandbox account has no tags configured, so tag update and value tests are skipped in VCR recordings

## Contributing

See [CONTRIBUTORS.md](CONTRIBUTORS.md) for development setup, testing guidelines, and instructions for regenerating models.

## Testing

See [CONTRIBUTORS.md](CONTRIBUTORS.md) for VCR-backed and live testing workflows.
