Productstatus REST API Python client
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples
productstatus
.arclint
.gitignore
LICENSE
README.md
setup.py

README.md

python-productstatus-client

Abstract

This is a Python module used to access a Productstatus REST API server.

The Productstatus code can be found on Github.

Setting up a development environment

mkvirtualenv python-productstatus-client
python setup.py develop

Building for pypi

python setup.py sdist bdist_wheel
twine upload dist/*

Examples of use

Load your virtualenv and run the example scripts in the examples/ directory.

Running unit tests

source deps/bin/activate
nosetests

Making requests

Import the module productstatus.api, and instantiate an Api object. You are now ready to use the Productstatus server.

import productstatus.api

# username and api key is only needed for write access
api = productstatus.api.Api('https://productstatus.fqdn', username='foo', api_key='bar')

REST API resource collections (e.g. /api/v1/product/) can be accessed as objects directly underneath the Api object. REST API resources (e.g. /api/v1/product/f314a536-bb96-4d2a-83cd-9764e2e3e16a/) can be accessed using indexing:

product = api.product['f314a536-bb96-4d2a-83cd-9764e2e3e16a']
print(product.name)  # 'AROME MetCoOp 2500m'

Foreign keys on resources are automatically resolved into objects:

print(product.institution.name)  # 'MET Norway'

You can run filtering queries to find the object you are looking for:

productinstances = api.productinstance.objects
productinstances.filter(product=product, reference_time=datetime.datetime(2015, 1, 1))
productinstances.order_by('-version')
productinstances.limit(2)
print(productinstances.count())  # 2
productinstance = productinstances[0]
print(productinstance.product.resource_uri == product.resource_uri)  # True

Creating new objects are done using the resource collection:

new_productinstance = api.productinstance.create()
new_productinstance.reference_time = datetime.datetime.now()
new_productinstance.product = product
new_productinstance.save()
print(new_productinstance.id)  # '4560279d-ef3e-49ae-bf2e-0dabac1b9e74'

You can also edit an existing object:

productinstance.reference_time += datetime.timedelta(seconds=1)
productinstance.save()

Lastly, you can access the schema to get an idea of how the data model looks like:

print(api.productinstance.schema)  # { 'huge': 'dictionary' }

Command-line utility

The Productstatus client ships with a handy "swiss army knife" that enables you to read and write remote objects from the command line.

Some examples of usage follow. Below, we create a new service backend object:

$ python productstatus/cli.py \
    --username X \
    --api_key Y \
    http://localhost:8000 \
    servicebackend create \
    --name /dev/null \
    --documentation_url 'https://example.com'
{
    "created": "2015-11-10T17:35:17+0000",
    "documentation_url": "https://example.com",
    "id": "013f06f9-8cf3-4123-94b1-4206b2807cbd",
    "modified": "2015-11-10T17:35:17+0000",
    "name": "/dev/null",
    "resource_uri": "/api/v1/servicebackend/013f06f9-8cf3-4123-94b1-4206b2807cbd/"
}

Searching by specific parameters. If you omit the parameters, all results will be returned.

$ python productstatus/cli.py http://localhost:8000 productinstance search --reference_time 2015-01-01T12:00:00Z --product 8efab026-434e-4baf-b8ed-d921a1b0b427
[
    {
        "created": "2015-11-10T17:27:13+0000",
        "id": "1ddb75c9-d5b4-49a8-9c27-79a47dd396b5",
        "product": "/api/v1/product/8efab026-434e-4baf-b8ed-d921a1b0b427/",
        "modified": "2015-11-10T17:27:13+0000",
        "reference_time": "2015-01-01T12:00:00+0000",
        "resource_uri": "/api/v1/productinstance/1ddb75c9-d5b4-49a8-9c27-79a47dd396b5/",
        "version": 1
    },
    {
        "created": "2015-11-10T17:27:20+0000",
        "id": "3789bc4b-eeb1-488b-96df-a1b2e680bf27",
        "product": "/api/v1/product/8efab026-434e-4baf-b8ed-d921a1b0b427/",
        "modified": "2015-11-10T17:27:20+0000",
        "reference_time": "2015-01-01T12:00:00+0000",
        "resource_uri": "/api/v1/productinstance/3789bc4b-eeb1-488b-96df-a1b2e680bf27/",
        "version": 2
    }
]

Requesting a specific resource item:

$ python productstatus/cli.py http://localhost:8000 product get 8efab026-434e-4baf-b8ed-d921a1b0b427
{
    "bounding_box": "0,0,0,0",
    "contact": "/api/v1/person/8e547c76-6639-450d-a077-5dbcabeb3581/",
    "created": "2015-11-05T11:32:59+0000",
    "grib_center": "ecmf",
    "grib_generating_process_id": "145",
    "grid_resolution": "4000.00000",
    "grid_resolution_unit": "m",
    "id": "8efab026-434e-4baf-b8ed-d921a1b0b427",
    "institution": "/api/v1/institution/a5eb5df1-704c-4450-a7a4-388f7e54c496/",
    "modified": "2015-11-10T11:37:58+0000",
    "name": "Nordic",
    "parent": null,
    "prognosis_length": 60,
    "projection": "/api/v1/projection/c2b3d081-bb4d-4dea-975b-0126bdab6691/",
    "resource_uri": "/api/v1/product/8efab026-434e-4baf-b8ed-d921a1b0b427/",
    "time_steps": 60,
    "wdb_data_provider": "nordic_roms"
}

Exit codes

See cli.py code for the mapping between exceptions and various exit codes.

Listening for Productstatus message queue events

The event listener is asynchronous, and will queue incoming messages until you fetch them with get_next_event().

See examples/events.py

import productstatus.api
import productstatus.exceptions

import json

api = productstatus.api.Api(
    'https://productstatus.met.no'
)

# You can easily set up an event listener using the API client. The default operation is to block
# until an event is received, or you can specify a timeout in the constructor.
event_listener = api.get_event_listener()

print('Listening for events...')
print()

# Loop through received events.
while True:
    try:
        event = event_listener.get_next_event()
    except productstatus.exceptions.EventTimeoutException:
        pass
    print(json.dumps(event, indent=4))
    print()

    if event.type == 'heartbeat':
        print('Received heartbeat with timestamp', event.message_timestamp)
    elif event.type == 'resource':
        print('Received resource of type', event.resource)
        if event.resource == 'datainstance':
            datainstance = api[event.uri]
            print('DataInstance URL:', datainstance.url)
            print('DataInstance product name:', datainstance.data.productinstance.product.name)
            print('DataInstance product slug:', datainstance.data.productinstance.product.slug)

    print()