Metadata-Version: 2.4
Name: weatherflow4py
Version: 1.5.4
Summary: Python library used by Home Assistant to interact with the WeatherFlow REST API
Project-URL: Homepage, https://github.com/jeeftor/weatherflow4py
Project-URL: Repository, https://github.com/jeeftor/weatherflow4py
Project-URL: Bug Tracker, https://github.com/jeeftor/weatherflow4py/issues
Author-email: Jeef <jeeftor@users.noreply.github.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <4.0,>=3.12
Requires-Dist: aiohttp>=3.13.3
Requires-Dist: dataclasses-json>=0.6.3
Requires-Dist: marshmallow>=3.20.1
Requires-Dist: websockets>=11.0
Provides-Extra: dev
Requires-Dist: aioresponses>=0.7.6; extra == 'dev'
Requires-Dist: coverage>=7.4.0; extra == 'dev'
Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.2; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.3; extra == 'dev'
Requires-Dist: python-dotenv>=1.0.1; extra == 'dev'
Requires-Dist: ruff>=0.1.9; extra == 'dev'
Requires-Dist: ty>=0.0.1a21; extra == 'dev'
Requires-Dist: uv>=0.8.10; extra == 'dev'
Description-Content-Type: text/markdown

# WeatherFlow4Py

A Python library for interacting with the WeatherFlow REST API and WebSocket services. This library provides both synchronous and asynchronous interfaces to access weather data from WeatherFlow weather stations.

[![PyPI](https://img.shields.io/pypi/v/weatherflow4py.svg)](https://pypi.org/project/weatherflow4py/)
[![Test PyPI](https://img.shields.io/badge/Test%20PyPI-available-blue)](https://test.pypi.org/project/weatherflow4py/)

## Features

- **REST API Client**: Access station data, forecasts, and observations
- **WebSocket Client**: Real-time weather data updates
- **Type Annotations**: Full type support for better development experience
- **Asynchronous Support**: Built with `asyncio` for efficient I/O operations
- **Pydantic Models**: Strongly-typed data models for all API responses

## Installation

```bash
pip install weatherflow4py
```

Or with uv:

```bash
uv pip install weatherflow4py
```

## Prerequisites

- Python 3.12 or higher
- WeatherFlow API token (available from [WeatherFlow's website](https://tempestwx.com))

## Quick Start

### REST API Example

```python
import asyncio
from weatherflow4py.api import WeatherFlowRestAPI

async def main():
    # Initialize the API with your token
    async with WeatherFlowRestAPI("YOUR_API_TOKEN") as api:
        # Get all available stations
        stations = await api.async_get_stations()
        
        for station in stations.stations:
            print(f"Station: {station.name}")
            print(f"Location: {station.latitude}, {station.longitude}")
            
            # Get current observations
            obs = await api.async_get_observation(station.station_id)
            print(f"Current temperature: {obs.obs[0].air_temperature}°C")
            
            # Get forecast
            forecast = await api.async_get_forecast(station.station_id)
            print(f"Forecast high: {forecast.forecast.daily[0].air_temp_high}°C")

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

### WebSocket Example

```python
import asyncio
import logging
from weatherflow4py.ws import WeatherFlowWebsocketAPI

# Set up logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

async def main():
    # Initialize the WebSocket client
    ws = WeatherFlowWebsocketAPI("YOUR_API_TOKEN")
    
    # Define callback functions for different message types
    def handle_observation(data):
        print(f"Observation received - Temp: {data.air_temperature}°C")
    
    def handle_rapid_wind(data):
        print(f"Wind speed: {data.wind_speed} m/s at {data.wind_direction}°")
    
    # Register callbacks
    ws.register_callback("obs_st", handle_observation)
    ws.register_callback("rapid_wind", handle_rapid_wind)
    
    try:
        # Start listening for messages
        await ws.connect()
        
        # Start listening to all available devices
        await ws.start_listening()
        
        # Keep the connection alive
        while True:
            await asyncio.sleep(1)
            
    except KeyboardInterrupt:
        print("Disconnecting...")
    finally:
        await ws.disconnect()

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

## API Documentation

### REST API

The `WeatherFlowRestAPI` class provides the following methods:

- `async_get_stations()`: Get all stations associated with the account
- `async_get_observation(station_id)`: Get current observations for a station
- `async_get_forecast(station_id)`: Get forecast data for a station
- `async_get_device_observations(device_id)`: Get observations from a specific device
- `get_all_data()`: Get all available data for all stations

### WebSocket API

The `WeatherFlowWebsocketAPI` class provides real-time updates:

- `connect()`: Establish WebSocket connection
- `disconnect()`: Close the connection
- `start_listening(device_ids=None)`: Start listening for updates
- `stop_listening(device_ids=None)`: Stop listening for updates
- `register_callback(message_type, callback)`: Register a callback for specific message types

## Error Handling

The library raises specific exceptions for different error conditions:

- `TokenError`: When no API token is provided
- `APIError`: For general API errors
- `WebSocketError`: For WebSocket connection issues

## Rate Limiting

- **REST API**: Limited to 100 requests per minute
- **WebSocket**: Follows WeatherFlow's rate limiting policies

## Resources

- [WeatherFlow API Documentation](https://apidocs.tempestwx.com/reference/quick-start)
- [WeatherFlow REST API Swagger](https://weatherflow.github.io/Tempest/api/swagger/)
- [WeatherFlow WebSocket Documentation](https://weatherflow.github.io/Tempest/api/ws.html)

## Development

This project uses [uv](https://github.com/astral-sh/uv) for dependency management and virtual environment creation.

### Setup with Nix

If you have Nix installed with flakes enabled:

```bash
# Enter the development environment
nix develop

# This will automatically:
# 1. Create a virtual environment with uv
# 2. Install dependencies from requirements.txt and requirements-dev.txt
# 3. Install the project in development mode
```

### Manual Setup with uv

```bash
# Create a virtual environment
uv venv

# Activate the virtual environment
source .venv/bin/activate

# Install dependencies
uv pip install -r requirements.txt
uv pip install -r requirements-dev.txt

# Install the project in development mode
uv pip install -e .
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- WeatherFlow for their excellent weather station hardware and API
- All contributors who have helped improve this library

## Support

For support, please open an issue on the [GitHub repository](https://github.com/jeeftor/weatherflow4py).