Metadata-Version: 2.1
Name: katsdptelstate
Version: 0.7
Summary: Karoo Array Telescope - Telescope State Client
Home-page: https://github.com/ska-sa/katsdptelstate
Author: Simon Ratcliffe
Author-email: sratcliffe@ska.ac.za
License: Modified BSD
Keywords: meerkat ska
Platform: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, <4
Requires-Dist: redis (>=2.10.5)
Requires-Dist: fakeredis (<1.0,>=0.10.2)
Requires-Dist: netifaces
Requires-Dist: ipaddress
Requires-Dist: msgpack
Requires-Dist: numpy
Provides-Extra: rdb
Requires-Dist: rdbtools ; extra == 'rdb'
Requires-Dist: python-lzf ; extra == 'rdb'

MeerKAT Science Data Processor Telescope State
==============================================

This is a client package that allows connection to the Redis database that
stores telescope state information for the Science Data Processor of the
MeerKAT radio telescope.

The Redis database acts as a key-value store. Each key is either a *sensor* or
an *attribute*. A sensor has multiple timestamped values organised into an
ordered set. An attribute (or *immutable* key) has a single value without a
timestamp that is not allowed to change.

The keys are strings and values are arbitrary Python objects stored as pickles.
Keys can be accessed using attribute syntax or dict syntax.

.. warning::

  **WARNING**: The standard warning about Python pickles applies. Never
  retrieve data from an untrusted telescope state or connect to one over an
  untrusted network.

Getting Started
---------------

You will need a relatively recent version of Redis installed (2.8.9 or newer).

- macOS: ``brew install redis``
- Ubuntu: ``apt-get install redis-server``

Then ``pip install katsdptelstate`` and run a local ``redis-server``. If you
also want to load RDB files, do ``pip install katsdptelstate[rdb]``.

A Simple Example
----------------

.. code:: python

  import time
  import katsdptelstate

  # Connect to an actual Redis server
  telstate = katsdptelstate.TelescopeState('localhost:6379')
  # Or use a fake Redis instance (key/values stored in memory, useful for testing)
  telstate = katsdptelstate.TelescopeState()
  # Load dump file into Redis if katsdptelstate is installed with [rdb] option
  telstate.load_from_file('dump.rdb')

  # Attribute / dict style access returns the latest value
  telstate.add('n_chans', 32768)
  print(telstate.n_chans)
  print(telstate['n_chans'])

  # List all keys (attributes and sensors)
  print(telstate.keys())

  # Sensors are timestamped underneath
  st = time.time()
  telstate.add('n_chans', 4096)
  et = time.time()
  telstate.add('n_chans', 16384)
  # Time ranges can be used and are really fast
  telstate.get_range('n_chans', st=st, et=et)
  # Add an item 10 seconds back
  telstate.add('n_chans', 1024, ts=time.time() - 10)

  # Attributes cannot be changed (only deleted)
  telstate.add('no_change', 1234, immutable=True)
  # Adding it again is OK as long as the value doesn't change
  telstate.add('no_change', 1234, immutable=True)
  # Will raise katsdptelstate.ImmutableKeyError
  telstate.add('no_change', 456)


History
=======

0.7 (2019-02-12)
----------------
* Introduce encodings and add msgpack encoding as alternative to pickle (#64, #65)
* Introduce backends and add in-memory backend as alternative to redis (#71, #72)
* Simplify setting attributes via `__setitem__` (#68)
* Let keys be bytes internally, but allow specification as unicode strings (#63)
* The GitHub repository is now public as well

0.6 (2018-05-10)
----------------
* Initial release of katsdptelstate


