PyCoway

PyCoway is a typed asyncio client for Coway AIRMEGA devices, covering cloud authentication, purifier status, and remote control through Coway IoCare.

Features

• Async API built on aiohttp
• Typed dataclass models for purifier state
• Device control: power, fan speed, light, timers, modes, button lock, and more
• Air-quality readings: PM2.5, PM10, CO2, VOC, AQI
• Filter health monitoring: pre-filter, MAX2, and odor filter with detailed supply info
• Unified data from three API sources: IoT JSON, legacy REST, and HTML scrape
• Automatic token and session management
• Full test coverage with GitHub Actions CI
• Automated semantic version bumping, GitHub releases, and PyPI publishing

Requirements

• Python 3.14 or newer, the version the current Home Assistant release runs on
• A Coway IoCare account with at least one registered purifier

Installation

pip install pycoway

For local development:

git clone https://github.com/Antonio112009/pycoway.git
cd pycoway
pip install -e ".[dev]"

Quick Start

import asyncio

from pycoway import CowayClient


async def main() -> None:
    async with CowayClient("email@example.com", "password") as client:
        await client.login()
        data = await client.async_get_purifiers_data()

        for device_id, purifier in data.purifiers.items():
            print(f"{purifier.device_attr.name} ({device_id})")
            print(f"  Power: {'On' if purifier.is_on else 'Off'}")
            print(f"  Fan Speed: {purifier.fan_speed}")
            print(f"  PM2.5: {purifier.particulate_matter_2_5}")
            print(f"  AQI: {purifier.air_quality_index}")


asyncio.run(main())

Skipping Password Change Prompt

Coway requires users to change their password every 60 days. If the password hasn't been updated within that window, the API returns a password-change form instead of completing login, causing a PasswordExpired exception.

To skip this prompt and continue logging in without changing your password, set skip_password_change to True before calling login():

client = CowayClient("email@example.com", "password", skip_password_change=True)
await client.login()

Note: This does not disable the Coway password policy — it simply submits the "change next time" option on the password-change page so login can proceed.

Device Control

Every control method accepts the device_attr from a CowayPurifier instance:

import asyncio

from pycoway import CowayClient, LightMode


async def control_first_purifier() -> None:
    async with CowayClient("email@example.com", "password") as client:
        await client.login()
        data = await client.async_get_purifiers_data()

        purifier = next(iter(data.purifiers.values()))
        attr = purifier.device_attr

        await client.async_set_power(attr, is_on=True)
        await client.async_set_auto_mode(attr)
        await client.async_set_fan_speed(attr, speed="2")
        await client.async_set_light(attr, light_on=True)
        await client.async_set_light_mode(attr, LightMode.AQI_OFF)
        await client.async_set_timer(attr, time="120")


asyncio.run(control_first_purifier())

Available Control Methods

Data Model

async_get_purifiers_data() returns a PurifierData dataclass containing a purifiers dictionary keyed by device ID.

Each CowayPurifier includes:

Device Identity

Control State

Air Quality

Filter Health

FilterInfo

Each FilterInfo object in the filters list provides detailed supply data from the IoCare API:

For the complete schema, see src/pycoway/devices/models.py.

Data Sources

async_get_purifiers_data() combines three API sources automatically:

Exceptions

All exceptions inherit from CowayError, including network failures: aiohttp connection errors, timeouts and truncated payloads are wrapped in CowayConnectionError, so a single except CowayError covers everything the client can raise.

from pycoway import AuthError, CowayConnectionError, CowayError, PasswordExpired

Migrating from cowayaio

If you're switching from the original cowayaio package:

pip uninstall cowayaio
pip install pycoway

Update your imports:

# Before
from cowayaio import CowayClient

# After
from pycoway import CowayClient

Development

git clone https://github.com/Antonio112009/pycoway.git
cd pycoway
pip install -e ".[dev]"
pytest
ruff check .
ruff format --check .

Feature work should branch from development, and pull requests merge into development first. See CONTRIBUTING.md for the full workflow.

Release Flow

• PRs from development to main trigger the release workflow when merged
• The workflow bumps src/pycoway/__version__.py
• PRs to main must have exactly one version label: patch, minor, or major
• A git tag and GitHub release are created automatically
• The package is published to PyPI automatically

Project Structure

src/pycoway/
├── __init__.py            # Public API exports
├── __version__.py         # Version string
├── client.py              # Public CowayClient entry point
├── constants.py           # API constants, sensor codes, IAQ field mapping
├── exceptions.py          # Public exception hierarchy
├── py.typed               # PEP 561 marker
├── account/
│   ├── auth.py            # Authentication (login, token refresh)
│   └── maintenance.py     # Server maintenance checks
├── devices/
│   ├── control.py         # Purifier control commands
│   ├── data.py            # Data fetching (legacy HTML + IoT JSON API)
│   ├── models.py          # Dataclasses (CowayPurifier, FilterInfo, PurifierData)
│   └── parser.py          # HTML/JSON response parsing and normalisation
└── transport/
    └── http.py            # HTTP base client with session management

License

MIT, originally authored by RobertD502