# libdyson-rest
[](https://badge.fury.io/py/libdyson-rest)
[](https://pypi.org/project/libdyson-rest/)
[](https://github.com/cmgrayb/libdyson-rest/blob/main/LICENSE)
A Python library for interacting with Dyson devices through their official REST API.
## Features
- **Official API Compliance**: Implements the complete Dyson App API as documented in their OpenAPI specification
- **Two-Step Authentication**: Secure login process with OTP codes
- **Complete Device Management**: List devices, get device details, and retrieve IoT credentials
- **MQTT Connection Support**: Extract both cloud (AWS IoT) and local MQTT connection parameters
- **Password Decryption**: Decrypt local MQTT broker credentials for direct device communication
- **Token-Based Authentication**: Store and reuse authentication tokens for repeated API calls
- **Type-Safe Models**: Comprehensive data models with proper type hints
- **Error Handling**: Detailed exception hierarchy for robust error handling
- **Context Manager Support**: Automatic resource cleanup
## Installation
Install from PyPI:
```bash
pip install libdyson-rest
```
Or install from source:
```bash
git clone https://github.com/cmgrayb/libdyson-rest.git
cd libdyson-rest
pip install -e .
```
## Quick Start
```python
from libdyson_rest import DysonClient
# Initialize the client
client = DysonClient(
email="your@email.com",
password="your_password",
country="US", # ISO 3166-1 alpha-2 country code
culture="en-US" # IETF language code
)
# Two-step authentication process
try:
# Step 1: Begin login process
challenge = client.begin_login()
print(f"Challenge ID: {challenge.challenge_id}")
print("Check your email for an OTP code")
# Step 2: Complete login with OTP code
otp_code = input("Enter OTP code: ")
login_info = client.complete_login(str(challenge.challenge_id), otp_code)
print(f"Logged in! Account: {login_info.account}")
# Get devices
devices = client.get_devices()
for device in devices:
print(f"Device: {device.name} ({device.serial_number})")
print(f" Type: {device.type}")
print(f" Category: {device.category.value}")
# Get IoT credentials for connected devices
if device.connection_category.value != "nonConnected":
iot_data = client.get_iot_credentials(device.serial_number)
print(f" IoT Endpoint: {iot_data.endpoint}")
finally:
client.close()
```
## Authentication Flow
The Dyson API uses a secure two-step authentication process:
### 1. API Provisioning (Automatic)
```python
version = client.provision() # Called automatically
```
### 2. User Status Check (Optional)
```python
user_status = client.get_user_status()
print(f"Account status: {user_status.account_status.value}")
```
### 3. Begin Login Process
```python
challenge = client.begin_login()
# This triggers an OTP code to be sent to your email
```
### 4. Complete Login with OTP
```python
login_info = client.complete_login(
challenge_id=str(challenge.challenge_id),
otp_code="123456" # From your email
)
```
### 5. Authenticated API Calls
```python
devices = client.get_devices()
iot_data = client.get_iot_credentials("device_serial")
```
## API Reference
### DysonClient
#### Constructor
```python
DysonClient(
email: Optional[str] = None,
password: Optional[str] = None,
country: str = "US",
culture: str = "en-US",
timeout: int = 30,
user_agent: str = "android client"
)
```
#### Core Methods
##### Authentication
- `provision() -> str`: Required initial API call
- `get_user_status(email=None) -> UserStatus`: Check account status
- `begin_login(email=None) -> LoginChallenge`: Start login process
- `complete_login(challenge_id, otp_code, email=None, password=None) -> LoginInformation`: Complete authentication
- `authenticate(otp_code=None) -> bool`: Convenience method for full auth flow
##### Device Management
- `get_devices() -> List[Device]`: List all account devices
- `get_iot_credentials(serial_number) -> IoTData`: Get AWS IoT connection info
##### Session Management
- `close() -> None`: Close session and clear state
- `__enter__()` and `__exit__()`: Context manager support
### Data Models
#### Device
```python
@dataclass
class Device:
category: DeviceCategory # ec, flrc, hc, light, robot, wearable
connection_category: ConnectionCategory # lecAndWifi, lecOnly, nonConnected, wifiOnly
model: str
name: str
serial_number: str
type: str
variant: Optional[str] = None
connected_configuration: Optional[ConnectedConfiguration] = None
```
#### DeviceCategory (Enum)
- `ENVIRONMENT_CLEANER = "ec"` - Air filters, purifiers
- `FLOOR_CLEANER = "flrc"` - Vacuum cleaners
- `HAIR_CARE = "hc"` - Hair dryers, stylers
- `LIGHT = "light"` - Lighting products
- `ROBOT = "robot"` - Robot vacuums
- `WEARABLE = "wearable"` - Wearable devices
#### ConnectionCategory (Enum)
- `LEC_AND_WIFI = "lecAndWifi"` - Bluetooth and Wi-Fi
- `LEC_ONLY = "lecOnly"` - Bluetooth only
- `NON_CONNECTED = "nonConnected"` - No connectivity
- `WIFI_ONLY = "wifiOnly"` - Wi-Fi only
#### LoginInformation
```python
@dataclass
class LoginInformation:
account: UUID # Account ID
token: str # Bearer token for API calls
token_type: TokenType # Always "Bearer"
```
#### IoTData
```python
@dataclass
class IoTData:
endpoint: str # AWS IoT endpoint
iot_credentials: IoTCredentials # Connection credentials
```
### Exception Hierarchy
```
DysonAPIError (base)
├── DysonConnectionError # Network/connection issues
├── DysonAuthError # Authentication failures
├── DysonDeviceError # Device operation failures
└── DysonValidationError # Input validation errors
```
## Advanced Usage
### Using Context Manager
```python
with DysonClient(email="your@email.com", password="password") as client:
# Authentication
challenge = client.begin_login()
otp = input("Enter OTP: ")
client.complete_login(str(challenge.challenge_id), otp)
# API calls
devices = client.get_devices()
# Client automatically closed on exit
```
### Error Handling
```python
from libdyson_rest import DysonAuthError, DysonConnectionError, DysonAPIError
try:
client = DysonClient(email="user@example.com", password="pass")
challenge = client.begin_login()
except DysonAuthError as e:
print(f"Authentication failed: {e}")
except DysonConnectionError as e:
print(f"Network error: {e}")
except DysonAPIError as e:
print(f"API error: {e}")
```
### Manual Authentication Steps
```python
client = DysonClient(email="user@example.com", password="password")
# Step 1: Provision (required)
version = client.provision()
print(f"API version: {version}")
# Step 2: Check user status
user_status = client.get_user_status()
print(f"Account active: {user_status.account_status.value == 'ACTIVE'}")
# Step 3: Begin login
challenge = client.begin_login()
print("Check email for OTP")
# Step 4: Complete login
otp = input("OTP: ")
login_info = client.complete_login(str(challenge.challenge_id), otp)
print(f"Bearer token: {login_info.token[:10]}...")
# Step 5: Use authenticated endpoints
devices = client.get_devices()
```
## Configuration
### Environment Variables
- `DYSON_EMAIL`: Default email address
- `DYSON_PASSWORD`: Default password
- `DYSON_COUNTRY`: Default country code (default: "US")
- `DYSON_CULTURE`: Default culture/locale (default: "en-US")
- `DYSON_TIMEOUT`: Request timeout in seconds (default: "30")
### Country and Culture Codes
- **Country**: 2-letter uppercase ISO 3166-1 alpha-2 codes (e.g., "US", "GB", "DE")
- **Culture**: 5-character IETF language codes (e.g., "en-US", "en-GB", "de-DE")
## API Compliance
This library implements the complete Dyson App API as documented in their OpenAPI specification:
- Authentication endpoints (`/v3/userregistration/email/*`)
- Device management (`/v3/manifest`)
- IoT credentials (`/v2/authorize/iot-credentials`)
- Provisioning (`/v1/provisioningservice/application/Android/version`)
## Requirements
- Python 3.8+
- `requests` - HTTP client library
- `dataclasses` - Data model support (Python 3.8+)
## Contributing
Contributions are welcome! Please ensure all changes maintain compatibility with the official Dyson OpenAPI specification.
## Versioning & Releases
This project follows **PEP 440** versioning (not semantic versioning). Here's how versions are distributed:
### Version Patterns
| Pattern | Example | Distribution | Purpose |
|---------|---------|--------------|---------|
| **Alpha** | `0.3.0a1`, `0.3.0alpha1` | TestPyPI | Internal testing only |
| **Dev** | `0.3.0.dev1` | TestPyPI | Development builds |
| **Beta** | `0.3.0b1`, `0.3.0beta1` | **PyPI** | Public beta testing |
| **RC** | `0.3.0rc1` | **PyPI** | Release candidates |
| **Stable** | `0.3.0` | **PyPI** | Production releases |
| **Patch** | `0.3.0.post1` | **PyPI** | Post-release patches |
### Installation
```bash
# Install stable release
pip install libdyson-rest
# Install latest beta (includes rc, beta versions)
pip install --pre libdyson-rest
# Install specific version
pip install libdyson-rest==0.3.0b1
# Install from TestPyPI (alpha/dev versions)
pip install -i https://test.pypi.org/simple/ libdyson-rest==0.3.0a1
```
### For Beta Testers
Want to help test new features? Install pre-release versions:
```bash
pip install --pre libdyson-rest
```
This will install the latest beta or release candidate, giving you access to new features before stable release.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Disclaimer
This is an unofficial library. Dyson is a trademark of Dyson Ltd. This library is not affiliated with, endorsed by, or sponsored by Dyson Ltd.
## OpenAPI Specification
This library is based on the community-documented Dyson App API OpenAPI specification. The specification can be found at:
https://raw.githubusercontent.com/libdyson-wg/appapi/refs/heads/main/openapi.yaml
This project is created to further the efforts of others in the community in interacting with the
Dyson devices they have purchased to better integrate them into their smart homes.
At this time, this library is PURELY EXPERIMENTAL and should not be used without carefully examining
the code before doing so. **USE AT YOUR OWN RISK**
## Features
- Clean, intuitive API for Dyson device interaction
- Full type hints support
- Comprehensive error handling
- Async/sync support
- Built-in authentication handling
- Extensive test coverage
## Installation
### From Source (Development)
```bash
# Clone the repository
git clone https://github.com/cmgrayb/libdyson-rest.git
cd libdyson-rest
# Create and activate virtual environment
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate
# Install development dependencies
pip install -r requirements-dev.txt
```
## Quick Start
```python
from libdyson_rest import DysonClient
# Initialize the client
client = DysonClient(
email="your_email@example.com",
password="your_password",
country="US"
)
# Authenticate with Dyson API
client.authenticate()
# Get your devices
devices = client.get_devices()
for device in devices:
print(f"Device: {device['name']} ({device['serial']})")
# Always close the client when done
client.close()
# Or use as context manager
with DysonClient(email="email@example.com", password="password") as client:
client.authenticate()
devices = client.get_devices()
# Client is automatically closed
```
## Development
This project uses several tools to maintain code quality:
- **Black**: Code formatting (120 character line length)
- **Flake8**: Linting and style checking
- **isort**: Import sorting
- **MyPy**: Type checking
- **Pytest**: Testing framework
- **Pre-commit**: Git hooks
### Setting up Development Environment
1. **Create virtual environment and install dependencies:**
```bash
python -m venv .venv
.venv\Scripts\activate # Windows
pip install -r requirements-dev.txt
```
2. **Install pre-commit hooks:**
```bash
pre-commit install
```
### VSCode Tasks
This project includes VSCode tasks for common development operations:
- **Setup Dev Environment**: Create venv and install dependencies
- **Format Code**: Run Black formatter
- **Lint Code**: Run Flake8 linter
- **Sort Imports**: Run isort
- **Type Check**: Run MyPy type checker
- **Run Tests**: Execute pytest with coverage
- **Check All**: Run all quality checks in sequence
Access these via `Ctrl+Shift+P` → "Tasks: Run Task"
### Code Quality Commands
```bash
# Format code
black .
# Sort imports
isort .
# Lint code
flake8 .
# Type check
mypy src/libdyson_rest
# Run tests
pytest
# Run all checks
black . && isort . && flake8 . && mypy src/libdyson_rest && pytest
```
### Testing
Run tests with coverage:
```bash
# All tests
pytest
# Unit tests only
pytest tests/unit/
# Integration tests only
pytest tests/integration/
# With coverage report
pytest --cov=src/libdyson_rest --cov-report=html
```
## Project Structure
```
libdyson-rest/
├── src/
│ └── libdyson_rest/ # Main library code
│ ├── __init__.py
│ ├── client.py # Main API client
│ ├── exceptions.py # Custom exceptions
│ ├── models/ # Data models
│ └── utils/ # Utility functions
├── tests/
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
├── .vscode/
│ └── tasks.json # VSCode tasks
├── requirements.txt # Production dependencies
├── requirements-dev.txt # Development dependencies
├── pyproject.toml # Project configuration
├── .flake8 # Flake8 configuration
├── .pre-commit-config.yaml # Pre-commit hooks
└── README.md
```
## Configuration Files
- **pyproject.toml**: Main project configuration (Black, isort, pytest, mypy)
- **.flake8**: Flake8 linting configuration
- **.pre-commit-config.yaml**: Git pre-commit hooks
- **requirements.txt**: Production dependencies
- **requirements-dev.txt**: Development dependencies
## Publishing to PyPI
This package is automatically published to PyPI using GitHub Actions. For detailed publishing instructions, see [PUBLISHING.md](PUBLISHING.md).
### Quick Publishing
- **Test Release**: GitHub Actions → Run workflow → TestPyPI
- **Production Release**: Create a GitHub release with version tag (e.g., `v0.2.0`)
- **Local Build**: `python .github/scripts/publish_to_pypi.py --check`
The package is available on PyPI as `libdyson-rest`.
## Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes following the coding standards
4. Run all quality checks: ensure Black, Flake8, isort, MyPy, and tests pass
5. Commit your changes: `git commit -am 'Add feature'`
6. Push to the branch: `git push origin feature-name`
7. Create a Pull Request
All PRs must pass the full test suite and code quality checks.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Security
- No hardcoded credentials or sensitive data
- Use environment variables for configuration
- All user inputs are validated
- API responses are sanitized
## Roadmap
- [ ] Complete API endpoint coverage
- [ ] Asynchronous client support
- [ ] WebSocket real-time updates
- [ ] Command-line interface
- [ ] Docker container support
Raw data
{
"_id": null,
"home_page": null,
"name": "libdyson-rest",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Chris Gray <cmgrayb@outlook.com>",
"keywords": "dyson, air-purifier, fan, iot, rest-api, mqtt, home-automation",
"author": null,
"author_email": "Chris Gray <cmgrayb@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/66/f9/8326d44d45341e5712cf08eb007921bf4c1a5617e9268a3aad7453a758f0/libdyson_rest-0.4.0.tar.gz",
"platform": null,
"description": "# libdyson-rest\n\n[](https://badge.fury.io/py/libdyson-rest)\n[](https://pypi.org/project/libdyson-rest/)\n[](https://github.com/cmgrayb/libdyson-rest/blob/main/LICENSE)\n\nA Python library for interacting with Dyson devices through their official REST API.\n\n## Features\n\n- **Official API Compliance**: Implements the complete Dyson App API as documented in their OpenAPI specification\n- **Two-Step Authentication**: Secure login process with OTP codes\n- **Complete Device Management**: List devices, get device details, and retrieve IoT credentials\n- **MQTT Connection Support**: Extract both cloud (AWS IoT) and local MQTT connection parameters\n- **Password Decryption**: Decrypt local MQTT broker credentials for direct device communication\n- **Token-Based Authentication**: Store and reuse authentication tokens for repeated API calls\n- **Type-Safe Models**: Comprehensive data models with proper type hints\n- **Error Handling**: Detailed exception hierarchy for robust error handling\n- **Context Manager Support**: Automatic resource cleanup\n\n## Installation\n\nInstall from PyPI:\n\n```bash\npip install libdyson-rest\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/cmgrayb/libdyson-rest.git\ncd libdyson-rest\npip install -e .\n```\n\n## Quick Start\n\n```python\nfrom libdyson_rest import DysonClient\n\n# Initialize the client\nclient = DysonClient(\n email=\"your@email.com\",\n password=\"your_password\",\n country=\"US\", # ISO 3166-1 alpha-2 country code\n culture=\"en-US\" # IETF language code\n)\n\n# Two-step authentication process\ntry:\n # Step 1: Begin login process\n challenge = client.begin_login()\n print(f\"Challenge ID: {challenge.challenge_id}\")\n print(\"Check your email for an OTP code\")\n\n # Step 2: Complete login with OTP code\n otp_code = input(\"Enter OTP code: \")\n login_info = client.complete_login(str(challenge.challenge_id), otp_code)\n print(f\"Logged in! Account: {login_info.account}\")\n\n # Get devices\n devices = client.get_devices()\n for device in devices:\n print(f\"Device: {device.name} ({device.serial_number})\")\n print(f\" Type: {device.type}\")\n print(f\" Category: {device.category.value}\")\n\n # Get IoT credentials for connected devices\n if device.connection_category.value != \"nonConnected\":\n iot_data = client.get_iot_credentials(device.serial_number)\n print(f\" IoT Endpoint: {iot_data.endpoint}\")\n\nfinally:\n client.close()\n```\n\n## Authentication Flow\n\nThe Dyson API uses a secure two-step authentication process:\n\n### 1. API Provisioning (Automatic)\n```python\nversion = client.provision() # Called automatically\n```\n\n### 2. User Status Check (Optional)\n```python\nuser_status = client.get_user_status()\nprint(f\"Account status: {user_status.account_status.value}\")\n```\n\n### 3. Begin Login Process\n```python\nchallenge = client.begin_login()\n# This triggers an OTP code to be sent to your email\n```\n\n### 4. Complete Login with OTP\n```python\nlogin_info = client.complete_login(\n challenge_id=str(challenge.challenge_id),\n otp_code=\"123456\" # From your email\n)\n```\n\n### 5. Authenticated API Calls\n```python\ndevices = client.get_devices()\niot_data = client.get_iot_credentials(\"device_serial\")\n```\n\n## API Reference\n\n### DysonClient\n\n#### Constructor\n```python\nDysonClient(\n email: Optional[str] = None,\n password: Optional[str] = None,\n country: str = \"US\",\n culture: str = \"en-US\",\n timeout: int = 30,\n user_agent: str = \"android client\"\n)\n```\n\n#### Core Methods\n\n##### Authentication\n- `provision() -> str`: Required initial API call\n- `get_user_status(email=None) -> UserStatus`: Check account status\n- `begin_login(email=None) -> LoginChallenge`: Start login process\n- `complete_login(challenge_id, otp_code, email=None, password=None) -> LoginInformation`: Complete authentication\n- `authenticate(otp_code=None) -> bool`: Convenience method for full auth flow\n\n##### Device Management\n- `get_devices() -> List[Device]`: List all account devices\n- `get_iot_credentials(serial_number) -> IoTData`: Get AWS IoT connection info\n\n##### Session Management\n- `close() -> None`: Close session and clear state\n- `__enter__()` and `__exit__()`: Context manager support\n\n### Data Models\n\n#### Device\n```python\n@dataclass\nclass Device:\n category: DeviceCategory # ec, flrc, hc, light, robot, wearable\n connection_category: ConnectionCategory # lecAndWifi, lecOnly, nonConnected, wifiOnly\n model: str\n name: str\n serial_number: str\n type: str\n variant: Optional[str] = None\n connected_configuration: Optional[ConnectedConfiguration] = None\n```\n\n#### DeviceCategory (Enum)\n- `ENVIRONMENT_CLEANER = \"ec\"` - Air filters, purifiers\n- `FLOOR_CLEANER = \"flrc\"` - Vacuum cleaners\n- `HAIR_CARE = \"hc\"` - Hair dryers, stylers\n- `LIGHT = \"light\"` - Lighting products\n- `ROBOT = \"robot\"` - Robot vacuums\n- `WEARABLE = \"wearable\"` - Wearable devices\n\n#### ConnectionCategory (Enum)\n- `LEC_AND_WIFI = \"lecAndWifi\"` - Bluetooth and Wi-Fi\n- `LEC_ONLY = \"lecOnly\"` - Bluetooth only\n- `NON_CONNECTED = \"nonConnected\"` - No connectivity\n- `WIFI_ONLY = \"wifiOnly\"` - Wi-Fi only\n\n#### LoginInformation\n```python\n@dataclass\nclass LoginInformation:\n account: UUID # Account ID\n token: str # Bearer token for API calls\n token_type: TokenType # Always \"Bearer\"\n```\n\n#### IoTData\n```python\n@dataclass\nclass IoTData:\n endpoint: str # AWS IoT endpoint\n iot_credentials: IoTCredentials # Connection credentials\n```\n\n### Exception Hierarchy\n\n```\nDysonAPIError (base)\n\u251c\u2500\u2500 DysonConnectionError # Network/connection issues\n\u251c\u2500\u2500 DysonAuthError # Authentication failures\n\u251c\u2500\u2500 DysonDeviceError # Device operation failures\n\u2514\u2500\u2500 DysonValidationError # Input validation errors\n```\n\n## Advanced Usage\n\n### Using Context Manager\n```python\nwith DysonClient(email=\"your@email.com\", password=\"password\") as client:\n # Authentication\n challenge = client.begin_login()\n otp = input(\"Enter OTP: \")\n client.complete_login(str(challenge.challenge_id), otp)\n\n # API calls\n devices = client.get_devices()\n # Client automatically closed on exit\n```\n\n### Error Handling\n```python\nfrom libdyson_rest import DysonAuthError, DysonConnectionError, DysonAPIError\n\ntry:\n client = DysonClient(email=\"user@example.com\", password=\"pass\")\n challenge = client.begin_login()\n\nexcept DysonAuthError as e:\n print(f\"Authentication failed: {e}\")\nexcept DysonConnectionError as e:\n print(f\"Network error: {e}\")\nexcept DysonAPIError as e:\n print(f\"API error: {e}\")\n```\n\n### Manual Authentication Steps\n```python\nclient = DysonClient(email=\"user@example.com\", password=\"password\")\n\n# Step 1: Provision (required)\nversion = client.provision()\nprint(f\"API version: {version}\")\n\n# Step 2: Check user status\nuser_status = client.get_user_status()\nprint(f\"Account active: {user_status.account_status.value == 'ACTIVE'}\")\n\n# Step 3: Begin login\nchallenge = client.begin_login()\nprint(\"Check email for OTP\")\n\n# Step 4: Complete login\notp = input(\"OTP: \")\nlogin_info = client.complete_login(str(challenge.challenge_id), otp)\nprint(f\"Bearer token: {login_info.token[:10]}...\")\n\n# Step 5: Use authenticated endpoints\ndevices = client.get_devices()\n```\n\n## Configuration\n\n### Environment Variables\n- `DYSON_EMAIL`: Default email address\n- `DYSON_PASSWORD`: Default password\n- `DYSON_COUNTRY`: Default country code (default: \"US\")\n- `DYSON_CULTURE`: Default culture/locale (default: \"en-US\")\n- `DYSON_TIMEOUT`: Request timeout in seconds (default: \"30\")\n\n### Country and Culture Codes\n- **Country**: 2-letter uppercase ISO 3166-1 alpha-2 codes (e.g., \"US\", \"GB\", \"DE\")\n- **Culture**: 5-character IETF language codes (e.g., \"en-US\", \"en-GB\", \"de-DE\")\n\n## API Compliance\n\nThis library implements the complete Dyson App API as documented in their OpenAPI specification:\n- Authentication endpoints (`/v3/userregistration/email/*`)\n- Device management (`/v3/manifest`)\n- IoT credentials (`/v2/authorize/iot-credentials`)\n- Provisioning (`/v1/provisioningservice/application/Android/version`)\n\n## Requirements\n\n- Python 3.8+\n- `requests` - HTTP client library\n- `dataclasses` - Data model support (Python 3.8+)\n\n## Contributing\n\nContributions are welcome! Please ensure all changes maintain compatibility with the official Dyson OpenAPI specification.\n\n## Versioning & Releases\n\nThis project follows **PEP 440** versioning (not semantic versioning). Here's how versions are distributed:\n\n### Version Patterns\n\n| Pattern | Example | Distribution | Purpose |\n|---------|---------|--------------|---------|\n| **Alpha** | `0.3.0a1`, `0.3.0alpha1` | TestPyPI | Internal testing only |\n| **Dev** | `0.3.0.dev1` | TestPyPI | Development builds |\n| **Beta** | `0.3.0b1`, `0.3.0beta1` | **PyPI** | Public beta testing |\n| **RC** | `0.3.0rc1` | **PyPI** | Release candidates |\n| **Stable** | `0.3.0` | **PyPI** | Production releases |\n| **Patch** | `0.3.0.post1` | **PyPI** | Post-release patches |\n\n### Installation\n\n```bash\n# Install stable release\npip install libdyson-rest\n\n# Install latest beta (includes rc, beta versions)\npip install --pre libdyson-rest\n\n# Install specific version\npip install libdyson-rest==0.3.0b1\n\n# Install from TestPyPI (alpha/dev versions)\npip install -i https://test.pypi.org/simple/ libdyson-rest==0.3.0a1\n```\n\n### For Beta Testers\n\nWant to help test new features? Install pre-release versions:\n\n```bash\npip install --pre libdyson-rest\n```\n\nThis will install the latest beta or release candidate, giving you access to new features before stable release.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Disclaimer\n\nThis is an unofficial library. Dyson is a trademark of Dyson Ltd. This library is not affiliated with, endorsed by, or sponsored by Dyson Ltd.\n\n## OpenAPI Specification\n\nThis library is based on the community-documented Dyson App API OpenAPI specification. The specification can be found at:\nhttps://raw.githubusercontent.com/libdyson-wg/appapi/refs/heads/main/openapi.yaml\n\nThis project is created to further the efforts of others in the community in interacting with the\nDyson devices they have purchased to better integrate them into their smart homes.\n\nAt this time, this library is PURELY EXPERIMENTAL and should not be used without carefully examining\nthe code before doing so. **USE AT YOUR OWN RISK**\n\n## Features\n\n- Clean, intuitive API for Dyson device interaction\n- Full type hints support\n- Comprehensive error handling\n- Async/sync support\n- Built-in authentication handling\n- Extensive test coverage\n\n## Installation\n\n### From Source (Development)\n\n```bash\n# Clone the repository\ngit clone https://github.com/cmgrayb/libdyson-rest.git\ncd libdyson-rest\n\n# Create and activate virtual environment\npython -m venv .venv\n\n# Windows\n.venv\\Scripts\\activate\n\n# Linux/Mac\nsource .venv/bin/activate\n\n# Install development dependencies\npip install -r requirements-dev.txt\n```\n\n## Quick Start\n\n```python\nfrom libdyson_rest import DysonClient\n\n# Initialize the client\nclient = DysonClient(\n email=\"your_email@example.com\",\n password=\"your_password\",\n country=\"US\"\n)\n\n# Authenticate with Dyson API\nclient.authenticate()\n\n# Get your devices\ndevices = client.get_devices()\nfor device in devices:\n print(f\"Device: {device['name']} ({device['serial']})\")\n\n# Always close the client when done\nclient.close()\n\n# Or use as context manager\nwith DysonClient(email=\"email@example.com\", password=\"password\") as client:\n client.authenticate()\n devices = client.get_devices()\n # Client is automatically closed\n```\n\n## Development\n\nThis project uses several tools to maintain code quality:\n\n- **Black**: Code formatting (120 character line length)\n- **Flake8**: Linting and style checking\n- **isort**: Import sorting\n- **MyPy**: Type checking\n- **Pytest**: Testing framework\n- **Pre-commit**: Git hooks\n\n### Setting up Development Environment\n\n1. **Create virtual environment and install dependencies:**\n ```bash\n python -m venv .venv\n .venv\\Scripts\\activate # Windows\n pip install -r requirements-dev.txt\n ```\n\n2. **Install pre-commit hooks:**\n ```bash\n pre-commit install\n ```\n\n### VSCode Tasks\n\nThis project includes VSCode tasks for common development operations:\n\n- **Setup Dev Environment**: Create venv and install dependencies\n- **Format Code**: Run Black formatter\n- **Lint Code**: Run Flake8 linter\n- **Sort Imports**: Run isort\n- **Type Check**: Run MyPy type checker\n- **Run Tests**: Execute pytest with coverage\n- **Check All**: Run all quality checks in sequence\n\nAccess these via `Ctrl+Shift+P` \u2192 \"Tasks: Run Task\"\n\n### Code Quality Commands\n\n```bash\n# Format code\nblack .\n\n# Sort imports\nisort .\n\n# Lint code\nflake8 .\n\n# Type check\nmypy src/libdyson_rest\n\n# Run tests\npytest\n\n# Run all checks\nblack . && isort . && flake8 . && mypy src/libdyson_rest && pytest\n```\n\n### Testing\n\nRun tests with coverage:\n\n```bash\n# All tests\npytest\n\n# Unit tests only\npytest tests/unit/\n\n# Integration tests only\npytest tests/integration/\n\n# With coverage report\npytest --cov=src/libdyson_rest --cov-report=html\n```\n\n## Project Structure\n\n```\nlibdyson-rest/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 libdyson_rest/ # Main library code\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 client.py # Main API client\n\u2502 \u251c\u2500\u2500 exceptions.py # Custom exceptions\n\u2502 \u251c\u2500\u2500 models/ # Data models\n\u2502 \u2514\u2500\u2500 utils/ # Utility functions\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 unit/ # Unit tests\n\u2502 \u2514\u2500\u2500 integration/ # Integration tests\n\u251c\u2500\u2500 .vscode/\n\u2502 \u2514\u2500\u2500 tasks.json # VSCode tasks\n\u251c\u2500\u2500 requirements.txt # Production dependencies\n\u251c\u2500\u2500 requirements-dev.txt # Development dependencies\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u251c\u2500\u2500 .flake8 # Flake8 configuration\n\u251c\u2500\u2500 .pre-commit-config.yaml # Pre-commit hooks\n\u2514\u2500\u2500 README.md\n```\n\n## Configuration Files\n\n- **pyproject.toml**: Main project configuration (Black, isort, pytest, mypy)\n- **.flake8**: Flake8 linting configuration\n- **.pre-commit-config.yaml**: Git pre-commit hooks\n- **requirements.txt**: Production dependencies\n- **requirements-dev.txt**: Development dependencies\n\n## Publishing to PyPI\n\nThis package is automatically published to PyPI using GitHub Actions. For detailed publishing instructions, see [PUBLISHING.md](PUBLISHING.md).\n\n### Quick Publishing\n\n- **Test Release**: GitHub Actions \u2192 Run workflow \u2192 TestPyPI\n- **Production Release**: Create a GitHub release with version tag (e.g., `v0.2.0`)\n- **Local Build**: `python .github/scripts/publish_to_pypi.py --check`\n\nThe package is available on PyPI as `libdyson-rest`.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes following the coding standards\n4. Run all quality checks: ensure Black, Flake8, isort, MyPy, and tests pass\n5. Commit your changes: `git commit -am 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Create a Pull Request\n\nAll PRs must pass the full test suite and code quality checks.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Security\n\n- No hardcoded credentials or sensitive data\n- Use environment variables for configuration\n- All user inputs are validated\n- API responses are sanitized\n\n## Roadmap\n\n- [ ] Complete API endpoint coverage\n- [ ] Asynchronous client support\n- [ ] WebSocket real-time updates\n- [ ] Command-line interface\n- [ ] Docker container support\n",
"bugtrack_url": null,
"license": null,
"summary": "Python library for interacting with Dyson devices through their official REST API",
"version": "0.4.0",
"project_urls": {
"Changelog": "https://github.com/cmgrayb/libdyson-rest/releases",
"Documentation": "https://github.com/cmgrayb/libdyson-rest#readme",
"Homepage": "https://github.com/cmgrayb/libdyson-rest",
"Issues": "https://github.com/cmgrayb/libdyson-rest/issues",
"Repository": "https://github.com/cmgrayb/libdyson-rest"
},
"split_keywords": [
"dyson",
" air-purifier",
" fan",
" iot",
" rest-api",
" mqtt",
" home-automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "320dd44d3753097f238fd3459d225ce72e2a2acf2783acb577600f265e28a6b2",
"md5": "cf3b8b87322132495fd19824065cc97f",
"sha256": "2fc83714efdd2c4c79984a507a88ba0d2f53219b5fd1129cb83a3ace672a7bf4"
},
"downloads": -1,
"filename": "libdyson_rest-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cf3b8b87322132495fd19824065cc97f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18570,
"upload_time": "2025-08-18T18:53:36",
"upload_time_iso_8601": "2025-08-18T18:53:36.618351Z",
"url": "https://files.pythonhosted.org/packages/32/0d/d44d3753097f238fd3459d225ce72e2a2acf2783acb577600f265e28a6b2/libdyson_rest-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "66f98326d44d45341e5712cf08eb007921bf4c1a5617e9268a3aad7453a758f0",
"md5": "fe309d5697b8753deec5eb7c625e196f",
"sha256": "adc138b953cc015ac0b6bd72cc2b22be231eddb678089c3822ba620d0bda5d61"
},
"downloads": -1,
"filename": "libdyson_rest-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "fe309d5697b8753deec5eb7c625e196f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 23024,
"upload_time": "2025-08-18T18:53:38",
"upload_time_iso_8601": "2025-08-18T18:53:38.016987Z",
"url": "https://files.pythonhosted.org/packages/66/f9/8326d44d45341e5712cf08eb007921bf4c1a5617e9268a3aad7453a758f0/libdyson_rest-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 18:53:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cmgrayb",
"github_project": "libdyson-rest",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.28.0"
]
]
},
{
"name": "cryptography",
"specs": [
[
">=",
"3.4.0"
]
]
}
],
"lcname": "libdyson-rest"
}
JSON
