aurorawatchuk¶

class aurorawatchuk.AuroraWatchUK(base_url='http://aurorawatch-api.lancs.ac.uk/0.2/', lang='en', raise_=True, unknown_status_color='#777777', preemptive=False)¶

Class from which the current and recent AuroraWatch UK status, activity and descriptions can be obtained.

The AuroraWatchUK class handles all network traffic with the AuroraWatch UK web service and automatically updates as information fetched expires. For time-critical applications where network delays are undesirable (for example the cameralogger module) preemptive updates can be requested; if enabled a background thread will initiate an update shortly before the expiry time is reached.

Be aware that updates can occur at any time, and may occur between calls for related information. Consider using the snapshot version of this class, snapshot.AuroraWatchUK_SS which also features lazy evaluation and will make network calls only if required.

When the object is constructed base_url may be used to adjust the base URL of the AuroraWatch UK API, for instance to select between HTTP and HTTPS transport. The language used for descriptions, messages etc. can be selected with the lang parameter; only lang='en' is supported at present.

By default exceptions are raised when the status, activity or descriptions cannot be fetched from AuroraWatch UK. In some limited cases unknown values can be returned instead of exceptions (primarily when such information may be included in formatted strings). Call the constructor with raise_=False to avoid exceptions, note the trailing underscore to avoid collision with the raise keyword. When the status is unknown the value retrieved from status_color returned can be set with the unknown_status_color keyword.

activity¶

The current activity object. Type Activity.

If the current activity cannot be obtained accessing this property will generate an exception, regardless of the constructor parameter raise_.

descriptions¶

Descriptions and meanings used in the AuroraWatch UK API. Type collections.OrderedDict.

If the current activity cannot be obtained accessing this property will generate an exception, regardless of the constructor parameter raise_.

lang¶: Retrieves the selected language for messages, descriptions etc. from the API Type str.

status¶

Retrieves the current status object. Type Status.

If the current status cannot be obtained accessing this property will generate an exception, regardless of the constructor parameter raise_.

status_color¶

Retrieves the current status color as a RGB string. Type str.

If the AuroraWatchUK object was created with raise_=True then accessing this property will generate an exception if the current status cannot be obtained. However if it was created with raise_=False then unknown_status_color will be returned if the current status cannot be determined.

status_description¶

Retrieves the description for the current alert status. Type str.

If the AuroraWatchUK object was created with raise_=True then accessing this property will generate an exception if the current description cannot be obtained. However if it was created with raise_=False then 'Unknown' will be returned.

Status descriptions are not terminated with a full stop.

status_level¶

Retrieves the current status level. Type str.

If the AuroraWatchUK object was created with raise=True then accessing this property will: generate an exception if the current status cannot be obtained. However if it was created with raise_=False then the status level will be returned as unknown if the current status cannot be determined.

status_meaning¶

The meaning of the current alert status. Type str.

If the AuroraWatchUK object was created with raise_=True then accessing this property will generate an exception if the current description cannot be obtained. However if it was created with raise_=False then 'Unknown.' will be returned.

The status meanings are terminated with a full stop.

class aurorawatchuk.snapshot.AuroraWatchUK_SS(*args, **kwargs)¶

Take a snapshot of the AuroraWatch UK status.

This class mimics the behaviour of the aurorawatchuk.AuroraWatchUK class but its fields are evaluated just once and cached, at the time first requested. Thus the values it returns are snapshots of the status, activity and description fields. This is useful when the information may be required multiple times as it avoids the possibility that the value could change between uses. If the information is not required then no network traffic is generated.

For documentation see aurorawatchuk.AuroraWatchUK.

class aurorawatchuk.Activity(expires, thresholds, updated, activity_values, messages)¶

Current and recent AuroraWatch UK activity values.

If only a minimal set of information is required (current status level and messages) then the Status class should be preferred over this class as the network transfers are smaller.

all¶: Retrieves all activity values. Type list of ActivityValue objects.

expires¶: Retrieves the expiry time, as seconds since epoch. Type float.

latest¶: Retrieves the latest activity value available. Type ActivityValue.

messages¶

Retrieves a list of currently active messages. Type Message or None.

The list of messages may be empty.

thresholds¶

Retrieves the lower thresholds for each activity level. Type collections.OrderedDict.

The lower thresholds are given in units of nanotesla (nT). The activity must equal or exceed the lower threshold, and not equal or exceed the lower threshold of the next status level.

updated¶: Retrieves the time the status was last updated. Type datetime.datetime.

class aurorawatchuk.ActivityValue(level, datetime, value)¶

A single AuroraWatch UK activity value.

datetime¶: Retrieves the start time for the hourly activity value. Type datetime.datetime.

level¶: Retrieves the status level. Type str.

value¶

Retrieves the activity value, in units of nanotesla (nT). Type float.

The activity value is an unsigned scalar value.

class aurorawatchuk.Message(id_, priority, description, url, expires)¶

An AuroraWatch UK message.

description¶: Retrieves the descriptive text of the message, in the selected language. Type str.

expires¶

Retrieves the date and time the message expires. Type datetime.datetime.

After the expiry time the message should not be displayed and any saved references (for instance recording that the message has been shown to the user) can be discarded.

id¶

Retrieves a unique identifier for the message. Type str.

The identifier can be used to record which messages have been presented to a user and to hide any which have been seen previously.

priority¶

Retrieves the priority level for a message. Type str.

The priority indicates what action, if any, may be appropriate. A 'high' priority suggests that an alerting notification may be appropriate while a 'low' priority suggests a silent notification may be more appropriate. Test messages are indicated with the priority 'test'. Messages with unknown priorities should be ignored.

url¶

Retrieves an optional URL for the message. Type str or None.

The URL associated with the message, if one is present, otherwise None.

class aurorawatchuk.Status(expires, level, updated, messages)¶

AuroraWatch UK current status.

If only a minimal set of information is required (status level and messages) this class should be preferred over the Activity class as the network transfers are smaller.

expires¶: Retrieves the expiry time, as seconds since epoch. Type float.

level¶: Retrieves the current status level. Type str.

messages¶

Retrieves a list of currently active messages. Type Message or None.

The list of messages may be empty.

updated¶: Retrieves the time status was last updated. Type datetime.datetime.

aurorawatchuk¶

Indices and tables¶