pyoscar 0.9.0

Pythonic API to WMO OSCAR Web Services

pyoscar

Pythonic API to WMO OSCAR

Overview

pyoscar provides a Pythonic API atop the WMO OSCAR HTTP API.

For R enthusiasts

For those interested in using R, the oscarr project provides an R wrapper to the pyoscar Python module for the R community.

Installation

Requirements

• Python 3
• virtualenv or Conda

Dependencies

Dependencies are listed in requirements.txt. Dependencies are automatically installed during pyoscar installation.

Installing pyoscar

For users

To install the latest stable version:

pip3 install pyoscar

To keep up to date with stable updates:

pip3 install pyoscar -U

For developers

# setup virtualenv
python3 -m venv pyoscar
cd pyoscar
source bin/activate

# clone codebase and install
git clone https://github.com/wmo-cop/pyoscar.git
cd pyoscar
python3 setup.py build
python3 setup.py install

Running pyoscar via the Command Line

# help
pyoscar --help

# get version
pyoscar --version

# all subcommands support the following options:
# --env (depl or prod, default depl)
# --verbosity (ERROR, WARNING, INFO, DEBUG, default NONE)

# get all station identifiers
pyoscar stations

# get all station identifiers by country
pyoscar stations --country=CAN

# get all station identifiers by program affiliation
pyoscar stations --program=GAW

# get all stations by station name (partial names are supported)
pyoscar stations --station-name toronto

# get a single station by WIGOS identifier
pyoscar station 0-20000-0-71151

# get a single station by WIGOS identifier in summary mode
pyoscar station 0-20000-0-71151 --summary

# get a single station by WIGOS identifier in WIGOS XML format
pyoscar station 0-20000-0-71151 --format=XML

# get a single station by WIGOS identifier in WIGOS XML format in summary mode
pyoscar station 0-20000-0-71151 --format=XML --summary

# add verbose mode (ERROR, WARNING, INFO, DEBUG)
pyoscar station 0-20000-0-71151 --verbosity=DEBUG

# get contact by country
pyoscar contact -c Canada

# get contact by surname
pyoscar contact -s Karn

# get contact by organization
pyoscar contact -o "Environment Canada"

# upload WMDR XML (to production environment)
pyoscar upload -x /path/to/wmdr.xml -at API_TOKEN -e prod

# upload WMDR XML (to production environment) and save results to file
pyoscar upload -x /path/to/wmdr.xml -at API_TOKEN -e prod -l results.log

# use only GML ids is TRUE by default; use --no-gml-ids to set to FALSE
pyoscar upload -x /path/to/wmdr.xml -at API_TOKEN -e prod -l results.log --no-gml-ids

# harvest all records
pyoscar harvest --env=prod --directory=/path/to/dir

Using the pyoscar API

from pyoscar import OSCARClient

client = OSCARClient()

# get all Canadian stations
stations = client.get_stations(country='CAN')

# get all Canadian stations
stations = client.get_stations(program='GAW')

# get invididual station report
stn_leo = client.get_station_report('0-20000-0-71758')

# get invididual station report in summary mode
stn_leo = client.get_station_report('0-20000-0-71758', summary=True)

# upload WMDR XML

## instantiate client to OSCAR DEPL (default)
client = OSCARClient(api_token='foo')

## ...or to OSCAR production
client = OSCARClient(api_token='foo', env='prod')

with open('some-wmdr-file.xml') as fh:
    data = fh.read()

response = client.upload(data)

Development

Running Tests

# install dev requirements
pip3 install -r requirements-dev.txt

# run tests like this:
cd tests
python3 run_tests.py

# or like this:
python3 setup.py test

# measure code coverage
coverage run --source pyoscar setup.py test
coverage report -m

Releasing

create release (x.y.z is the release version)
vi pyoscar/__init__.py  # update __version__
git commit -am 'update release version x.y.z'
git push origin master
git tag -a x.y.z -m 'tagging release version x.y.z'
git push --tags

# upload to PyPI
rm -fr build dist *.egg-info
python3 setup.py sdist bdist_wheel --universal
twine upload dist/*

# publish release on GitHub (https://github.com/wmo-cop/pyoscar/releases/new)

# bump version back to dev
vi pyoscar/__init__.py  # update __version__
git commit -am 'back to dev'
git push origin master

Code Conventions

• PEP8

Bugs and Issues

All bugs, enhancements and issues are managed on GitHub.

Contact

• Tom Kralidis