Kattypes

Utilities for dealing with KATCP types.

class katcp.kattypes.Address(default=None, optional=False, multiple=False)

Bases: katcp.kattypes.KatcpType

The KATCP address type.

Note

The address type was added in katcp 0.4.

Methods

Address.check(value, major)	Check whether the value is valid.
Address.decode(value, major)
Address.encode(value, major)
Address.get_default()	Return the default value.
Address.pack(value[, nocheck, major])	Return the value formatted as a KATCP parameter.
Address.unpack(packed_value[, major])	Parse a KATCP parameter into an object.

class katcp.kattypes.Bool(default=None, optional=False, multiple=False)

Bases: katcp.kattypes.KatcpType

The KATCP boolean type.

Methods

Bool.check(value, major)	Check whether the value is valid.
Bool.decode(value, major)
Bool.encode(value, major)
Bool.get_default()	Return the default value.
Bool.pack(value[, nocheck, major])	Return the value formatted as a KATCP parameter.
Bool.unpack(packed_value[, major])	Parse a KATCP parameter into an object.

class katcp.kattypes.Discrete(values, case_insensitive=False, **kwargs)

Bases: katcp.kattypes.Str

The KATCP discrete type.

Parameters :

values : list of str

List of the values the discrete type may accept.

case_insensitive : bool

Whether case-insensitive value matching should be used.

Methods

Discrete.check(value, major)	Check whether the value in the set of allowed values.
Discrete.decode(value, major)
Discrete.encode(value, major)
Discrete.get_default()	Return the default value.
Discrete.pack(value[, nocheck, major])	Return the value formatted as a KATCP parameter.
Discrete.unpack(packed_value[, major])	Parse a KATCP parameter into an object.

check(value, major)

Check whether the value in the set of allowed values.

Raise a ValueError if it is not.

class katcp.kattypes.DiscreteMulti(values, all_keyword='all', separator=', ', **kwargs)

Bases: katcp.kattypes.Discrete

Discrete type which can accept multiple values.

Its value is always a list.

Parameters :

values : list of str

Set of allowed values.

all_keyword : str

The string which represents the list of all allowed values.

separator : str

The separator used in the packed value string.

Methods

DiscreteMulti.check(value, major)	Check that each item in the value list is in the allowed set.
DiscreteMulti.decode(value, major)
DiscreteMulti.encode(value, major)
DiscreteMulti.get_default()	Return the default value.
DiscreteMulti.pack(value[, nocheck, major])	Return the value formatted as a KATCP parameter.
DiscreteMulti.unpack(packed_value[, major])	Parse a KATCP parameter into an object.

check(value, major)

Check that each item in the value list is in the allowed set.

class katcp.kattypes.Float(min=None, max=None, **kwargs)

Bases: katcp.kattypes.KatcpType

The KATCP float type.

Parameters :

min : float

The minimum allowed value. Ignored if not given.

max : float

The maximum allowed value. Ignored if not given.

Methods

Float.check(value, major)	Check whether the value is between the minimum and maximum.
Float.decode(value, major)
Float.encode(value, major)
Float.get_default()	Return the default value.
Float.pack(value[, nocheck, major])	Return the value formatted as a KATCP parameter.
Float.unpack(packed_value[, major])	Parse a KATCP parameter into an object.

check(value, major)

Check whether the value is between the minimum and maximum.

Raise a ValueError if it is not.

class katcp.kattypes.Int(min=None, max=None, **kwargs)

Bases: katcp.kattypes.KatcpType

The KATCP integer type.

Parameters :

min : int

The minimum allowed value. Ignored if not given.

max : int

The maximum allowed value. Ignored if not given.

Methods

Int.check(value, major)	Check whether the value is between the minimum and maximum.
Int.decode(value, major)
Int.encode(value, major)
Int.get_default()	Return the default value.
Int.pack(value[, nocheck, major])	Return the value formatted as a KATCP parameter.
Int.unpack(packed_value[, major])	Parse a KATCP parameter into an object.

check(value, major)

Check whether the value is between the minimum and maximum.

Raise a ValueError if it is not.

class katcp.kattypes.KatcpType(default=None, optional=False, multiple=False)

Bases: object

Class representing a KATCP type.

Sub-classes should:

• Set the name attribute.
• Implement the encode() method.
• Implement the decode() method.

Parameters :

default : object

The default value for this type.

optional : boolean

Whether the value is allowed to be None.

multiple : boolean

Whether multiple values of this type are expected. Must be the last type parameter if this is True.

Methods

KatcpType.check(value, major)	Check whether the value is valid.
KatcpType.get_default()	Return the default value.
KatcpType.pack(value[, nocheck, major])	Return the value formatted as a KATCP parameter.
KatcpType.unpack(packed_value[, major])	Parse a KATCP parameter into an object.

