Metadata-Version: 2.4
Name: aspiaspace
Version: 0.1.1
Summary: Python SDK for the Aspia Space REST API
Project-URL: Homepage, https://api.aspiaspace.com/v1/reference/
Author-email: Aspia Space <contact@aspiaspace.com>
License: Proprietary
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: requests>=2.28
Description-Content-Type: text/markdown

﻿# AspiaSpace Python SDK

The official Python client for interacting with the [Aspia APIs](https://api.aspiaspace.com/v1/docs/).
This SDK handles authentication, response formatting, automatic retries, and robust error handling
out of the box — so you can focus on working with your data rather than managing HTTP requests.

To get started, you'll need an Aspia account with a client ID and secret. Contact
`contact@aspiaspace.com` to request a trial, or visit [aspiaspace.com](https://aspiaspace.com).

## Key Features

-  **Automatic authentication** — handles token acquisition and renewal using your client ID and secret
-  **Automatic retries** — built-in retry logic for transient network and server errors
-  **Response formatting** — responses are returned in structured, user-friendly formats
-  **Robust error handling** — clear exceptions with actionable messages
-  **Full endpoint coverage** — supports the customer areas, Vigour, ALT, and weather endpoints

## Requirements

### Python Requirements

![Python](https://img.shields.io/badge/Python-3.12%2B-blue)

This package requires **Python 3.12 or higher**.

### System Requirements

![macOS](https://img.shields.io/badge/macOS-supported-brightgreen)
![Linux](https://img.shields.io/badge/Linux-supported-brightgreen)
![Windows](https://img.shields.io/badge/Windows-supported-brightgreen)

This package is compatible with **macOS**, **Linux**, and **Windows**.

## Installation

Install the SDK from PyPI using pip:

```bash
pip install aspiaspace
```

## Quick Start

Construct an `AspiaSpace` instance with your credentials, then call any of the available
service attributes to start making requests:

```python
from aspiaspace import AspiaSpace

sdk = AspiaSpace(
    client_id="your-client-id",
    client_secret="your-client-secret",
)

# List all customers
customers = sdk.customers.list()
```

We recommend storing your credentials in environment variables rather than hardcoding them:

```python
import os
from aspiaspace import AspiaSpace

sdk = AspiaSpace(
    client_id=os.environ["ASPIA_CLIENT_ID"],
    client_secret=os.environ["ASPIA_CLIENT_SECRET"],
)
```

## Authentication

All requests are authenticated using your **client ID** and **client secret**, which are
issued when you register with Aspia. The SDK handles token acquisition and renewal
automatically — you only need to provide your credentials once when constructing the client.

If you do not yet have credentials, contact `contact@aspiaspace.com` or visit
[aspiaspace.com](https://aspiaspace.com) to request a trial.

## Available Services

| Attribute | Description |
|---|---|
| `sdk.customers` | Manage and retrieve customer area data |
| `sdk.vigour` | Access Vigour endpoint data |
| `sdk.alt` | Access ALT endpoint data |
| `sdk.weather` | Retrieve weather data |
| `sdk.config` | View and manage SDK configuration |

Full API reference documentation is available at [api.aspiaspace.com/v1/docs](https://api.aspiaspace.com/v1/docs/).

## Error Handling

The SDK raises descriptive exceptions to help you handle failures gracefully:

```python
from aspiaspace import AspiaSpace
from aspiaspace.exceptions import AspiaAuthError, AspiaAPIError

sdk = AspiaSpace(
    client_id=os.environ["ASPIA_CLIENT_ID"],
    client_secret=os.environ["ASPIA_CLIENT_SECRET"],
)

try:
    customers = sdk.customers.list()
except AspiaAuthError:
    print("Authentication failed — check your client ID and secret.")
except AspiaAPIError as e:
    print(f"API error: {e}")
```

## Support

- 📖 **API Reference:** [api.aspiaspace.com/v1/docs](https://api.aspiaspace.com/v1/docs/)
- 📧 **Contact:** `contact@aspiaspace.com`
- 🌐 **Website:** [aspiaspace.com](https://aspiaspace.com)