# pyoscar
Pythonic API to WMO OSCAR
[](https://github.com/wmo-cop/pyoscar/actions)
# Overview
pyoscar provides a Pythonic API atop the WMO [OSCAR](https://oscar.wmo.int/surface/index.html) HTTP API.
## For R enthusiasts
For those interested in using R, the [oscarr](https://github.com/oousmane/oscarr) project provides an R wrapper to the pyoscar Python module for the R community.
# Installation
## Requirements
- Python 3
- [virtualenv](https://virtualenv.pypa.io/) or [Conda](https://docs.conda.io)
### Dependencies
Dependencies are listed in [requirements.txt](requirements.txt). Dependencies
are automatically installed during pyoscar installation.
## Installing pyoscar
### For users
To install the latest stable version:
```bash
pip3 install pyoscar
```
To keep up to date with stable updates:
```bash
pip3 install pyoscar -U
```
### For developers
```bash
# 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
```bash
# 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 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
```python
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
```bash
# 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
```bash
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](https://www.python.org/dev/peps/pep-0008)
### Bugs and Issues
All bugs, enhancements and issues are managed on [GitHub](https://github.com/wmo-cop/pyoscar/issues).
## Contact
* [Tom Kralidis](https://github.com/tomkralidis)
Raw data
{
"_id": null,
"home_page": "https://github.com/wmo-cop/pyoscar",
"name": "pyoscar",
"maintainer": "Meteorological Service of Canada",
"docs_url": null,
"requires_python": null,
"maintainer_email": "tomkralidis@gmail.com",
"keywords": "wmo oscar wigos station metadata gawsis",
"author": "Meteorological Service of Canada",
"author_email": "tomkralidis@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e9/d8/87bb6d87c44f869dc9578110dabe39a172ca876b5d8628552bd01225136e/pyoscar-0.8.0.tar.gz",
"platform": "all",
"description": "# pyoscar\n\nPythonic API to WMO OSCAR\n\n[](https://github.com/wmo-cop/pyoscar/actions)\n\n# Overview\n\npyoscar provides a Pythonic API atop the WMO [OSCAR](https://oscar.wmo.int/surface/index.html) HTTP API.\n\n## For R enthusiasts\n\nFor those interested in using R, the [oscarr](https://github.com/oousmane/oscarr) project provides an R wrapper to the pyoscar Python module for the R community.\n# Installation\n\n## Requirements\n- Python 3\n- [virtualenv](https://virtualenv.pypa.io/) or [Conda](https://docs.conda.io)\n\n### Dependencies\nDependencies are listed in [requirements.txt](requirements.txt). Dependencies\nare automatically installed during pyoscar installation.\n\n## Installing pyoscar\n\n### For users\n\nTo install the latest stable version:\n\n```bash\npip3 install pyoscar\n```\n\nTo keep up to date with stable updates:\n\n```bash\npip3 install pyoscar -U\n```\n\n### For developers\n\n```bash\n# setup virtualenv\npython3 -m venv pyoscar\ncd pyoscar\nsource bin/activate\n\n# clone codebase and install\ngit clone https://github.com/wmo-cop/pyoscar.git\ncd pyoscar\npython3 setup.py build\npython3 setup.py install\n```\n\n## Running pyoscar via the Command Line\n\n```bash\n# help\npyoscar --help\n\n# get version\npyoscar --version\n\n# all subcommands support the following options:\n# --env (depl or prod, default depl)\n# --verbosity (ERROR, WARNING, INFO, DEBUG, default NONE)\n\n# get all station identifiers\npyoscar stations\n\n# get all station identifiers by country\npyoscar stations --country=CAN\n\n# get all station identifiers by program affiliation\npyoscar stations --program=GAW\n\n# get a single station by WIGOS identifier\npyoscar station 0-20000-0-71151\n\n# get a single station by WIGOS identifier in summary mode\npyoscar station 0-20000-0-71151 --summary\n\n# get a single station by WIGOS identifier in WIGOS XML format\npyoscar station 0-20000-0-71151 --format=XML\n\n# get a single station by WIGOS identifier in WIGOS XML format in summary mode\npyoscar station 0-20000-0-71151 --format=XML --summary\n\n# add verbose mode (ERROR, WARNING, INFO, DEBUG)\npyoscar station 0-20000-0-71151 --verbosity=DEBUG\n\n# get contact by country\npyoscar contact -c Canada\n\n# get contact by surname\npyoscar contact -s Karn\n\n# get contact by organization\npyoscar contact -o \"Environment Canada\"\n\n# upload WMDR XML (to production environment)\npyoscar upload -x /path/to/wmdr.xml -at API_TOKEN -e prod\n\n# upload WMDR XML (to production environment) and save results to file\npyoscar upload -x /path/to/wmdr.xml -at API_TOKEN -e prod -l results.log\n\n# use only GML ids is TRUE by default; use --no-gml-ids to set to FALSE\npyoscar upload -x /path/to/wmdr.xml -at API_TOKEN -e prod -l results.log --no-gml-ids\n\n# harvest all records\npyoscar harvest --env=prod --directory=/path/to/dir\n```\n\n## Using the pyoscar API\n\n```python\nfrom pyoscar import OSCARClient\n\nclient = OSCARClient()\n\n# get all Canadian stations\nstations = client.get_stations(country='CAN')\n\n# get all Canadian stations\nstations = client.get_stations(program='GAW')\n\n# get invididual station report\nstn_leo = client.get_station_report('0-20000-0-71758')\n\n# get invididual station report in summary mode\nstn_leo = client.get_station_report('0-20000-0-71758', summary=True)\n\n# upload WMDR XML\n\n## instantiate client to OSCAR DEPL (default)\nclient = OSCARClient(api_token='foo')\n\n## ...or to OSCAR production\nclient = OSCARClient(api_token='foo', env='prod')\n\nwith open('some-wmdr-file.xml') as fh:\n data = fh.read()\n\nresponse = client.upload(data)\n```\n\n## Development\n\n### Running Tests\n\n```bash\n# install dev requirements\npip3 install -r requirements-dev.txt\n\n# run tests like this:\ncd tests\npython3 run_tests.py\n\n# or like this:\npython3 setup.py test\n\n# measure code coverage\ncoverage run --source pyoscar setup.py test\ncoverage report -m\n```\n\n# Releasing\n```bash\ncreate release (x.y.z is the release version)\nvi pyoscar/__init__.py # update __version__\ngit commit -am 'update release version x.y.z'\ngit push origin master\ngit tag -a x.y.z -m 'tagging release version x.y.z'\ngit push --tags\n\n# upload to PyPI\nrm -fr build dist *.egg-info\npython3 setup.py sdist bdist_wheel --universal\ntwine upload dist/*\n\n# publish release on GitHub (https://github.com/wmo-cop/pyoscar/releases/new)\n\n# bump version back to dev\nvi pyoscar/__init__.py # update __version__\ngit commit -am 'back to dev'\ngit push origin master\n```\n\n### Code Conventions\n\n* [PEP8](https://www.python.org/dev/peps/pep-0008)\n\n### Bugs and Issues\n\nAll bugs, enhancements and issues are managed on [GitHub](https://github.com/wmo-cop/pyoscar/issues).\n\n## Contact\n\n* [Tom Kralidis](https://github.com/tomkralidis)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pythonic API to WMO OSCAR Web Services",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/wmo-cop/pyoscar"
},
"split_keywords": [
"wmo",
"oscar",
"wigos",
"station",
"metadata",
"gawsis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "24c30f62ed2ce07367933c8448542ca21a6ea587bf32aec686fc5a1fa0b793b8",
"md5": "d021eb993ef5552daeed9a1a28f807be",
"sha256": "25f8317e6ce39cbca41bb1e5b0231e8ccc234f1e29caa24cf1682c44ace5516b"
},
"downloads": -1,
"filename": "pyoscar-0.8.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "d021eb993ef5552daeed9a1a28f807be",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 11086,
"upload_time": "2024-09-25T02:05:59",
"upload_time_iso_8601": "2024-09-25T02:05:59.455165Z",
"url": "https://files.pythonhosted.org/packages/24/c3/0f62ed2ce07367933c8448542ca21a6ea587bf32aec686fc5a1fa0b793b8/pyoscar-0.8.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e9d887bb6d87c44f869dc9578110dabe39a172ca876b5d8628552bd01225136e",
"md5": "39efd19c8311be9273437b006a8e654d",
"sha256": "1a023b52b6d6d1ed3d8b9a7171dd13d9099499ecfdd021b01ba14ac14959e9a4"
},
"downloads": -1,
"filename": "pyoscar-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "39efd19c8311be9273437b006a8e654d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11851,
"upload_time": "2024-09-25T02:06:00",
"upload_time_iso_8601": "2024-09-25T02:06:00.925826Z",
"url": "https://files.pythonhosted.org/packages/e9/d8/87bb6d87c44f869dc9578110dabe39a172ca876b5d8628552bd01225136e/pyoscar-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-25 02:06:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wmo-cop",
"github_project": "pyoscar",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "beautifulsoup4",
"specs": []
},
{
"name": "click",
"specs": []
},
{
"name": "lxml",
"specs": []
},
{
"name": "requests",
"specs": []
}
],
"lcname": "pyoscar"
}
JSON