check(value, major)

Check whether the value is valid.

Do nothing if the value is valid. Raise an exception if the value is not valid. Parameter major describes the KATCP major version to use when interpreting the validity of a value.

get_default()

Return the default value.

Raise a ValueError if the value is not optional and there is no default.

Returns :

default : object

The default value.

pack(value, nocheck=False, major=5)

Return the value formatted as a KATCP parameter.

Parameters :

value : object

The value to pack.

nocheck : bool

Whether to check that the value is valid before packing it.

major : int. Defaults to latest implemented KATCP version (5)

Major version of KATCP to use when interpreting types

Returns :

——- :

packed_value : str

The unescaped KATCP string representing the value.

unpack(packed_value, major=5)

Parse a KATCP parameter into an object.

Parameters :

packed_value : str

The unescaped KATCP string to parse into a value.

major : int. Defaults to latest implemented KATCP version (5)

Major version of KATCP to use when interpreting types

Returns :

value : object

The value the KATCP string represented.

class katcp.kattypes.Lru(default=None, optional=False, multiple=False)

Bases: katcp.kattypes.KatcpType

The KATCP lru type

Methods

Lru.check(value, major)	Check whether the value is valid.
Lru.decode(value, major)
Lru.encode(value, major)
Lru.get_default()	Return the default value.
Lru.pack(value[, nocheck, major])	Return the value formatted as a KATCP parameter.
Lru.unpack(packed_value[, major])	Parse a KATCP parameter into an object.

class katcp.kattypes.Parameter(position, name, kattype, major)

Bases: object

Wrapper for kattypes which holds parameter-specific information

Parameters :

position : int

The parameter’s position (starts at 1)

name : str

The parameter’s name (introspected)

kattype : KatcpType object

The parameter’s kattype

major : integer

Major version of KATCP to use when interpreting types

Methods

Parameter.pack(value)	Pack the parameter using its kattype.
Parameter.unpack(value)	Unpack the parameter using its kattype.

pack(value)

Pack the parameter using its kattype.

Parameters :

value : object

The value to pack

Returns :

packed_value : str

The unescaped KATCP string representing the value.

unpack(value)

Unpack the parameter using its kattype.

Parameters :

packed_value : str

The unescaped KATCP string to unpack.

Returns :

value : object

The unpacked value.

class katcp.kattypes.Regex(regex, **kwargs)

Bases: katcp.kattypes.Str

String type that checks values using a regular expression.

Parameters :

regex : str or regular expression object

Regular expression that values should match.

Methods

Regex.check(value, major)
Regex.decode(value, major)
Regex.encode(value, major)
Regex.get_default()	Return the default value.
Regex.pack(value[, nocheck, major])	Return the value formatted as a KATCP parameter.
Regex.unpack(packed_value[, major])	Parse a KATCP parameter into an object.

class katcp.kattypes.Str(default=None, optional=False, multiple=False)

Bases: katcp.kattypes.KatcpType

The KATCP string type.

Methods

Str.check(value, major)	Check whether the value is valid.
Str.decode(value, major)
Str.encode(value, major)
Str.get_default()	Return the default value.
Str.pack(value[, nocheck, major])	Return the value formatted as a KATCP parameter.
Str.unpack(packed_value[, major])	Parse a KATCP parameter into an object.

class katcp.kattypes.StrictTimestamp(default=None, optional=False, multiple=False)

Bases: katcp.kattypes.KatcpType

A timestamp that enforces the XXXX.YYY format for timestamps.

Methods

StrictTimestamp.check(value, major)	Check whether the value is positive.
StrictTimestamp.decode(value, major)
StrictTimestamp.encode(value, major)
StrictTimestamp.get_default()	Return the default value.
StrictTimestamp.pack(value[, nocheck, major])	Return the value formatted as a KATCP parameter.
StrictTimestamp.unpack(packed_value[, major])	Parse a KATCP parameter into an object.

check(value, major)

Check whether the value is positive.

Raise a ValueError if it is not.

class katcp.kattypes.Struct(fmt, **kwargs)

Bases: katcp.kattypes.KatcpType

KatcpType for parsing and packing values using the struct module.

Parameters :

fmt : str

Format to use for packing and unpacking values. It is passed directly into struct.pack() and struct.unpack().

Methods

Struct.check(value, major)	Check whether the value is valid.
Struct.decode(value, major)
Struct.encode(value, major)
Struct.get_default()	Return the default value.
Struct.pack(value[, nocheck, major])	Return the value formatted as a KATCP parameter.
Struct.unpack(packed_value[, major])	Parse a KATCP parameter into an object.

class katcp.kattypes.Timestamp(default=None, optional=False, multiple=False)

Bases: katcp.kattypes.KatcpType

