Metadata-Version: 2.4
Name: phonkersbase
Version: 0.2.0
Summary: A Python client for the PhonkersBase API
Home-page: https://github.com/brokenbyteofcode/phonkersbase-py
Author: brokenbyteofcode
Author-email: BrokenByteOfCode <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/BrokenByteOfCode/phonkersbase-py
Project-URL: Repository, https://github.com/BrokenByteOfCode/phonkersbase-py
Project-URL: Documentation, https://github.com/BrokenByteOfCode/phonkersbase-py#readme
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: cachetools>=4.2.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: pytest-cov>=2.10.0; extra == "dev"
Requires-Dist: black>=20.8b1; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: mypy>=0.800; extra == "dev"
Requires-Dist: twine>=3.4.1; extra == "dev"
Requires-Dist: build>=0.7.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# PhonkersBase Python Client

A Python client library for interacting with the PhonkersBase API (phonkersbase.com).

## Features

- Search and retrieve artists from PhonkersBase
- Filter artists by label and country
- Built-in caching support
- Pagination helpers
- Type hints support
- Error handling

## Installation

```bash
pip install phonkersbase
```

## Quick Start

```python
from phonkersbase import phonkerbase, ArtistLabel

# Basic usage
artists = phonkerbase.search_artists("phonk")

# Filter by label
approved_artists = phonkerbase.get_artists_by_label(ArtistLabel.APPROVED)

# Filter by country
uk_artists = phonkerbase.get_artists_by_country("uk")

# Paginate through all results
all_artists = phonkerbase.paginate_all_artists(label=ArtistLabel.APPROVED)
```

## API Reference

### PhonkersBaseAPI

The main client class for interacting with the PhonkersBase API.

```python
client = PhonkersBaseAPI(
    timeout=10,  # Request timeout in seconds
    cache_ttl=3600,  # Cache TTL in seconds
    cache_size=2048  # Maximum number of cached items
)
```

### Methods

- `get_artists(search=None, label=None, country=None, limit=25, offset=0, locale='uk')`
- `get_countries()`
- `search_artists(query, **kwargs)`
- `get_artists_by_label(label, **kwargs)`
- `get_artists_by_country(country, **kwargs)`
- `paginate_all_artists(**kwargs)`
- `clear_cache()`
- `get_cache_info()`

### Artist Labels

Available artist labels (via `ArtistLabel` enum):
- BASE
- APPROVED
- UNKNOWN
- PRIDE
- BLOCKED
- WARNING

## Error Handling

The library uses the `PhonkersBaseException` class for error handling:

```python
try:
    artists = phonkerbase.search_artists("archez")
except PhonkersBaseException as e:
    print(f"API Error: {e}")
```

## License

MIT License
