Metadata-Version: 2.5
Name: datasetseek
Version: 0.1.1
Summary: DatasetSeek 官方 Python SDK
Requires-Python: >=3.8
Requires-Dist: requests>=2.28
Description-Content-Type: text/markdown

```markdown
# DatasetSeek Python SDK

The official Python SDK for DatasetSeek. Effortlessly download high-quality datasets with secure AK/SK authentication, auto-extraction, and precise billing feedback.

## Installation

```bash
pip install datasetseek
```

## Quick Start

Before you begin, register an account at **https://www.datasetseek.com/** and obtain your **Access Key (AK)** and **Secret Key (SK)** from your dashboard. Both credentials are required to authenticate every request.

> ⚠️ **Never hard-code your real AK/SK in source code or commit them to version control.** Use environment variables or a secrets manager instead.

### 1. Initialize the Client

For maximum security, the SDK uses an HMAC-SHA256 dynamic signature mechanism. Create a client once with your credentials and reuse it:

```python
import os
import datasetseek

# Read credentials from environment variables (recommended)
client = datasetseek.Client(
    ak=os.environ["DATASETSEEK_AK"],
    sk=os.environ["DATASETSEEK_SK"],
)
```

### 2. Download a Dataset

Simply pass the numerical Dataset ID. The SDK will automatically handle authentication, download the `.zip` file, extract the contents, and return a clean result dictionary.

```python
# Pass the dataset ID to download
result = client.download("602010")

# Inspect the structured result
if result["code"] == 200:
    print(f"✅ Success! Files saved at: {result['path']}")
    print(f"💰 Points deducted: {result['points_cost']}")
else:
    print(f"❌ Error [{result['code']}]: {result['message']}")
```

If you just want to inspect the raw response, you can print it directly — the SDK never raises tracebacks for API errors, it always returns a structured `dict`:

```python
result = client.download("602010")
print(result)
# {'code': 200, 'message': 'success', 'path': '/abs/path/to/dataset', 'points_cost': 10}
```

## Features

- 🔐 **Secure AK/SK Authentication**: Automatically generates HMAC-SHA256 signatures with timestamps to prevent replay attacks and keep your credentials safe (no plain-text transmission).
- 📦 **Auto-Extraction**: Automatically unzips the downloaded dataset and cleans up temporary files, directly returning the absolute path to the clean data folder.
- 💰 **Smart Billing Integration**: The `points_cost` field in the return value tells you exactly how many points were deducted. If you re-download within the validity period, it will be `0`.
- 🛡️ **Graceful Error Handling**: No more long, ugly Python tracebacks. The SDK always returns a structured JSON dictionary for both success and failure.

## Supported Business Scenarios & Versioning

As the SDK evolves, we will continuously expand its capabilities.

- **v0.1.0 (Current Release)**: Supports **Dataset Acquisition** (Searching and downloading datasets).
- *Future releases will include support for Model APIs, Real-time Data Streaming, and more.*

## Return Format

The `download()` method **always** returns a dictionary (`dict`) with the following structure:

| Key | Type | Description |
| :--- | :--- | :--- |
| `code` | `int` | Status code. `200` indicates success; others indicate failure. |
| `message` | `str` | Error message or "success". Clear reasons are provided on failure. |
| `path` | `str` / `None` | Absolute local path to the extracted dataset on success; `None` on failure. |
| `points_cost` | `int` | Points deducted for this download. Returns `0` if downloaded within the valid period. |

## Error Codes

- `401`: AK/SK authentication failed, signature mismatch, or request expired.
- `403`: Insufficient points, dataset offline, or permission denied (private dataset).
- `404`: Dataset ID not found.
- `500`: Server internal error or cloud storage connection failed.

## Support

If you encounter any issues or have feedback, please contact us at:
📧 **dev@payititi.com**

New users can register at **https://www.datasetseek.com/** to obtain their AK/SK and get started.

## License
This project is licensed under the MIT License.
```