The KATCP timestamp type.

Methods

Timestamp.check(value, major)	Check whether the value is valid.
Timestamp.decode(value, major)
Timestamp.encode(value, major)
Timestamp.get_default()	Return the default value.
Timestamp.pack(value[, nocheck, major])	Return the value formatted as a KATCP parameter.
Timestamp.unpack(packed_value[, major])	Parse a KATCP parameter into an object.

class katcp.kattypes.TimestampOrNow(default=None, optional=False, multiple=False)

Bases: katcp.kattypes.Timestamp

KatcpType representing either a Timestamp or the special value katcp.kattypes.TimestampOrNow.NOW.

Floats are encoded as for katcp.kattypes.Timestamp. katcp.kattypes.TimestampOrNow.NOW is encoded as the string “now”.

Methods

TimestampOrNow.check(value, major)	Check whether the value is valid.
TimestampOrNow.decode(value, major)
TimestampOrNow.encode(value, major)
TimestampOrNow.get_default()	Return the default value.
TimestampOrNow.pack(value[, nocheck, major])	Return the value formatted as a KATCP parameter.
TimestampOrNow.unpack(packed_value[, major])	Parse a KATCP parameter into an object.

katcp.kattypes.make_reply(msgname, types, arguments, major)

Helper method for constructing a reply message from a list or tuple

Parameters :

msgname : str

Name of the reply message.

types : list of kattypes

The types of the reply message parameters (in order).

arguments : list of objects

The (unpacked) reply message parameters.

major : integer

Major version of KATCP to use when packing types

katcp.kattypes.pack_types(types, args, major)

Pack arguments according the the types list.

Parameters :

types : list of kattypes

The types of the arguments (in order).

args : list of objects

The arguments to format.

major : integer

Major version of KATCP to use when packing types

katcp.kattypes.request(*types, **options)

Decorator for request handler methods.

The method being decorated should take a req argument followed by arguments matching the list of types. The decorator will unpack the request message into the arguments.

Parameters :

types : list of kattypes

The types of the request message parameters (in order). A type with multiple=True has to be the last type.

Keyword Arguments:  

include_msg : bool, default: False

Pass the request message as the third parameter to the decorated request handler function

major : int. Defaults to latest implemented KATCP version (5)

Major version of KATCP to use when interpreting types

Examples

>>> class MyDevice(DeviceServer):
...     @request(Int(), Float(), Bool())
...     @return_reply(Int(), Float())
...     def request_myreq(self, req, my_int, my_float, my_bool):
...         return ("ok", my_int + 1, my_float / 2.0)
...
...     @request(Int(), include_msg=True)
...     @return_reply(Bool())
...     def request_is_odd(self, req, msg, my_int):
...         self.inform(req, Message.reply_inform(
...             msg, 'Checking oddity of %d' % my_int))
...         return ("ok", my_int % 2)
...

katcp.kattypes.return_reply(*types, **options)

Decorator for returning replies from request handler methods

The method being decorated should return an iterable of result values. If the first value is ‘ok’, the decorator will check the remaining values against the specified list of types (if any). If the first value is ‘fail’ or ‘error’, there must be only one remaining parameter, and it must be a string describing the failure or error In both cases, the decorator will pack the values into a reply message.

Parameters :

types : list of kattypes

The types of the reply message parameters (in order).

Keyword Arguments:  

major : int. Defaults to latest implemented KATCP version (5)

Major version of KATCP protocol to use when interpreting types

Examples

>>> class MyDevice(DeviceServer):
...     @request(Int())
...     @return_reply(Int(), Float())
...     def request_myreq(self, req, my_int):
...         return ("ok", my_int + 1, my_int * 2.0)
...

katcp.kattypes.send_reply(*types, **options)

Decorator for sending replies from request callback methods

This decorator constructs a reply from a list or tuple returned from a callback method, but unlike the return_reply decorator it also sends the reply rather than returning it.

The list/tuple returned from the callback method must have req (a ClientRequestConnection instance) as its first parameter and the original message as the second. The original message is needed to determine the message name and ID.

The device with the callback method must have a reply method.

Parameters :

types : list of kattypes

The types of the reply message parameters (in order).

Keyword Arguments:  

major : int. Defaults to latest implemented KATCP version (5)

Major version of KATCP to use when interpreting types

Examples

>>> class MyDevice(DeviceServer):
...     @send_reply(Int(), Float())
...     def my_callback(self, req):
...         return (req, "ok", 5, 2.0)
...

katcp.kattypes.unpack_types(types, args, argnames, major)

Parse arguments according to types list.

Parameters :

types : list of kattypes

The types of the arguments (in order).

args : list of strings

The arguments to parse.

argnames : list of strings

The names of the arguments.

major : integer

Major version of KATCP to use when packing types