pywws.service

Base classes for “service” uploaders.

Functions

main(class_[, argv])

Classes

CatchupDataService(context[, check_params])
DataServiceBase(context[, check_params])	Base class for “data” services.
FileService(context[, check_params])	Base class for “file” services.
LiveDataService(context[, check_params])
Queue(start, *arg, **kw)
ServiceBase(context[, check_params])	Base class for all service uploaders.

class pywws.service.Queue(start, *arg, **kw)

Bases: collections.deque

append(x)

Add an element to the right side of the deque.

full()

Are there already too many uploads on the queue.

class pywws.service.ServiceBase(context, check_params=True)

Bases: threading.Thread

Base class for all service uploaders.

Uploaders use a separate thread to allow the main program thread to continue even if a service is slow to respond. Items to upload are passed to the thread via a thread safe queue. The thread is started when the first item is put on the queue. To shut down the thread put None on the queue, e.g. by calling stop().

There are two types of uploader derived from this class. DataServiceBase is used by uploaders that send defined sets of data, typically as an HTML “post” or “get” operation. FileService is used to upload files, including free form text such as a Twitter message.

All service classes must provide a logger object so that logging messages carry the right module name, and define a service_name string. They must also define a session() method.

config = {}

Defines the user configuration of the uploader. Each item must be of the form name: (default (str), required (bool), fixed_key (str or None)). name is the weather.ini value name, default is a default value, required defines whether a value must be supplied at run time, and fixed_key defines if and to where in fixed_data the value should be copied.

interval = datetime.timedelta(seconds=40)

Sets the minimum period between the timestamps of uploaded data. For some services this can be less than the weather station’s “live” data period (48 seconds) whereas others may require 5 or 15 minutes between readings.

logger = None

A logging.Logger object created with the module name. This is typically done as follows:

logger = logging.getLogger(__name__)

service_name = ''

A short name used to refer to the service in weather.ini. It should be all lower case. The best name to use is the last part of the module’s file name, as follows:

service_name = os.path.splitext(os.path.basename(__file__))[0]

check_params(*keys)

Ensure user has set required values in weather.ini.

Normally the config names with required set are checked, but if your uploader has a register method you may need to check for other data.

Parameters:keys (str) – the config names to verify.

session()

Context manager factory function for a batch of one or more uploads.

This makes it easy to ensure any resources such as an internet connection are properly closed after a batch of uploads. Use the contextlib.contextmanager() decorator when you implement this method.

For a typical example, see the source code of the pywws.service.openweathermap module. If your upload can’t benefit from a session object yield None, as in pywws.service.copy.

run()

stop()

log(message)

class pywws.service.DataServiceBase(context, check_params=True)

Bases: pywws.service.ServiceBase

Base class for “data” services.

A “data” service uploader sends defined sets of data, typically as an HTML “post” or “get” operation. Service classes should be based on CatchupDataService or LiveDataService, depending on whether the service allows uploading of past data, for example to fill in gaps if the server (or pywws client) goes down for a few hours or days.

Data service classes must provide a template string to define how to convert pywws data before uploading. Required methods are session() and upload_data(). If the service has a separate authorisation or registration process this can be done in a register() method. See pywws.service.mastodon for an example.

template = ''

Defines the conversion of pywws data to key, value pairs required by the service. The template string is passed to pywws.template, then the result is passed to literal_eval() to create a dict. This rather complex process allows great flexibility, but you do have to be careful with use of quotation marks.

fixed_data = {}

Defines a set of key: value pairs that are the same for every data upload. This might include the station’s location or the software name & version. Values set by the user should be included in the weather.ini config defined in config.

upload_data(session, prepared_data={})

Upload one data set to the service.

Every data service class must implement this method.

Parameters:

• session (object) – the object created by session(). This is typically used to communicate with the server and is automatically closed when a batch of uploads has finished.
• prepared_data (dict) – a set of key: value pairs to upload. The keys and values must all be text strings.

queue_data(timestamp, data)

prepare_data(data)

valid_data(data)

class pywws.service.CatchupDataService(context, check_params=True)

Bases: pywws.service.DataServiceBase

catchup = 7

Sets the number of days of past data that can be uploaded when a service is first used.

queue_data(timestamp, data)

do_catchup(do_all=False)

upload(live_data=None, test_mode=False, options=())

upload_batch()

class pywws.service.LiveDataService(context, check_params=True)

Bases: pywws.service.DataServiceBase

catchup = None

do_catchup(do_all=False)

upload(live_data=None, test_mode=False, options=())

upload_batch()

class pywws.service.FileService(context, check_params=True)

Bases: pywws.service.ServiceBase

Base class for “file” services.

do_catchup(do_all=False)

upload(live_data=None, options=())

upload_batch()

pywws.service.main(class_, argv=None)

---

Comments or questions? Please subscribe to the pywws mailing list http://groups.google.com/group/pywws and let us know.