katsdptelstate 0.14

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 4.0 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

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']

Asynchronous interface

There is also an interface that works with asyncio. Use katsdptelstate.aio.TelescopeState instead of katsdptelstate.TelescopeState. Functions that interact with the database are now coroutines. Python 3.6+ is required.

There are a few differences from the synchronous version, partly necessary due to the nature of asyncio and partly to streamline and modernise the code:

• The constructor only takes a backend, not an endpoint. See below for an example of how to construct a redis backend.

• There is currently no support for reading or writing RDB files; you’ll need to create a synchronous telescope state client that connects to the same storage.

• There is no support for attribute-style access.

• Item-style access is supported for read (await ts.get('key')), but not for write. Use await ts.set('key', 'value') instead to set immutable keys.

• Instead of key in ts, use await ts.exists(key).

• The wait_key and wait_indexed methods do not take a timeout or a cancellation future. They can be used with asyncio’s cancellation machinery. The async-timeout package is useful for timeouts.

• The backend should be closed when no longer needed to avoid warnings.

from katsdptelstate.aio import TelescopeState
from katsdptelstate.aio.redis import RedisBackend

# Create a connection to localhost redis server
backend = await RedisBackend.from_url('redis://localhost')
ts = TelescopeState(backend)

# Store and retrieve some data
await ts.set('key', 'value')
print(await ts.get('key'))

# Close the connections (do not try to use ts after this)
ts.backend.close()
await ts.backend.wait_closed()

0.14 (2024-02-28)

• Improvements to internal type hints (#133)

• Get lupa version (for testing) from katsdpdockerbase (#134)

• Fix variables referenced before use in exception path (#135)

• Improve error message when opening old files containing pickles (#136)

0.13 (2023-03-15)

• Upgrade to redis-py>=4.2 and fakeredis>=2, fix test warnings (#132)

• This now requires at least Python 3.7 and no more aioredis

0.12 (2023-03-13)

• Switch to aioredis 2.x (#124)

• Add async (and synchronous) RedisBackend.from_url constructor (#125, #126)

• Switch from nose to pytest (#129)

• Remove Endpoint.multicast_subscribe and netifaces dependency (#130)

• Fix Lua script for set_indexed so that wait_indexed actually works (#127)

• Make aio wait_key more robust (#128)

• General cleanup (#122, #123)

0.11 (2021-05-07)

• Add asynchronous RDBWriter class (#108)

• Use a transaction for get_range instead of Lua: faster on server side (#110)

• Multiplex aio pubsubs over pool’s standard connection (#113)

• Require hiredis for speed and aioredis<2 for compatibility (#114, #118)

• Improve wait_keys responsiveness for MemoryBackend (#111, #116)

• Avoid blocking the Redis server on telstate.clear (#112)

• Update Docker image to use Redis 6.x instead of 4.x (#109)

• Support older HMSET Redis command in unit tests (#107)

• Requirements cleanup (#115, #117, #119, #120)

0.10 (2020-05-25)

• Remove Python 2 support. At least Python 3.5 is required.

• Remove support for old versions of redis-py (#100)

• Use redis-py health checks to improve robustness (#99)

• Add “indexed” keys (#98)

• Add an asyncio interface (#103)

• No longer throw InvalidKeyError when setting a key that shadows a method (#102)

• Add type annotations for mypy (#101)

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