voxcity.utils.weather
=====================

.. py:module:: voxcity.utils.weather

.. autoapi-nested-parse::

   Weather utilities subpackage.

   Public API:
   - safe_rename, safe_extract
   - process_epw, read_epw_for_solar_simulation
   - get_nearest_epw_from_climate_onebuilding

   This package was introduced to split a previously monolithic module into
   cohesive submodules. Backwards-compatible imports are preserved: importing
   from `voxcity.utils.weather` continues to work.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/voxcity/utils/weather/epw/index
   /autoapi/voxcity/utils/weather/files/index
   /autoapi/voxcity/utils/weather/onebuilding/index


Functions
---------

.. autoapisummary::

   voxcity.utils.weather.safe_rename
   voxcity.utils.weather.safe_extract
   voxcity.utils.weather.process_epw
   voxcity.utils.weather.read_epw_for_solar_simulation
   voxcity.utils.weather.get_nearest_epw_from_climate_onebuilding


Package Contents
----------------

.. py:function:: safe_rename(src: pathlib.Path, dst: pathlib.Path) -> pathlib.Path

   Safely rename a file, handling existing files by adding a number suffix.


.. py:function:: safe_extract(zip_ref: zipfile.ZipFile, filename: str, extract_dir: pathlib.Path) -> pathlib.Path

   Safely extract a file from zip, handling existing files.


.. py:function:: process_epw(epw_path: Union[str, pathlib.Path]) -> Tuple[pandas.DataFrame, dict]

   Process an EPW file into a pandas DataFrame and header metadata.


.. py:function:: read_epw_for_solar_simulation(epw_file_path)

   Read EPW file specifically for solar simulation purposes.
   Returns (df[DNI,DHI], lon, lat, tz, elevation_m).


.. py:function:: get_nearest_epw_from_climate_onebuilding(longitude: float, latitude: float, output_dir: str = './', max_distance: Optional[float] = None, extract_zip: bool = True, load_data: bool = True, region: Optional[Union[str, List[str]]] = None, allow_insecure_ssl: bool = False, allow_http_fallback: bool = False, ssl_verify: Union[bool, str] = True) -> Tuple[Optional[str], Optional[pandas.DataFrame], Optional[Dict]]

   Download and process EPW weather file from Climate.OneBuilding.Org based on coordinates.