Add Tomorrow.io weather provider and improve documentation

- Add Tomorrow.io as a new weather provider with full weather code mapping
- Update README with provider comparison table and detailed setup instructions
- Modernize tests to work with Sopel 8 and add provider-specific tests
- All 14 tests passing for Open-Meteo, Pirate Weather, and Tomorrow.io

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: RustyBower

README.md

@@ -11,11 +11,15 @@ A weather lookup plugin for Sopel IRC bots.
 pip install sopel-weather
 ```
 
-## Configuration
+## Quick Start
 
-You can automatically configure this plugin using `sopel configure --plugins`.
+Configure the plugin using:
 
-Or configure manually in `~/.sopel/default.cfg`:
+```bash
+sopel configure --plugins
+```
+
+Or manually edit `~/.sopel/default.cfg`:
 
 ```ini
 [weather]
@@ -25,49 +29,168 @@ weather_provider = openmeteo
 weather_api_key = dummy
 ```
 
-## Usage
+## Weather Providers
+
+| Provider | API Key Required | Free Tier | UV Index | Features |
+|----------|-----------------|-----------|----------|----------|
+| **Open-Meteo** | No (use "dummy") | Unlimited | No | Best for basic weather, no signup needed |
+| **Tomorrow.io** | Yes | 500 calls/day | Yes | Modern API, good accuracy |
+| **Pirate Weather** | Yes | 20,000 calls/month | Yes | Dark Sky replacement |
+| **OpenWeatherMap** | Yes | 1,000 calls/day | Yes | Popular, well-documented |
+
+### Open-Meteo (Recommended for simplicity)
+
+No API key required. Use any string (e.g., "dummy") for the weather_api_key.
+
+```ini
+[weather]
+weather_provider = openmeteo
+weather_api_key = dummy
+```
+
+- Website: https://open-meteo.com/
+- Free for non-commercial use
+- No signup required
+
+### Tomorrow.io
+
+Sign up at https://www.tomorrow.io/ for a free API key.
+
+```ini
+[weather]
+weather_provider = tomorrow
+weather_api_key = YOUR_TOMORROW_API_KEY
+```
+
+- Free tier: 500 API calls/day
+- Includes UV index
+- Modern REST API
+
+### Pirate Weather
+
+Sign up at https://pirateweather.net/ for a free API key.
+
+```ini
+[weather]
+weather_provider = pirateweather
+weather_api_key = YOUR_PIRATEWEATHER_API_KEY
+```
+
+- Free tier: 20,000 API calls/month
+- Drop-in Dark Sky API replacement
+- Includes UV index
+
+### OpenWeatherMap
+
+Sign up at https://openweathermap.org/ for a free API key.
+
+```ini
+[weather]
+weather_provider = openweathermap
+weather_api_key = YOUR_OPENWEATHERMAP_API_KEY
+```
+
+- Free tier: 1,000 API calls/day
+- Includes UV index
+
+## Geocoding Provider
+
+A geocoding provider is required to convert location names (like "Seattle" or "90210") to coordinates.
+
+### LocationIQ (Required)
+
+Sign up at https://locationiq.com/ for a free API key.
+
+```ini
+[weather]
+geocoords_provider = locationiq_us
+geocoords_api_key = YOUR_LOCATIONIQ_API_KEY
+```
+
+Options:
+- `locationiq_us` - US-based servers (recommended for North America)
+- `locationiq_eu` - EU-based servers (recommended for Europe)
+
+Free tier: 5,000 requests/day
+
+## Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `geocoords_provider` | Geocoding provider (`locationiq_us`, `locationiq_eu`) | `locationiq_us` |
+| `geocoords_api_key` | API key for geocoding provider | Required |
+| `weather_provider` | Weather provider (`openmeteo`, `tomorrow`, `pirateweather`, `openweathermap`) | Required |
+| `weather_api_key` | API key for weather provider | Required |
+| `sunrise_sunset` | Show sunrise/sunset times | `False` |
+| `nick_lookup` | Allow looking up weather by IRC nickname | `True` |
+
+### Example Configuration
+
+```ini
+[weather]
+geocoords_provider = locationiq_us
+geocoords_api_key = pk.abc123...
+weather_provider = tomorrow
+weather_api_key = abc123xyz...
+sunrise_sunset = True
+nick_lookup = True
+```
+
+## Commands
 
 ### Current Weather
 
 ```
 .weather              # Uses your saved location
