cloudweatherlib 0.1.0

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

☁️ cloudweatherlib

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

pip install cloudweatherlib

For development (with testing tools):

pip install cloudweatherlib[dev]

---

🚀 Quick Start

Basic Usage — Get Current Weather

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

# 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

# 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

# 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)

# 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

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)

# 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

# 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 file for details.