Metadata-Version: 2.3
Name: client-for-vantage
Version: 1.0.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-Dist: pendulum>=3.0.0
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

# Client for Vantage

![Python 3.10](https://img.shields.io/badge/Python-3.10-blue.svg)
![Python 3.11](https://img.shields.io/badge/Python-3.11-blue.svg)
![Python 3.12](https://img.shields.io/badge/Python-3.12-blue.svg)

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

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",
    date_interval=DateInterval.this_month,
    chart_type=ChartType.line,
    date_bin=DateBin.cumulative
)

response = vantage.create_cost_report(cost_report)
```

## Supported Endpoints

This SDK supports all endpoints from the Vantage API. While comprehensive test coverage exists for most endpoints, some endpoints have limited test coverage due to various constraints.

### 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

## Contributing

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