Metadata-Version: 2.4
Name: wildberries-python-sdk
Version: 0.1.11
Summary: Contract-oriented Python client for Wildberries API
Author: Aliaksandr Ivanou <alexivanou@gmail.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: pydocstyle>=6.3.0; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=8.0.0; extra == "docs"
Dynamic: license-file

# Wildberries Python SDK

Professional, contract-oriented Python client for Wildberries API.

[![PyPI version](https://badge.fury.io/py/wildberries-python-sdk.svg)](https://badge.fury.io/py/wildberries-python-sdk)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

## Features

- **Async/Sync support** - Works with both async and synchronous code using httpx
- **Type-safe** - Full Pydantic V2 models with validation
- **Rate limiting** - Intelligent token-based rate limiting with category isolation
- **Error handling** - Typed exception hierarchy for all API errors
- **Registry-based** - YAML configuration for easy endpoint extension
- **Sandbox/Production** - Support for both WB environments
- **Pagination** - Built-in async/sync page iterators

## Installation

```bash
pip install wildberries-python-sdk
```

Or with development dependencies:

```bash
pip install wildberries-python-sdk[dev]
```

## Quick Start

### Async Client

```python
import asyncio
from wildberries_python_sdk import BaseClient, Registry, RateLimiter, GeneralService

async def main():
    registry = Registry("config/endpoints")
    ratelimiter = RateLimiter()

    client = BaseClient(
        token="your-api-token",
        registry=registry,
        ratelimiter=ratelimiter
    )

    service = GeneralService(client)
    info = await service.get_seller_info()
    print(f"Seller: {info.name}")

    await client.close()

asyncio.run(main())
```

### Sync Client

```python
from wildberries_python_sdk import SyncClient, Registry, RateLimiter, GeneralService

with SyncClient("token", registry, ratelimiter) as client:
    service = GeneralService(client)
    info = service.get_seller_info()
    print(info.name)
```

## Services

| Service | Description |
|---------|-------------|
| `GeneralService` | Connection check, news, seller info, user management |
| `ProductsService` | Categories, product cards, tags |
| `WarehouseService` | Seller warehouses management |
| `InventoryService` | Stock management |
| `PricesService` | Prices and discounts |
| `MediaService` | Media files upload |

## Products API Example

```python
from wildberries_python_sdk import ProductsService

service = ProductsService(client)

# Get categories
categories = await service.get_parent_categories()
for cat in categories.data:
    print(f"{cat.id}: {cat.name}")

# Get product cards
cards = await service.get_cards_list(
    settings={"cursor": {"limit": 100}}
)
```

## Error Handling

```python
from wildberries_python_sdk import WBAPIError, TooManyRequestsError

try:
    result = await service.get_data()
except TooManyRequestsError as e:
    print(f"Rate limited! {e.detail}")
except WBAPIError as e:
    print(f"API Error {e.status}: {e.detail}")
```

## Configuration

```python
from wildberries_python_sdk import Config, DomainType, set_default_locale

# Set global configuration
set_default_locale("en")

# Or use Config class
config = Config(locale="en", domain=DomainType.SANDBOX)
```

## Development

```bash
# Clone and install
git clone https://github.com/wildberries/wildberries-python-sdk
cd wildberries-python-sdk
pip install -e ".[dev]"

# Run tests
pytest tests/

# Type checking
mypy src/

# Linting
ruff check src/
```

## License

MIT License - see LICENSE file for details.