-.weather seattle, us
-.weather london
+.weather seattle
+.weather Seattle, US
+.weather 90210
 ```
 
 Example output:
 ```
-Paris, Ile-de-France, FR: 6°C (42°F), Clear, Humidity: 83%, UV Index: 0, Gentle breeze 4.0m/s (↗)
+Seattle, Washington, US: 12°C (54°F), Partly Cloudy, Humidity: 75%, UV Index: 2, Gentle breeze: 19km/h (12mph) (↑)
 ```
 
 ### Forecast
 
 ```
-.forecast              # Uses your saved location
-.forecast seattle, us
-.forecast london
+.forecast             # Uses your saved location
+.forecast seattle
+.forecast London, UK
+```
+
+Example output:
+```
+Seattle, WA, US :: Monday - Partly Cloudy - 12°C (54°F) / 5°C (41°F) :: Tuesday - Rain - 14°C (57°F) / 6°C (43°F) ...
 ```
 
 ### Set Your Location
 
 ```
-.setlocation london    # Set by city name
-.setlocation 98101     # Set by US zip code
+.setlocation seattle
+.setlocation 98101
+.setlocation London, UK
 ```
 
-## API Keys Required
+## Troubleshooting
+
+### "Weather API key missing"
+Set `weather_api_key` in your configuration. For Open-Meteo, use any string like "dummy".
+
+### "GeoCoords API key missing"
+Sign up at https://locationiq.com/ and add your API key to `geocoords_api_key`.
 
-### GeoCoords Provider
-- [LocationIQ](https://locationiq.com/) - Free tier available
+### "Could not geocode location"
+- Check your LocationIQ API key is valid
+- Try a more specific location (e.g., "Seattle, WA" instead of "Seattle")
+- Check LocationIQ rate limits (5,000/day on free tier)
 
-### Weather Providers
+### "Error: Invalid API key"
+Verify your weather provider API key is correct and active.
 
-- **Open-Meteo** - No API key required (use any string)
-  - https://open-meteo.com/
-- **OpenWeatherMap** - Free tier available
-  - https://openweathermap.org/
-- **Pirate Weather** - Drop-in Dark Sky replacement
-  - https://pirateweather.net/
+### UV Index not showing
+UV Index is only available with Tomorrow.io, Pirate Weather, and OpenWeatherMap providers.
 
 ## Requirements
 
@@ -76,4 +199,4 @@ Paris, Ile-de-France, FR: 6°C (42°F), Clear, Humidity: 83%, UV Index: 0, Gentl
 
 ## License
 
-MIT License
+Eiffel Forum License 2

sopel_weather/__init__.py

@@ -23,12 +23,14 @@
 from .providers.weather.openmeteo import openmeteo_forecast, openmeteo_weather
 from .providers.weather.openweathermap import openweathermap_forecast, openweathermap_weather
 from .providers.weather.pirateweather import pirateweather_forecast, pirateweather_weather
+from .providers.weather.tomorrow import tomorrow_forecast, tomorrow_weather
 
 WEATHER_PROVIDERS = [
     'darksky',
     'openmeteo',
     'openweathermap',
     'pirateweather',
+    'tomorrow',
 ]
 
 GEOCOORDS_PROVIDERS = {
@@ -252,6 +254,9 @@ def get_forecast(bot, trigger):
     # Pirate Weather
     elif bot.config.weather.weather_provider == 'pirateweather':
         return pirateweather_forecast(bot, latitude, longitude, location)
+    # Tomorrow.io
+    elif bot.config.weather.weather_provider == 'tomorrow':
+        return tomorrow_forecast(bot, latitude, longitude, location)
     # Unsupported Provider
     else:
         raise Exception('Error: Unsupported Provider')
@@ -273,6 +278,9 @@ def get_weather(bot, trigger):
     # Pirate Weather
     elif bot.config.weather.weather_provider == 'pirateweather':
         return pirateweather_weather(bot, latitude, longitude, location)
+    # Tomorrow.io
+    elif bot.config.weather.weather_provider == 'tomorrow':
+        return tomorrow_weather(bot, latitude, longitude, location)
     # Unsupported Provider
     else:
         raise Exception('Error: Unsupported Provider')

sopel_weather/providers/weather/tomorrow.py

@@ -0,0 +1,122 @@
+# coding=utf-8
+import requests
+
+from datetime import datetime
+
+
+API_ENDPOINT = 'https://api.tomorrow.io/v4/weather/forecast'
+
+# Tomorrow.io weather codes
+# https://docs.tomorrow.io/reference/data-layers-weather-codes
+WEATHER_CODES = {
+    0: "Unknown",
+    1000: "Clear",
+    1001: "Cloudy",
+    1100: "Mostly Clear",
+    1101: "Partly Cloudy",
+    1102: "Mostly Cloudy",
+    2000: "Fog",
+    2100: "Light Fog",
+    4000: "Drizzle",
+    4001: "Rain",
+    4200: "Light Rain",
+    4201: "Heavy Rain",
+    5000: "Snow",
+    5001: "Flurries",
+    5100: "Light Snow",
+    5101: "Heavy Snow",
+    6000: "Freezing Drizzle",
+    6001: "Freezing Rain",
+    6200: "Light Freezing Rain",
+    6201: "Heavy Freezing Rain",
+    7000: "Ice Pellets",
+    7101: "Heavy Ice Pellets",
+    7102: "Light Ice Pellets",
+    8000: "Thunderstorm",
+}
+
+
+def tomorrow_forecast(bot, latitude, longitude, location):
+    params = {
+        'location': '{},{}'.format(latitude, longitude),
+        'apikey': bot.config.weather.weather_api_key,
+        'units': 'metric',
+        'timesteps': 'daily',
+    }
+
+    try:
+        r = requests.get(API_ENDPOINT, params=params)
+    except:
+        raise Exception("An Error Occurred. Check Logs For More Information.")
+
+    data = r.json()
+    if r.status_code != 200:
+        error_msg = data.get('message', data.get('error', 'Unknown error'))
+        raise Exception('Error: {}'.format(error_msg))
+
+    weather_data = {'location': location, 'data': []}
+
+    daily_data = data['timelines']['daily']
+    for day in daily_data[:4]:
+        weather_code = day['values'].get('weatherCodeMax', 0)
+        condition = WEATHER_CODES.get(weather_code, 'Unknown')
+
+        weather_data['data'].append({
+            'dow': datetime.fromisoformat(day['time'].replace('Z', '+00:00')).strftime('%A'),
+            'summary': condition,
+            'high_temp': day['values']['temperatureMax'],
+            'low_temp': day['values']['temperatureMin'],
+        })
+
+    return weather_data
+
+
+def tomorrow_weather(bot, latitude, longitude, location):
+    params = {
+        'location': '{},{}'.format(latitude, longitude),
+        'apikey': bot.config.weather.weather_api_key,
+        'units': 'metric',
+        'timesteps': 'current,daily',
+    }
+
+    try:
+        r = requests.get(API_ENDPOINT, params=params)
+    except:
+        raise Exception("An Error Occurred. Check Logs For More Information.")
+
+    data = r.json()
+    if r.status_code != 200:
+        error_msg = data.get('message', data.get('error', 'Unknown error'))
+        raise Exception('Error: {}'.format(error_msg))
+
+    current = data['timelines']['minutely'][0]['values']
+    weather_code = current.get('weatherCode', 0)
+    condition = WEATHER_CODES.get(weather_code, 'Unknown')
+
+    # Wind speed from Tomorrow.io is in m/s when using metric units
+    weather_data = {
+        'location': location,
+        'temp': current['temperature'],
+        'condition': condition,
+        'humidity': current['humidity'] / 100.0,  # normalize to decimal percentage
+        'wind': {
+            'speed': current['windSpeed'],
+            'bearing': current['windDirection'],
+        },
+        'uvindex': current.get('uvIndex'),
+        'timezone': data['location'].get('timezone', 'UTC'),
+    }
+
+    if bot.config.weather.sunrise_sunset:
+        daily = data['timelines']['daily'][0]['values']
+        # Parse ISO format timestamps and convert to Unix timestamps
+        sunrise_str = daily.get('sunriseTime', '')
+        sunset_str = daily.get('sunsetTime', '')
+        if sunrise_str:
+            weather_data['sunrise'] = int(datetime.fromisoformat(
+                sunrise_str.replace('Z', '+00:00')).timestamp())
+        if sunset_str:
+            weather_data['sunset'] = int(datetime.fromisoformat(
+                sunset_str.replace('Z', '+00:00')).timestamp())
+
+    return weather_data