Metadata-Version: 2.4
Name: poolcop
Version: 0.7.0
Summary: Asynchronous Python client for the PoolCopilot API
License: Apache-2.0
License-File: LICENSE
Keywords: poolcop,poolcopilot,api,async,client
Author: Sander Striker
Author-email: s.striker@striker.nl
Maintainer: Sander Striker
Maintainer-email: s.striker@striker.nl
Requires-Python: >=3.10,<4.0
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: aiohttp (>=3.0.0)
Requires-Dist: async-timeout (>=4.0.0)
Requires-Dist: yarl (>=1.6.0)
Project-URL: Bug Tracker, https://github.com/sstriker/python-poolcop/issues
Project-URL: Changelog, https://github.com/sstriker/python-poolcop/releases
Project-URL: Documentation, https://github.com/sstriker/python-poolcop
Project-URL: Homepage, https://github.com/sstriker/python-poolcop
Project-URL: Repository, https://github.com/sstriker/python-poolcop
Description-Content-Type: text/markdown

Asynchronous Python client for the [PoolCopilot API][poolcopilot-api].

## About

A python package to interact with a [PoolCop][poolcop] device through the PoolCopilot API.

## Installation

```bash
pip install poolcop
```

## Usage

```python
import asyncio
import json
from poolcop import PoolCopilot

API_KEY="xxxxxxxxxxxxxxxxxxxxxxx"

async def main() -> None:
    """Show example on fetching the status from PoolCop."""
    async with PoolCopilot(api_key=API_KEY) as client:
        status = await client.status()
    print(json.dumps(status, indent=2))

if __name__ == "__main__":
    asyncio.run(main())
```

## API Features

The PoolCopilot API provides access to various features of your PoolCop device:

### Status Information
- Water and air temperature
- pH and ORP (Oxidation-Reduction Potential) values
- Water level status
- Valve position
- Pump status and speed
- Equipment status (auxiliaries, etc.)
- Filter settings and timers
- Forced filtration status and remaining time

### Commands
- Toggle pump on/off
- Set pump speed (for multi-speed pumps)
- Toggle auxiliary outputs
- Set valve position
- Clear alarms
- Set forced filtration mode (24h, 48h, or 72h)

### History
- Alarm history (with pagination)
- Command history (with pagination)

### Quota Management
- `token_limit` — remaining API calls in the current window
- `token_expire` — epoch timestamp when the current quota window resets

### Options
- `lang` parameter — sets the `X-PoolCopilot-Lang` header for localised responses

## Development

This project uses [Poetry](https://python-poetry.org/) for dependency management.

```bash
git clone https://github.com/sstriker/python-poolcop.git
cd python-poolcop
poetry install --with dev
poetry run pytest
```

### Releasing to PyPI

The repository uses [trusted publishing](https://docs.pypi.org/trusted-publishers/) via GitHub Actions. To release:

1. Bump the version in `pyproject.toml`
2. Merge to `main`
3. Create a GitHub Release (this creates a tag and triggers the publish workflow)
4. The workflow runs tests, builds with Poetry, and publishes to PyPI automatically

[poolcop]: https://www.poolcop.com/
[poolcopilot-api]: https://poolcopilot.com/api/docs/

