xweather2epw 0.1.0__tar.gz

xweather2epw-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Foobot AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xweather2epw-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.1
+Name: xweather2epw
+Version: 0.1.0
+Summary: A tool that fetches data from the XWeather API and generates EnergyPlus Weather files (EPW)
+Home-page: https://github.com/airboxlab/xweather2epw
+Keywords: weather,epw,energyplus,xweather
+Author: Antoine Galataud
+Author-email: antoine@foobot.io
+Requires-Python: >=3.12,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: click (>=8.1.7,<9.0.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Project-URL: Repository, https://github.com/airboxlab/xweather2epw
+Description-Content-Type: text/markdown
+
+# XWeather to EPW Converter
+
+A tool that fetches data from the [XWeather API](https://www.xweather.com/docs/weather-api/) and generates a full year AMY (Actual Meteorological Year) EnergyPlus Weather file (EPW).
+
+The tool takes care of fetching the necessary data from the API, processing it, and formatting it into the EPW format. It's designed for fast and efficient data retrieval.
+
+# Installation
+
+## Prerequisites
+
+You need to have a XWeather API access. Note that at hourly frequency (which is used for EPW generation), each day of data costs 1 API request.
+
+## Install the package
+
+### From source
+
+Clone the current repository and install the required dependencies using [Poetry](https://python-poetry.org/):
+
+```bash
+git clone https://github.com/airboxlab/xweather2epw.git
+cd xweather2epw
+poetry install
+```
+
+# Usage
+
+Example usage:
+
+```bash
+# using poetry, execute in local repository
+poetry run xweather2epw fetch --from '2025-01-01' --to '2025-12-31' --latitude 49.4 --longitude 0.1 --api-key YOUR_KEY --api-secret YOUR_SECRET
+
+# specify a custom output file
+poetry run xweather2epw fetch --from '2025-01-01' --to '2025-12-31' --latitude 49.4 --longitude 0.1 --api-key YOUR_KEY --api-secret YOUR_SECRET --output my_weather.epw
+```
+
+Use `--help` to have a list of available options:
+
+```bash
+poetry run xweather2epw --help
+poetry run xweather2epw fetch --help
+```
+
+## Development
+
+### Running Tests
+
+To run the test suite:
+
+```bash
+poetry run test
+```
+
+This will execute all unit tests with verbose output.
+
+## Features
+
+- **Date Range Validation**: Validates input parameters (latitude, longitude, date range)
+- **Smart Chunking**: Automatically splits requests into 15-day chunks to comply with API limits
+- **Date Range Limits**: 
+  - Maximum duration: 1 year (365 days)
+  - Forecast limit: Up to 14 days in the future
+- **Missing Data Handling**: Uses safe default values for missing weather data
+- **Unit Conversion**: Automatically converts units to comply with EPW format (SI units)
+- **EPW Header Generation**: Populates EPW headers with location information from API response
+- **Solar Radiation Data**: Extracts solar radiation data from XWeather API's `solrad` field (GHI, DNI, DHI)
+- **Sequential Processing**: Processes data chunks sequentially for reliability
+
+## Limitations
+
+- Ground/soil temperatures cannot be calculated from XWeather API data, so the `GROUND TEMPERATURES` header is set to `0`
+- Some advanced EPW fields (like extraterrestrial radiation and illuminance) are not available from the XWeather conditions endpoint and are filled with missing data indicators
+- Historical data availability depends on your XWeather API subscription
+
+## Documentation
+
+- [XWeather API Documentation](https://www.xweather.com/docs/weather-api/)
+- [XWeather Conditions Endpoint](https://www.xweather.com/docs/weather-api/endpoints/conditions)
+- [EPW Format Specification](https://designbuilder.co.uk/cahelp/Content/EnergyPlusWeatherFileFormat.htm)
+
+

xweather2epw-0.1.0/README.md

@@ -0,0 +1,80 @@
+# XWeather to EPW Converter
+
+A tool that fetches data from the [XWeather API](https://www.xweather.com/docs/weather-api/) and generates a full year AMY (Actual Meteorological Year) EnergyPlus Weather file (EPW).
+
+The tool takes care of fetching the necessary data from the API, processing it, and formatting it into the EPW format. It's designed for fast and efficient data retrieval.
+
+# Installation
+
+## Prerequisites
+
+You need to have a XWeather API access. Note that at hourly frequency (which is used for EPW generation), each day of data costs 1 API request.
+
+## Install the package
+
+### From source
+
+Clone the current repository and install the required dependencies using [Poetry](https://python-poetry.org/):
+
+```bash
+git clone https://github.com/airboxlab/xweather2epw.git
+cd xweather2epw
+poetry install
+```
+
+# Usage
+
+Example usage:
+
+```bash
+# using poetry, execute in local repository
+poetry run xweather2epw fetch --from '2025-01-01' --to '2025-12-31' --latitude 49.4 --longitude 0.1 --api-key YOUR_KEY --api-secret YOUR_SECRET
+
+# specify a custom output file
+poetry run xweather2epw fetch --from '2025-01-01' --to '2025-12-31' --latitude 49.4 --longitude 0.1 --api-key YOUR_KEY --api-secret YOUR_SECRET --output my_weather.epw
+```
+
+Use `--help` to have a list of available options:
+
+```bash
+poetry run xweather2epw --help
+poetry run xweather2epw fetch --help
+```
+
+## Development
+
+### Running Tests
+
+To run the test suite:
+
+```bash
+poetry run test
+```
+
+This will execute all unit tests with verbose output.
+
+## Features
+
+- **Date Range Validation**: Validates input parameters (latitude, longitude, date range)
+- **Smart Chunking**: Automatically splits requests into 15-day chunks to comply with API limits
+- **Date Range Limits**: 
+  - Maximum duration: 1 year (365 days)
+  - Forecast limit: Up to 14 days in the future
+- **Missing Data Handling**: Uses safe default values for missing weather data
+- **Unit Conversion**: Automatically converts units to comply with EPW format (SI units)
+- **EPW Header Generation**: Populates EPW headers with location information from API response
+- **Solar Radiation Data**: Extracts solar radiation data from XWeather API's `solrad` field (GHI, DNI, DHI)
+- **Sequential Processing**: Processes data chunks sequentially for reliability
+
+## Limitations
+
+- Ground/soil temperatures cannot be calculated from XWeather API data, so the `GROUND TEMPERATURES` header is set to `0`
+- Some advanced EPW fields (like extraterrestrial radiation and illuminance) are not available from the XWeather conditions endpoint and are filled with missing data indicators
+- Historical data availability depends on your XWeather API subscription
+
+## Documentation
+
+- [XWeather API Documentation](https://www.xweather.com/docs/weather-api/)
+- [XWeather Conditions Endpoint](https://www.xweather.com/docs/weather-api/endpoints/conditions)
+- [EPW Format Specification](https://designbuilder.co.uk/cahelp/Content/EnergyPlusWeatherFileFormat.htm)
+

xweather2epw-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[tool.poetry]
+name = "xweather2epw"
+version = "0.1.0"
+description = "A tool that fetches data from the XWeather API and generates EnergyPlus Weather files (EPW)"
+authors = ["Antoine Galataud <antoine@foobot.io>"]
+readme = "README.md"
+homepage = "https://github.com/airboxlab/xweather2epw"
+repository = "https://github.com/airboxlab/xweather2epw"
+keywords = ["weather", "epw", "energyplus", "xweather"]
+packages = [{include = "xweather2epw"}]
+
+[tool.poetry.dependencies]
+python = "^3.12"
+requests = "^2.31.0"
+click = "^8.1.7"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.4.0"
+pytest-cov = "^4.1.0"
+
+[tool.poetry.scripts]
+xweather2epw = "xweather2epw.cli:main"
+test = "tests.discover:run"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

xweather2epw-0.1.0/xweather2epw/__init__.py

@@ -0,0 +1,3 @@
+"""XWeather to EPW Converter package."""
+
+__version__ = "0.1.0"

xweather2epw-0.1.0/xweather2epw/api_client.py

@@ -0,0 +1,146 @@
+"""XWeather API client."""
+
+import logging
+from datetime import datetime, timedelta
+from typing import Any
+
+import requests
+
+from xweather2epw.logcfg import init_logging
+
+init_logging()
+
+
+class XWeatherClient:
+    """Client for interacting with XWeather API."""
+
+    BASE_URL = "https://data.api.xweather.com"
+    MAX_DAYS_PER_REQUEST = 15
+
+    def __init__(self, api_key: str, api_secret: str):
+        """Initialize XWeather API client.
+
+        :param api_key: XWeather API key (client_id)
+        :param api_secret: XWeather API secret (client_secret)
+        """
+        self.api_key = api_key
+        self.api_secret = api_secret
+
+    def fetch_conditions(
+        self, latitude: float, longitude: float, from_dt: datetime, to_dt: datetime
+    ) -> dict[str, Any]:
+        """Fetch weather conditions from XWeather API.
+
+        Splits the request into chunks of max 15 days to comply with API limits.
+
+        :param latitude: Latitude of location
+        :param longitude: Longitude of location
+        :param from_dt: Start datetime
+        :param to_dt: End datetime
+        :return: dict containing all weather data with metadata
+        """
+        all_periods = []
+        location_info = None
+        profile_info = None
+
+        # XWeather API treats 'to' date as exclusive, so we adjust it by adding 1 day
+        to_dt += timedelta(days=1)
+        # Split date range into chunks
+        chunks = self._split_date_range(from_dt, to_dt)
+
+        for chunk_start, chunk_end in chunks:
+            chunk_data = self._fetch_chunk(latitude, longitude, chunk_start, chunk_end)
+
+            if chunk_data and "response" in chunk_data:
+                response = chunk_data["response"]
+                if isinstance(response, list) and len(response) > 0:
+                    response = response[0]
+
+                # Get location info from first chunk
+                if location_info is None and isinstance(response, dict):
+                    if "place" in response:
+                        location_info = response["place"]
+                    if "profile" in response:
+                        profile_info = response["profile"]
+                    elif "loc" in response:
+                        # Fallback to basic location data
+                        logging.warning("Using fallback location info from 'loc' field.")
+                        location_info = {
+                            "name": "Unknown",
+                            "lat": response["loc"].get("lat", latitude),
+                            "long": response["loc"].get("long", longitude),
+                        }
+
+                # Collect periods
+                if "periods" in response:
+                    all_periods.extend(response["periods"])
+                else:
+                    raise ValueError("API response missing 'periods' data.")
+
+        return {
+            "place": location_info or {},
+            "profile": profile_info or {},
+            "periods": all_periods,
+            "loc": {"lat": latitude, "long": longitude},
+        }
+
+    def _split_date_range(
+        self, from_dt: datetime, to_dt: datetime
+    ) -> list[tuple[datetime, datetime]]:
+        """Split date range into chunks of max 15 days.
+
+        :param from_dt: Start datetime
+        :param to_dt: End datetime
+        :return: List of (start, end) datetime tuples
+        """
+        chunks = []
+        current = from_dt
+
+        while current <= to_dt:
+            chunk_end = min(current + timedelta(days=self.MAX_DAYS_PER_REQUEST - 1), to_dt)
+            chunks.append((current, chunk_end))
+            current = chunk_end + timedelta(days=1)
+
+        return chunks
+
+    def _fetch_chunk(
+        self, latitude: float, longitude: float, start_dt: datetime, end_dt: datetime
+    ) -> dict[str, Any]:
+        """Fetch a single chunk of weather data.
+
+        :param latitude: Latitude of location
+        :param longitude: Longitude of location
+        :param start_dt: Start datetime
+        :param end_dt: End datetime
+        :return: API response dictionary
+        """
+        # Format location
+        location = f"{latitude},{longitude}"
+
+        # Format date range for API
+        from_str = start_dt.strftime("%Y-%m-%d")
+        to_str = end_dt.strftime("%Y-%m-%d")
+
+        # Build URL
+        url = f"{self.BASE_URL}/conditions/{location}"
+
+        # Build parameters
+        params = {
+            "client_id": self.api_key,
+            "client_secret": self.api_secret,
+            "from": from_str,
+            "to": to_str,
+            "filter": "1hr",  # 1-hour interval data
+            "format": "json",
+        }
+
+        # Make request
+        logging.info(f"Fetching data with params: {params}")
+        response = requests.get(url, params=params, timeout=30)
+        response.raise_for_status()
+        response = response.json()
+
+        if response["success"] is False:
+            raise ValueError(f"API error: {response.get('error', 'Unknown error')}")
+
+        return response

xweather2epw-0.1.0/xweather2epw/cli.py

@@ -0,0 +1,110 @@
+"""Command line interface for xweather2epw."""
+
+import sys
+
+import click
+
+from .api_client import XWeatherClient
+from .epw_writer import EPWWriter
+from .validator import validate_inputs
+
+
+@click.group()
+@click.version_option()
+def cli():
+    """XWeather to EPW Converter - Fetch weather data and generate EPW files."""
+    pass
+
+
+@cli.command()
+@click.option(
+    "--from",
+    "from_date",
+    required=True,
+    type=str,
+    help="Start date in ISO format (YYYY-MM-DD)",
+)
+@click.option(
+    "--to",
+    "to_date",
+    required=True,
+    type=str,
+    help="End date in ISO format (YYYY-MM-DD, inclusive)",
+)
+@click.option(
+    "--latitude",
+    required=True,
+    type=float,
+    help="Latitude of the location (-90 to 90)",
+)
+@click.option(
+    "--longitude",
+    required=True,
+    type=float,
+    help="Longitude of the location (-180 to 180)",
+)
+@click.option(
+    "--api-key",
+    required=True,
+    type=str,
+    help="XWeather API key",
+)
+@click.option(
+    "--api-secret",
+    required=True,
+    type=str,
+    help="XWeather API secret",
+)
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(),
+    default=None,
+    help="Output EPW file path (default: weather_<lat>_<lon>.epw)",
+)
+def fetch(from_date, to_date, latitude, longitude, api_key, api_secret, output):
+    """Fetch weather data from XWeather API and generate an EPW file."""
+    try:
+        # Validate inputs
+        from_dt, to_dt = validate_inputs(from_date, to_date, latitude, longitude)
+
+        # Set default output filename
+        if output is None:
+            output = f"weather_{latitude}_{longitude}.epw"
+
+        click.echo(f"Fetching weather data for ({latitude}, {longitude})")
+        click.echo(f"Date range: {from_date} to {to_date}")
+
+        # Create API client
+        client = XWeatherClient(api_key, api_secret)
+
+        # Fetch weather data
+        click.echo("Fetching data from XWeather API...")
+        weather_data = client.fetch_conditions(latitude, longitude, from_dt, to_dt)
+
+        if not weather_data:
+            click.echo("Error: No weather data received from API", err=True)
+            sys.exit(1)
+
+        # Write EPW file
+        click.echo(f"Writing EPW file to {output}...")
+        writer = EPWWriter(weather_data, latitude, longitude)
+        writer.write(output)
+
+        click.echo(f"Successfully generated EPW file: {output}")
+
+    except ValueError as e:
+        click.echo(f"Validation error: {e}", err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+def main():
+    """Main entry point."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

xweather2epw-0.1.0/xweather2epw/epw_writer.py

@@ -0,0 +1,323 @@
+"""EPW file writer."""
+
+from datetime import datetime
+from typing import Any
+
+from xweather2epw.logcfg import init_logging
+
+init_logging()
+
+
+class EPWWriter:
+    """Writer for EnergyPlus Weather (EPW) files."""
+
+    # Default values for missing data as per EPW format specification
+    MISSING_TEMP = 99.9
+    MISSING_PRESSURE = 999999
+    MISSING_HUMIDITY = 999
+    MISSING_RADIATION = 9999
+    MISSING_WIND_SPEED = 999
+    MISSING_WIND_DIR = 999
+    MISSING_SKY_COVER = 99
+    MISSING_VISIBILITY = 9999
+    MISSING_CEILING = 99999
+    MISSING_PRECIP = 999
+    MISSING_SNOW = 999
+
+    def __init__(self, weather_data: dict[str, Any], latitude: float, longitude: float):
+        """Initialize EPW writer.
+
+        :param weather_data: Weather data from XWeather API
+        :param latitude: Location latitude
+        :param longitude: Location longitude
+        """
+        self.weather_data = weather_data
+        self.latitude = latitude
+        self.longitude = longitude
+
+    def write(self, output_path: str):
+        """Write EPW file.
+
+        Args:
+            output_path: Path to output EPW file
+        """
+        with open(output_path, "w", newline="\n") as f:
+            # Write headers
+            self._write_location_header(f)
+            self._write_design_conditions_header(f)
+            self._write_typical_extreme_periods_header(f)
+            self._write_ground_temperatures_header(f)
+            self._write_holidays_header(f)
+            self._write_comments_header(f)
+            self._write_data_periods_header(f)
+
+            # Write weather data
+            self._write_weather_data(f)
+
+    def _write_location_header(self, f):
+        """Write LOCATION header line."""
+        place = self.weather_data.get("place", {})
+        profile = self.weather_data.get("profile", {})
+
+        # Extract location information
+        city = place.get("name", "Unknown")
+        state = place.get("state", "")
+        country = place.get("country", "")
+
+        # Build city name
+        if state:
+            city_full = f"{city}/{state}"
+        else:
+            city_full = city
+
+        # Get timezone offset (default to 0 if not available)
+        tzoffset_sec = profile.get("tzoffset", 0) if profile else 0
+        if isinstance(tzoffset_sec, (int, float)):
+            timezone = tzoffset_sec / 3600  # Convert seconds to hours
+        else:
+            timezone = 0
+
+        # Get elevation (default to 0 if not available)
+        elevation = profile.get("elevM", 0) if profile else 0
+
+        # WMO number (not available from XWeather, use 999999)
+        wmo = 999999
+
+        # Data source
+        source = "XWeather"
+
+        f.write(
+            f"LOCATION,{city_full},{state},{country},{source},"
+            f"{wmo},{self.latitude},{self.longitude},{timezone},{elevation}\n"
+        )
+
+    def _write_design_conditions_header(self, f):
+        """Write DESIGN CONDITIONS header (empty for this implementation)."""
+        f.write("DESIGN CONDITIONS,0\n")
+
+    def _write_typical_extreme_periods_header(self, f):
+        """Write TYPICAL/EXTREME PERIODS header (empty for this implementation)."""
+        f.write("TYPICAL/EXTREME PERIODS,0\n")
+
+    def _write_ground_temperatures_header(self, f):
+        """Write GROUND TEMPERATURES header (set to 0 as per requirements)."""
+        f.write("GROUND TEMPERATURES,0\n")
+
+    def _write_holidays_header(self, f):
+        """Write HOLIDAYS/DAYLIGHT SAVINGS header (empty for this implementation)."""
+        periods = self.weather_data.get("periods", [])
+        first_period = periods[0]
+        first_date = self._parse_iso_datetime(first_period.get("dateTimeISO", ""))
+        is_leap_year = first_date.year % 4 == 0 if first_date else False
+        is_leap_year = "Yes" if is_leap_year else "No"
+        f.write(f"HOLIDAYS/DAYLIGHT SAVINGS,{is_leap_year},0,0,0\n")
+
+    def _write_comments_header(self, f):
+        """Write COMMENTS headers."""
+        f.write("COMMENTS 1,Generated by xweather2epw - XWeather to EPW Converter\n")
+        f.write("COMMENTS 2,Weather data sourced from XWeather API (https://www.xweather.com/)\n")
+
+    def _write_data_periods_header(self, f):
+        """Write DATA PERIODS header."""
+        periods = self.weather_data.get("periods", [])
+
+        if not periods:
+            # No data, write minimal header
+            f.write("DATA PERIODS,1,1,Data,Sunday,1/1,12/31\n")
+            return
+
+        # Get date range from periods
+        first_period = periods[0]
+        last_period = periods[-1]
+
+        # Parse dates
+        first_date = self._parse_iso_datetime(first_period.get("dateTimeISO", ""))
+        last_date = self._parse_iso_datetime(last_period.get("dateTimeISO", ""))
+
+        if first_date and last_date:
+            start_str = f"{first_date.month}/{first_date.day}"
+            end_str = f"{last_date.month}/{last_date.day}"
+            # Get day of week for start date (Monday=0)
+            day_of_week = [
+                "Monday",
+                "Tuesday",
+                "Wednesday",
+                "Thursday",
+                "Friday",
+                "Saturday",
+                "Sunday",
+            ][first_date.weekday()]
+        else:
+            start_str = "1/1"
+            end_str = "12/31"
+            day_of_week = "Sunday"
+
+        f.write(f"DATA PERIODS,1,1,Data,{day_of_week},{start_str},{end_str}\n")
+
+    def _write_weather_data(self, f):
+        """Write hourly weather data records."""
+        periods = self.weather_data.get("periods", [])
+
+        if not periods:
+            return
+
+        for period in periods:
+            self._write_weather_record(f, period)
+
+    def _write_weather_record(self, f, period: dict[str, Any]):
+        """Write a single weather data record.
+
+        Args:
+            f: File handle
+            period: Weather period data from API
+        """
+        # Parse timestamp
+        dt = self._parse_iso_datetime(period.get("dateTimeISO", ""))
+        if not dt:
+            return  # Skip invalid records
+
+        year = dt.year
+        month = dt.month
+        day = dt.day
+        hour = dt.hour + 1  # EPW hours are 1-24
+        minute = dt.minute if dt.minute else 0
+
+        # Data source and uncertainty flags (not used)
+        data_source_uncertainty = "9"
+
+        # Temperature data (°C)
+        dry_bulb = round(period.get("tempC", self.MISSING_TEMP), 1)
+        dew_point = round(period.get("dewpointC", self.MISSING_TEMP), 1)
+
+        # Humidity (%)
+        humidity = round(period.get("humidity", self.MISSING_HUMIDITY), 1)
+
+        # Atmospheric pressure (Pa) - XWeather provides in mb, convert to Pa
+        pressure_mb = period.get("pressureMB")
+        if pressure_mb is not None:
+            pressure = pressure_mb * 100  # mb to Pa
+        else:
+            pressure = self.MISSING_PRESSURE
+        pressure = round(pressure, 0)
+
+        # Radiation data (Wh/m²) - extract from solrad field if available
+        solrad = period.get("solrad", {})
+
+        # EPW expects Wh/m², XWeather provides W/m² (instantaneous)
+        # For hourly data, W/m² is approximately equal to Wh/m²
+        global_horizontal = solrad.get("ghiWM2", self.MISSING_RADIATION)
+        direct_normal = solrad.get("dniWM2", self.MISSING_RADIATION)
+        diffuse_horizontal = solrad.get("dhiWM2", self.MISSING_RADIATION)
+
+        # Extraterrestrial and infrared radiation not available from API
+        etr_horizontal = self.MISSING_RADIATION
+        etr_direct = self.MISSING_RADIATION
+        ir_horizontal = self.MISSING_RADIATION
+
+        # Illuminance data (lux) - using missing values
+        global_horiz_illum = self.MISSING_RADIATION
+        direct_normal_illum = self.MISSING_RADIATION
+        diffuse_horiz_illum = self.MISSING_RADIATION
+        zenith_luminance = self.MISSING_RADIATION
+
+        # Wind data
+        wind_dir = period.get("windDirDEG", self.MISSING_WIND_DIR)
+
+        # Wind speed (m/s) - XWeather provides in kph, convert to m/s
+        wind_kph = period.get("windSpeedKPH")
+        if wind_kph is not None:
+            wind_speed = wind_kph / 3.6  # kph to m/s
+        else:
+            wind_speed = self.MISSING_WIND_SPEED
+        wind_speed = round(wind_speed, 1)
+
+        # Sky cover data (tenths) - XWeather provides cloud cover in %, convert to tenths
+        cloud_cover_pct = period.get("cloudsCovered")
+        if cloud_cover_pct is not None:
+            sky_cover = int(cloud_cover_pct / 10)  # % to tenths
+        else:
+            sky_cover = self.MISSING_SKY_COVER
+
+        opaque_sky_cover = sky_cover  # Use same value for opaque cover
+
+        # Visibility (km)
+        visibility = period.get("visibilityKM", self.MISSING_VISIBILITY)
+
+        # Ceiling height (m)
+        ceiling = self.MISSING_CEILING
+
+        # Present weather observation and codes
+        weather_obs = 0
+        weather_codes = 999999999
+
+        # Precipitable water (mm)
+        precipitable_water = self.MISSING_PRECIP
+
+        # Aerosol optical depth (thousandths)
+        aerosol_optical = self.MISSING_PRECIP
+
+        # Snow depth (cm)
+        snow_depth_cm = period.get("snowDepthCM", self.MISSING_SNOW)
+
+        # Days since last snowfall
+        days_last_snow = self.MISSING_SNOW
+
+        # Albedo
+        albedo = self.MISSING_PRECIP
+
+        # Liquid precipitation (mm and hr)
+        precip_mm = period.get("precipMM")
+        if precip_mm is not None:
+            liquid_precip = precip_mm
+            liquid_precip_qty = 1  # Assume 1 hour
+        else:
+            liquid_precip = 0
+            liquid_precip_qty = 0
+
+        # Format record
+        record = (
+            f"{year},{month},{day},{hour},{minute},"
+            f"{data_source_uncertainty},"
+            f"{dry_bulb},{dew_point},{humidity},{pressure},"
+            f"{etr_horizontal},{etr_direct},{ir_horizontal},"
+            f"{global_horizontal},{direct_normal},{diffuse_horizontal},"
+            f"{global_horiz_illum},{direct_normal_illum},{diffuse_horiz_illum},{zenith_luminance},"
+            f"{wind_dir},{wind_speed},"
+            f"{sky_cover},{opaque_sky_cover},"
+            f"{visibility},{ceiling},"
+            f"{weather_obs},{weather_codes},"
+            f"{precipitable_water},{aerosol_optical},{snow_depth_cm},{days_last_snow},"
+            f"{albedo},{liquid_precip},{liquid_precip_qty}\n"
+        )
+
+        f.write(record)
+
+    def _parse_iso_datetime(self, iso_string: str) -> datetime:
+        """Parse ISO datetime string.
+
+        Args:
+            iso_string: ISO format datetime string
+
+        Returns:
+            datetime object or None if parsing fails
+        """
+        if not iso_string:
+            return None
+
+        try:
+            # Handle 'Z' timezone indicator (UTC)
+            # Note: We strip timezone info as EPW uses naive timestamps
+            if iso_string.endswith("Z"):
+                iso_string = iso_string[:-1]  # Remove 'Z'
+
+            # Try parsing with timezone info
+            # Format: "2024-02-19T18:00:00-06:00"
+            if "+" in iso_string or iso_string.count("-") > 2:
+                # Has timezone, strip it for simplicity
+                # EPW format uses local time without timezone
+                dt_part = iso_string[:19]  # Get YYYY-MM-DDTHH:MM:SS part
+                return datetime.strptime(dt_part, "%Y-%m-%dT%H:%M:%S")
+            else:
+                return datetime.strptime(iso_string, "%Y-%m-%dT%H:%M:%S")
+        except ValueError:
+            return None

xweather2epw-0.1.0/xweather2epw/logcfg.py

@@ -0,0 +1,32 @@
+import logging.config
+
+
+def init_logging(verbose: bool = False) -> None:
+    app_log_level = "INFO" if verbose else "WARNING"
+
+    logging.config.dictConfig(
+        {
+            "version": 1,
+            "disable_existing_loggers": True,
+            "formatters": {
+                "standard": {
+                    "format": (
+                        "%(asctime)s "
+                        + "[%(levelname)s]"
+                        + "[%(filename)s:%(lineno)s - %(funcName)s()]: %(message)s"
+                    )
+                },
+            },
+            "handlers": {
+                "default": {
+                    "level": "INFO",
+                    "formatter": "standard",
+                    "class": "logging.StreamHandler",
+                    "stream": "ext://sys.stdout",  # Default is stderr
+                },
+            },
+            "loggers": {
+                "": {"handlers": ["default"], "level": app_log_level},  # root logger
+            },
+        }
+    )

xweather2epw-0.1.0/xweather2epw/validator.py

@@ -0,0 +1,56 @@
+"""Input validation for xweather2epw."""
+
+from datetime import datetime, timedelta
+
+
+def validate_inputs(from_date_str, to_date_str, latitude, longitude):
+    """Validate command line inputs.
+
+    :param from_date_str: Start date string in ISO format (YYYY-MM-DD)
+    :param to_date_str: End date string in ISO format (YYYY-MM-DD)
+    :param latitude: Latitude value (-90 to 90)
+    :param longitude: Longitude value (-180 to 180)
+    :return: tuple: (from_datetime, to_datetime)
+    :raises: ValueError: If any validation fails
+    """
+    # Validate latitude
+    if not -90 <= latitude <= 90:
+        raise ValueError(f"Latitude must be between -90 and 90, got {latitude}")
+
+    # Validate longitude
+    if not -180 <= longitude <= 180:
+        raise ValueError(f"Longitude must be between -180 and 180, got {longitude}")
+
+    # Parse dates
+    try:
+        from_dt = datetime.strptime(from_date_str, "%Y-%m-%d")
+    except ValueError:
+        raise ValueError(f"Invalid from date format: {from_date_str}. Use YYYY-MM-DD")
+
+    try:
+        to_dt = datetime.strptime(to_date_str, "%Y-%m-%d")
+    except ValueError:
+        raise ValueError(f"Invalid to date format: {to_date_str}. Use YYYY-MM-DD")
+
+    # Validate date range
+    if from_dt > to_dt:
+        raise ValueError(f"Start date {from_date_str} must be before end date {to_date_str}")
+
+    # Calculate duration
+    duration = (to_dt - from_dt).days
+
+    # Check maximum duration (1 year = 365 days)
+    if duration > 365:
+        raise ValueError(f"Date range cannot exceed 365 days. Current range: {duration} days")
+
+    # Check forecast limit (14 days from now)
+    now = datetime.now()
+    max_future_date = now + timedelta(days=14)
+
+    if to_dt > max_future_date:
+        raise ValueError(
+            f"End date cannot be more than 14 days in the future. "
+            f"Maximum allowed date: {max_future_date.strftime('%Y-%m-%d')}"
+        )
+
+    return from_dt, to_dt