Metadata-Version: 2.1
Name: katsdptelstate
Version: 0.9
Summary: Karoo Array Telescope - Telescope State Client
Home-page: https://github.com/ska-sa/katsdptelstate
Author: MeerKAT SDP team
Author-email: sdpdev+katsdptelstate@ska.ac.za
License: Modified BSD
Description: 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. This database is colloquially known as *telstate*.
        
        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 the values are Python objects serialised via
        MessagePack_, which has been extended to support tuples, complex numbers and
        NumPy arrays. Older versions of the database stored the values as pickles, and
        the package warns the user if that's the case. Keys can be retrieved from the
        telstate object using attribute syntax or dict syntax.
        
        .. _MessagePack: http://www.msgpack.org/
        
        Databases can be accessed via one of two backends: a Redis client backend
        that allows shared access to an actual Redis server over the network (or a
        simulated server via fakeredis) and a simplified in-memory backend for
        stand-alone access. Both backends support loading and saving a Redis snapshot
        in the form of an RDB dump file.
        
        It is possible to have multiple *views* on the same database (one per telstate
        instance). A view is defined as a list of *prefixes* acting as namespaces that
        group keys. When reading from the database, each prefix is prepended to the key
        in turn until a match is found. When writing to the database, the first prefix
        is prepended to the key. The first prefix therefore serves as the primary
        namespace while the rest are supplementary read-only namespaces.
        
        .. warning::
        
          **WARNING**: The standard warning about Python pickles applies. Never
          retrieve data from an untrusted telstate database with values encoded as
          pickles, or connect to such a database over an untrusted network. Pickle
          support can be disabled by setting KATSDPTELSTATE_ALLOW_PICKLE=0 in the
          environment, which should make it safe to connect to untrusted telstates.
          On the other hand, the package warning can be disabled for trusted databases
          by setting the environment variable KATSDPTELSTATE_ALLOW_PICKLE=1.
        
        Getting Started
        ---------------
        
        The simplest way to test out `katsdptelstate` is to use the in-memory backend.
        If you want to run a real Redis server you will need to install Redis (version
        2.8.9 or newer) on a suitable machine on the network. For example, do this:
        
        - 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 via an endpoint or an URL
          telstate = katsdptelstate.TelescopeState('localhost:6379')
          telstate = katsdptelstate.TelescopeState('redis://localhost')
          # Or use the in-memory backend (useful for testing)
          telstate = katsdptelstate.TelescopeState()
          # Load RDB 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)  # -> 32768
          print(telstate['n_chans'])  # -> 32768
        
          # List all keys (attributes and sensors)
          print(telstate.keys())  # -> ['n_chans']
        
          # 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)  # -> [(4096, 1556112474.453495)]
          # 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)
          # Simpler notation for setting attributes
          telstate['no_change'] = 1234
          # Will raise katsdptelstate.ImmutableKeyError
          telstate['no_change'] = 456
        
          # Create a new view with namespace 'ns' and standard underscore separator
          view = telstate.view('ns')
          # Insert a new attribute in this namespace and retrieve it
          view['x'] = 1
          print(view['x'])  # -> 1
          print(view.prefixes)  # -> ('ns_', '')
          print(view.keys())  # -> ['n_chans', 'no_change', 'ns_x']
        
        
        History
        =======
        
        0.9 (2020-05-25)
        ----------------
        * Deprecate Python 2 support: this is the last release that will support Python 2 (#94)
        * Remove ``get_message`` and ``send_message``, which were never used (#89)
        * Publish the documentation on https://katsdptelstate.readthedocs.io (#90)
        * Disable pickles by default for security (#92)
        
        0.8 (2019-05-06)
        ----------------
        * The default encoding is now msgpack; warn on loading pickles (#75, #79)
        * The default backend is now in-memory (#76)
        * Add the ability to dump in-memory backend to an RDB file (#77)
        * Construct from RDB file-like objects and Redis URLs (#80, #82)
        * Report keys and prefixes to the user as strings (#73)
        * Add IPython tab completion (#83)
        * RDB reader and writer cleanup (#85, #86)
        
        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
        
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
Provides-Extra: rdb
