Metadata-Version: 1.1
Name: buoyant
Version: 0.5.2
Summary: Wrapper for the NOAA National Data Buoy Center
Home-page: https://github.com/fitnr/buoyant
Author: Neil Freeman
Author-email: contact@fakeisthenewreal.org
License: GPL
Description-Content-Type: UNKNOWN
Description: Buoyant
        -------
        
        Buoyant is a Python wrapper for grabbing buoy data from the `National
        Buoy Data Center <http://www.ndbc.noaa.gov>`__. It parses XML from a
        NBDC endpoint. This data source isn't fully documented, so there's no
        guarantee of its stability.
        
        The NBDC provides a `list <http://www.ndbc.noaa.gov/to_station.shtml>`__
        and a `map <http://www.ndbc.noaa.gov/obs.shtml>`__ of active buoys.
        
        Hello buoy example:
        
        .. code:: python
        
            from buoyant import Buoy
        
            # construct the Buoy object with the station ID
            # It's an alphanumeric code. If its numeric, an integer works fine.
            station = Buoy(13010)
        
            station.name
            # 'Soul'
            # Yes, that buoy is really named Soul.
        
        More examples:
        
        .. code:: python
        
            from buoyant import Buoy
        
            station = Buoy('lndc1')
        
            station.wind_speed
            # 9.9
        
            station.units['wind_speed']
            # 'kt'
        
            station.lon
            # -23.14
        
            station.coords
            # (20.43, -23.14)
        
            # Get the time the measurements were made.
            station.datetime
            # datetime.datetime(2014, 12, 15, 20, 50, tzinfo=<UTC>)
        
            # Not all stations report all data.
            station.wave_height
            # raises AttributeError
        
            # Fetches new data. This isn't very useful, since the buoys update only every hour or so
            station.refresh()
        
        Images
        ~~~~~~
        
        Some buoys have cameras! If the buoy doesn't have an active camera, a
        placeholder image provided by the NBDC will be returned.
        
        .. code:: python
        
            station = Buoy(41009)
        
            station.image_url
            # 'http://www.ndbc.noaa.gov/images/buoycam/Z14C_2014_11_01_2200.jpg'
        
            # Save image as a file 'out.jpg'
            station.write_image('out.jpg')
        
            # Get raw image as a BytesIO object (see https://docs.python.org/2/library/io.html)
            station.image
            # <_io.BytesIO object>
        
            station.url
            # 'http://www.ndbc.noaa.gov/station_page.php?station=41009'
        
        Measurement metadata
        ~~~~~~~~~~~~~~~~~~~~
        
        The occassional buoy reports metadata about its measurements. The
        ``Buoy`` object has a meta attribute with this data, if any.
        
        .. code:: python
        
            # Buoy in the Frying Pan Shoals, NC
            frying_pan = Buoy(41013)
        
            frying_pan.pressure
            # 30.1
        
            frying_pan.meta['pressure']
            # {'tendency': 'steady'}
        
        No data
        ~~~~~~~
        
        Sometimes buoys don't have recent data. You'll be able to tell two ways.
        First, the ``Buoy`` object won't have many attributes. Second, there
        will be a message. It will say 'No data'.
        
        .. code:: python
        
            station = Buoy('ANRN6')
            station.message
            # 'No data'
        
        Measurements included
        ~~~~~~~~~~~~~~~~~~~~~
        
        Any measurements reported in the NBDC's XML api are included in a
        ``Buoy`` object. `Read about the meaning of the different
        measurements <http://www.ndbc.noaa.gov/measdes.shtml>`__.
        
        Measurements often included (the text in parentheses is the one used on
        the NBDC's `measurement descriptions
        page <http://www.ndbc.noaa.gov/measdes.shtml>`__):
        
        -  air\_temp (ATMP)
        -  average\_period (APD)
        -  dominant\_period (DPD)
        -  mean\_wave\_direction (Spectral wave direction)
        -  water\_temp (WTMP)
        -  wave\_height (WVHT)
        -  wind\_direction (WDIR)
        -  wind\_gust (GST)
        -  wind\_speed (WSPD)
        -  datetime
        -  dewpoint (DEWP)
        -  lat (latitude)
        -  lon (longitude)
        -  pressure (PRES)
        
        Water quality data isn't included in the XML data source. Neither is the
        elevation of the station or the location of the instruments relative to
        the station.
        
        XML
        ~~~
        
        Get the raw XML, if you like XML for some reason. Maybe the package is
        missing something? If so, submit an
        `issue <https://github.com/fitnr/buoyant/issues>`__ or `pull
        request <https://github.com/fitnr/buoyant/pulls>`__!
        
        .. code:: python
        
            soul = Buoy('13010')
            soul.xml
            '''<?xml version="1.0" encoding="UTF-8"?>
            <observation id="13010" name="Soul" lat="-0.01" lon="0.00">
              <datetime>2014-12-16T02:00:00UTC</datetime>
              <winddir uom="degT">190</winddir>
              <windspeed uom="kt">9.9</windspeed>
              <airtemp uom="F">78.8</airtemp>
              </observation>'''
        
        Compatibility
        ~~~~~~~~~~~~~
        
        Buoyant is compatible with Python 2 and 3.
        
        License
        ~~~~~~~
        
        Buoyant is licensed under the
        `GPL <http://www.gnu.org/licenses/#GPL>`__.
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Intended Audience :: Science/Research
