Metadata-Version: 2.4
Name: cloudweatherlib
Version: 0.1.0
Summary: A reusable Python OOP library for weather data processing, multi-provider integration, severity analysis, and unit conversions.
Home-page: https://github.com/ksumachowdary/cloudweatherlib
Author: ksumachowdary
Author-email: ksumachowdary <ksuma0301@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/ksumachowdary/cloudweatherlib
Project-URL: Documentation, https://github.com/ksumachowdary/cloudweatherlib#readme
Project-URL: Repository, https://github.com/ksumachowdary/cloudweatherlib
Project-URL: Bug Tracker, https://github.com/ksumachowdary/cloudweatherlib/issues
Project-URL: Changelog, https://github.com/ksumachowdary/cloudweatherlib/blob/main/CHANGELOG.txt
Keywords: weather,cloud,google-weather-api,openweathermap,oop,meteorology,forecast,climate,dashboard
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# ☁️ cloudweatherlib

[![PyPI version](https://badge.fury.io/py/cloudweatherlib.svg)](https://badge.fury.io/py/cloudweatherlib)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**A powerful, reusable Python OOP library for weather data processing, multi-provider API integration, severity analysis, and unit conversions.**

`cloudweatherlib` provides a clean, object-oriented interface for fetching and processing weather data from multiple providers (Google Weather API, OpenWeatherMap). It handles raw API responses, converts units, analyzes weather severity, and aggregates data across multiple cities — all through a simple Facade client.

---

## 🏗️ Architecture & OOP Principles

| OOP Pillar | Implementation | Class(es) |
|---|---|---|
| **Abstraction** | Abstract base class defines the provider contract | `WeatherProvider` (ABC) |
| **Inheritance** | Concrete providers extend the abstract base | `GoogleWeatherProvider`, `OpenWeatherMapProvider` |
| **Encapsulation** | Private attributes with validated property accessors | `Location`, `WeatherData`, `Forecast` |
| **Polymorphism** | Interchangeable providers with identical interfaces | Swap Google ↔ OpenWeatherMap without code changes |

### Design Patterns Used

- **Facade Pattern** — `CloudWeatherClient` provides a single entry point
- **Factory Method** — `_create_provider()` instantiates the correct provider
- **Strategy Pattern** — `TemperatureConverter`, `WindSpeedConverter` for interchangeable algorithms
- **Adapter Pattern** — `OpenWeatherMapProvider` adapts OWM JSON to library models
- **Template Method** — `WeatherProvider` base class defines the processing template

---

## 📦 Installation

```bash
pip install cloudweatherlib
```

For development (with testing tools):

```bash
pip install cloudweatherlib[dev]
```

---

## 🚀 Quick Start

### Basic Usage — Get Current Weather

```python
from cloudweatherlib import CloudWeatherClient, Location

# Initialize the client with your API provider and key
client = CloudWeatherClient(provider="google", api_key="YOUR_GOOGLE_API_KEY")

# Create a location
dublin = Location("Dublin", latitude=53.3498, longitude=-6.2603, country_code="IE")

# Fetch current weather
weather = client.get_current_weather(dublin)

# Access weather data through clean properties
print(f"City: {weather.location.city_name}")
print(f"Temperature: {weather.temperature_celsius}°C / {weather.temperature_fahrenheit}°F")
print(f"Condition: {weather.condition_text}")
print(f"Wind: {weather.wind_speed_kmh} km/h ({weather.wind_speed_mph} mph)")
print(f"Humidity: {weather.humidity_percent}%")
print(f"UV Index: {weather.uv_index}")
```

### Get Weather Forecast

```python
# Daily forecast (up to 10 days)
forecasts = client.get_forecast(dublin, days=5)

for forecast in forecasts:
    print(f"{forecast.date}: {forecast.high_temp_celsius}°C / {forecast.low_temp_celsius}°C "
          f"- {forecast.condition_text} (Rain: {forecast.precipitation_probability}%)")

# Hourly forecast (up to 24 hours)
hourly = client.get_hourly_forecast(dublin, hours=12)
```

### Analyze Weather Severity

```python
# Get severity assessment
severity = client.get_severity(weather)

print(f"Severity Level: {severity['level']}")     # e.g., "WARNING"
print(f"Severity Score: {severity['score']}/100")  # e.g., 35
print(f"Alerts: {severity['alerts']}")             # e.g., ["Strong Wind: 52.3 km/h"]
print(f"Is Safe: {severity['is_safe']}")           # e.g., False
```

### Multi-City Dashboard Aggregation

```python
# Fetch weather for multiple cities
cities = [
    Location("Dublin", 53.3498, -6.2603, "IE"),
    Location("London", 51.5074, -0.1278, "GB"),
    Location("Paris", 48.8566, 2.3522, "FR"),
    Location("Berlin", 52.5200, 13.4050, "DE"),
]

weather_list = [client.get_current_weather(city) for city in cities]

# Get aggregated statistics
summary = client.get_multi_city_summary(weather_list)

print(f"Average Temperature: {summary['temperature']['average_celsius']}°C")
print(f"Hottest City: {summary['temperature']['highest']['city']}")
print(f"Coldest City: {summary['temperature']['lowest']['city']}")
print(f"Windiest City: {summary['wind']['windiest_city']['city']}")

# Group cities by weather condition
grouped = client.group_cities_by_condition(weather_list)
print(f"Sunny cities: {grouped.get('CLEAR', [])}")
print(f"Rainy cities: {grouped.get('RAIN', [])}")
```

### Switch Providers (Polymorphism)

```python
# Using Google Weather API
google_client = CloudWeatherClient(provider="google", api_key="GOOGLE_KEY")

# Using OpenWeatherMap — exact same interface!
owm_client = CloudWeatherClient(provider="openweathermap", api_key="OWM_KEY")

# Both return identical WeatherData objects
weather_google = google_client.get_current_weather(dublin)
weather_owm = owm_client.get_current_weather(dublin)

# Same properties work regardless of provider
print(weather_google.temperature_celsius)
print(weather_owm.temperature_celsius)
```

### Unit Converters — Standalone Usage

```python
from cloudweatherlib.converters.temperature import TemperatureConverter, TemperatureUnit
from cloudweatherlib.converters.wind import WindSpeedConverter, WindSpeedUnit

# Temperature conversions
print(TemperatureConverter.celsius_to_fahrenheit(25.0))  # 77.0
print(TemperatureConverter.fahrenheit_to_celsius(77.0))  # 25.0
print(TemperatureConverter.celsius_to_kelvin(25.0))      # 298.15

# Unified convert method
print(TemperatureConverter.convert(100.0, TemperatureUnit.CELSIUS, TemperatureUnit.FAHRENHEIT))  # 212.0

# Wind speed conversions
print(WindSpeedConverter.kmh_to_mph(100.0))    # 62.1
print(WindSpeedConverter.kmh_to_ms(100.0))     # 27.8
print(WindSpeedConverter.kmh_to_knots(100.0))  # 54.0

# Beaufort Scale classification
print(WindSpeedConverter.to_beaufort_scale(75.0))  # "Near Gale (Force 7)"
```

### Serialize to JSON (FastAPI Integration)

```python
# Convert weather data to a dictionary for API responses
weather_dict = weather.to_dict()

# In FastAPI:
# @router.get("/weather/{city}")
# async def get_weather(city: str, lat: float, lon: float):
#     location = Location(city, lat, lon)
#     weather = client.get_current_weather(location)
#     return {"weather": weather.to_dict(), "severity": client.get_severity(weather)}
```

---

## 📖 API Reference

### Core Classes

| Class | Module | Description |
|---|---|---|
| `CloudWeatherClient` | `cloudweatherlib` | High-level Facade — the main entry point |
| `Location` | `cloudweatherlib.models` | Geographic location with validated coordinates |
| `WeatherData` | `cloudweatherlib.models` | Current weather conditions with unit conversions |
| `Forecast` | `cloudweatherlib.models` | Daily forecast data |
| `CloudWeatherConfig` | `cloudweatherlib.config` | Encapsulated configuration management |

### Providers

| Class | Module | Description |
|---|---|---|
| `WeatherProvider` | `cloudweatherlib.providers` | Abstract base class (ABC) |
| `GoogleWeatherProvider` | `cloudweatherlib.providers` | Google Maps Weather API v1 |
| `OpenWeatherMapProvider` | `cloudweatherlib.providers` | OpenWeatherMap API v2.5 |

### Analyzers

| Class | Module | Description |
|---|---|---|
| `SeverityAnalyzer` | `cloudweatherlib.analyzers` | Weather severity scoring (0-100) |
| `SeverityLevel` | `cloudweatherlib.analyzers` | Severity level constants |
| `WeatherAggregator` | `cloudweatherlib.analyzers` | Multi-city statistics & grouping |

### Converters

| Class | Module | Description |
|---|---|---|
| `TemperatureConverter` | `cloudweatherlib.converters` | °C ↔ °F ↔ K conversions |
| `WindSpeedConverter` | `cloudweatherlib.converters` | km/h ↔ mph ↔ m/s ↔ knots |

### Exceptions

| Exception | Description |
|---|---|
| `CloudWeatherLibError` | Base exception for all library errors |
| `WeatherAPIError` | API request failures |
| `WeatherDataNotFoundError` | Data parsing failures |
| `InvalidLocationError` | Invalid coordinates/city |
| `ProviderNotSupportedError` | Unsupported provider requested |
| `ConfigurationError` | Invalid configuration |

---

## 🧪 Running Tests

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run with coverage report
pytest --cov=cloudweatherlib --cov-report=html

# Run specific test file
pytest tests/test_severity.py -v
```

---

## 📋 Requirements

- Python >= 3.9
- requests >= 2.28.0

---

## 📄 License

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