semvec/pypi-packages huggingface dataset:
openwav 0.1.1
Python wrapper for the OpenWAV API
License: MIT
Requires Python: >=3.8

# OpenWAV Python Library

[![PyPI version](https://img.shields.io/pypi/v/openwav.svg)](https://pypi.org/project/openwav/)
[![Python versions](https://img.shields.io/pypi/pyversions/openwav.svg)](https://pypi.org/project/openwav/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

A modern, asynchronous Python wrapper for the **OpenWAV API**. Lightweight, type-hinted, and easy to use.

---

## 🌟 Features

- **Async First**: Built on top of `httpx` for high-performance asynchronous operations.
- **Type Safe**: Fully type-hinted and uses `Pydantic` models for data validation.
- **Complete Coverage**: Supports Wallet transfers, Cheques, Multi-cheques, and Admin functions.
- **Clean Exceptions**: Custom exception hierarchy for precise error handling.

## 🚀 Installation

```bash
pip install openwav
```

## 🛠️ Quick Start

```python
import asyncio
from openwav import OpenWAVClient

async def main():
    async with OpenWAVClient(api_key="your_api_key") as client:
        # Get your profile
        me = await client.get_me()
        print(f"Hello, {me.full_name}!")
        
        # Transfer coins
        transfer = await client.transfer(
            receiver="OW_USER123",
            coin="WAV",
            amount=10.5,
            comment="Payment for services"
        )
        print(f"Transfer successful: {transfer.unique_id}")

asyncio.run(main())
```

## 📚 Best Practices

### 1. Context Managers
Always use the `async with` statement to ensure the underlying connection pool is properly closed.

### 2. Error Handling
Catch `OpenWAVError` to handle API-specific issues gracefully.

```python
from openwav import OpenWAVError, AuthenticationError

try:
    me = await client.get_me()
except AuthenticationError:
    print("Check your API key!")
except OpenWAVError as e:
    print(f"API Error: {e.message}")
```

### 3. Environment Variables
Never hardcode your API key. Use environment variables or a configuration manager.

```python
import os
api_key = os.getenv("OPEN_WAV_API_KEY")
```

## 📖 API Reference

### Wallet
- `client.get_me()`: Get your profile and balances.
- `client.transfer(...)`: Send coins to another user.
- `client.list_transfers(...)`: History of transfers.

### Cheques
- `client.create_cheque(...)`: Create a single-use cheque.
- `client.claim_cheque(cheque_id, password)`: Claim a cheque.
- `client.list_cheques(...)`: View your created cheques.

### Multi-Cheques
- `client.create_multicheque(...)`: Create a multi-use cheque.
- `client.claim_multicheque(...)`: Claim a multi-cheque.

## 🧪 Development

Install dependencies for development:

```bash
pip install -e ".[dev]"
```

Run tests (coming soon):
```bash
pytest
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.