Migrating from katcp-python

While aiokatcp is loosely inspired by the katcp-python API, it does not strictly follow it. There are a number of changes that you will need to make to port code from katcp-python to aiokatcp. This section tries to list some of the most important:

Messages

  • The message arguments are pass to Message as a *args, rather than a single list argument.

  • The mid (message ID) argument is keyword-only.

  • The message types are an enum, Message.Type.

Types

  • The kattypes types (Int etc) have been replaced by plain Python types and a type registration system. The discrete type has been replaced by enums.

  • In katcp-python, addresses were represented as a tuple of a string and an integer. In aiokatcp, it is a full-blown class (Address) and the host part uses the ipaddress module.

  • TimestampOrNow is not a real type. Instead, it is an alias for Union[Timestamp, Now]. The actual value received on decoding is either a Timestamp or is Now.NOW.

Device server

  • VERSION_INFO and BUILD_INFO tuples are replaced by VERSION and BUILD_STATE (to match the terminology in the specification) and they are strings (to give greater freedom in version format).

  • The @request and @return_reply decorators no longer exist, as they are effectively the defaults, and the type information is provided by Python type annotations.

  • The return code (ok, fail or invalid) no longer forms part of the handler return value. Returning a value implies ok while raising an exception implies fail. It’s now also acceptable to return nothing, which will send an ok without further arguments if no reply has been sent.

  • AsyncReply is gone. All request handlers are asynchronous now. If you need to serialise access to the device, use asyncio locks.

  • Instead of add_sensor() and so on, there is a DeviceServer.sensors attribute that behaves like either a dictionary or a set.

Sensors

  • The status is now an enum type, Sensor.Status.

  • There is no Observer class: just pass a callable.

General

  • Because it is required for Python 3, there is now careful separation between strings (Unicode) and bytes. See Strings versus bytes for more details.

  • There is no direct support for Tornado, as everything runs on the asyncio event loop. Refer to Tornado documentation for how to bridge Tornado and asyncio code.

  • None of the code is thread-safe, including sensor updates. It is recommended that code using aiokatcp is single-threaded, but where that is not possible it needs to use asyncio primitives (such as AbstractEventLoop.call_soon_threadsafe()) to ensure that aiokatcp structures are touched only by the thread running the event loop.

  • None of the functions have timeout parameters. Instead, you can cancel coroutines, for example, using async_timeout.