Internals

Structure

The library consists of a SmapInterface class that defines the main interface over sMAP. This class uses an abstract class TransportInterface that defines primitives to send and retrieve data over HTTP. Splitting the transport implementation from its interface allows to use this library with multiple backends. The only supported backend at the moment is the aiohttp library, plus a mockup backend used for testing.

Caching

The library supports caching time-series and metadata on the local machine, to reduce fetch time, network traffic and server load. When a query is executed for the first time, a filename is obtained by hashing its where-clause, and the query results are saved to such file. The following times the same query is executed, the results are taken from the local cached file.

The cache contains also the selected period, so that queries with same where-clause but different periods can use the cache, provided that the requested period is contained in the cached period. Other parameters, such as limits, are also stored in cache, and if they do not match, they invalidate the cache.

Local cache is disabled by default, and can enabled by passing cache=True to the SmapInterface constructor. The cache directory is obtained from appdirs library, and is usually located at:

• /home/USERNAME/.cache/sMAP-Python on Linux/Unix
• C:\\Users\\USERNAME\\AppData\\Local\\Acme\\sMAP-Python\\Cache on Windows

Invalidated cache files are deleted and re-created, but local cache is otherwise never deleted. In case it becomes too large, it should be manually deleted.

Schema Validation

sMAP server returns results through JSON encoding. This library optionally checks whether the returned JSON payloads respect the expected jsonschema. This can be useful to diagnose a faulty server implementation.