skypulse

☀️ SkyPulse

Modern Python Weather Data Package with Async Support

A powerful Python library for weather data retrieval with both synchronous and asynchronous support.

Features • Installation • Quick Start • Documentation • Contributing

✨ Features

🔄 Modern Python Design

• Full type hints support
• Async and sync operations
• Dataclass-style models
• Context managers
• Clean API interface

🌡️ Weather Data

• Current weather conditions
• Detailed forecasts
• Hourly predictions
• Astronomical data
• Wind information

⚡ Flexible Usage

• Sync/Async operations
• Custom API endpoints
• Format selection (j1/j2)
• Unit preferences
• Multi-location support

🛠️ Developer Experience

• Type safety
• Error handling
• Data validation
• Easy integration
• Modular design

🚀 Installation

📦 From PyPI

pip install skypulse

🔧 Development Installation

git clone https://github.com/HelpingAI/skypulse.git
cd skypulse
pip install -e .

📋 Requirements

• Python 3.7+
• Required packages:
  • requests>=2.28.2 - HTTP requests for sync operations
  • aiohttp>=3.8.4 - Async HTTP client

📖 Quick Start

🔄 Synchronous Usage

from skypulse import SkyPulse, UnitPreferences

# Initialize client
client = SkyPulse()

# Set unit preferences (optional)
client.set_units(UnitPreferences(
    temperature="C",
    wind_speed="kmh",
    pressure="mb"
))

# Get current weather
current = client.get_current("London")
print(f"Temperature: {current.temperature_c}°C")
print(f"Condition: {current.condition.description}")
print(f"Wind: {current.wind_speed_kmh} km/h {current.wind_direction}")
print(f"Humidity: {current.humidity}%")

# Get forecast with hourly data
forecast = client.get_forecast("London")
for day in forecast.days:
    print(f"\nDate: {day.date}")
    print(f"Temperature: {day.min_temp_c}°C to {day.max_temp_c}°C")
    print(f"Sunrise: {day.astronomy.sunrise}")
    print(f"Sunset: {day.astronomy.sunset}")
    
    # Hourly forecast
    for hour in day.hourly:
        print(f"\nTime: {hour.time}")
        print(f"Temperature: {hour.temperature_c}°C")
        print(f"Feels like: {hour.feels_like_c}°C")
        print(f"Rain chance: {hour.rain_chance}%")

⚡ Asynchronous Usage

import asyncio
from skypulse import SkyPulse

async def compare_weather():
    async with SkyPulse(async_mode=True) as client:
        # Compare weather for multiple cities concurrently
        cities = ["London", "New York", "Tokyo"]
        tasks = [client.get_current_async(city) for city in cities]
        results = await asyncio.gather(*tasks)
        
        for city, weather in zip(cities, results):
            print(f"\n{city}:")
            print(f"Temperature: {weather.temperature_c}°C")
            print(f"Condition: {weather.condition.description}")
            print(f"Humidity: {weather.humidity}%")

# Run async code
asyncio.run(compare_weather())

📚 Core Features

Current Weather

• Real-time temperature and humidity
• Wind speed, direction, and gusts
• Atmospheric pressure
• Cloud cover and visibility
• Weather conditions with icons

Weather Forecast

• Multi-day weather forecasts
• Hourly predictions
• Temperature ranges
• Rain and snow chances
• Astronomical data (sunrise/sunset)

Location Support

• City name or coordinates
• Country and region info
• Latitude and longitude
• Population data
• Weather station URL

Unit Preferences

• Temperature (°C/°F)
• Wind speed (km/h, mph)
• Pressure (mb, in)
• Distance (km, miles)
• Precipitation (mm, in)

AI Analysis

• Real-time weather insights
• Natural language analysis
• Activity suggestions
• Weather pattern detection
• Streaming responses
• Cross-platform Unicode support

🤖 AI Usage

from skypulse.ai_weather import WeatherAnalyzer

# Initialize analyzer
analyzer = WeatherAnalyzer()

# Get AI analysis
analysis = analyzer.analyze_weather("Tokyo")
print(analysis)

# CLI usage
skypulse analyze --location "Tokyo"

📝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

This project is licensed under the HelpingAI License v3.0 - see the LICENSE file for details.

Made with ❤️ by HelpingAI

HelpingAI License • Code of Conduct • Security Policy