tephpy.io.igra
==============

.. py:module:: tephpy.io.igra

.. autoapi-nested-parse::

   Integrated Global Radiosonde Archive (IGRA) version 2 reader (spec §3.4).

   :func:`read` takes one ascent from an IGRA v2 per-station file — the
   as-distributed ``.zip`` or the extracted ``.txt``, sniffed with
   ``zipfile.is_zipfile`` rather than by suffix — parsing the fixed-width
   records per NCEI's ``igra2-data-format.txt``: pressure in Pa, temperature
   and dewpoint depression in tenths of °C, wind in degrees and tenths of
   m s⁻¹, with the missing-value sentinels reading as NaN and dewpoint
   derived as temperature minus depression. Unreadable, malformed, or
   ambiguous input raises :class:`~tephpy.exceptions.TephpyIOError`; the
   returned sounding passes the ordinary ingest validation (spec §6).

   ..
       !! processed by numpydoc !!


Functions
---------

.. autoapisummary::

   tephpy.io.igra.read


Module Contents
---------------

.. py:function:: read(path: str | os.PathLike[str], *, time: datetime.datetime | str | None = None) -> tephpy.sounding.Sounding

   
   Read one sounding from an IGRA v2 per-station file.


   :Parameters:

       **path** : :class:`python:str` or :obj:`os.PathLike`
           The station file: the as-distributed ``.zip`` or the extracted
           ``.txt``.

       **time** : :obj:`datetime.datetime` or :class:`python:str`, optional
           The nominal launch time selecting the ascent; a string is read
           with :meth:`datetime.datetime.fromisoformat`, and a naive value
           is read as UTC. May be omitted only when the file holds exactly
           one sounding (trimmed research subsets, fixtures).



   :Returns:

       :obj:`Sounding <tephpy.sounding.Sounding>`
           The validated sounding, with the IGRA station identifier and
           the nominal time as metadata.




   :Raises:

       :obj:`TephpyIOError <tephpy.exceptions.TephpyIOError>`
           For an unreadable or malformed file, a `time` matching no
           ascent (the nearest nominal times are reported, when the file
           records any), or an ambiguous read — several soundings with no
           ``time=`` selector (the file's count and span are reported).

       :obj:`TypeError`
           If `time` is neither a datetime nor a string.

       :obj:`ValueError`
           If a `time` string is not ISO 8601.







   ..
       !! processed by numpydoc !!