Common Types

Helpers for creating standardized Type instances. as defined by http://epics-pvdata.sourceforge.net/alpha/normativeTypes/normativeTypes.html .

Automatic Value unwrapping

Automatic transformation can be performed. between Value and more convenient types.

Transformation may be performed at the following points:

• The result of p4p.client.thread.Context.get(),

• The argument the callable passed to p4p.client.thread.Context.monitor()

• The argument of p4p.client.thread.Context.put()

• The argument of p4p.client.thread.Context.rpc()

• The argument of p4p.server.thread.SharedPV.open()

• The argument of p4p.server.thread.SharedPV.post()

• The result of p4p.server.thread.SharedPV.current()

Controlling (Un)wrapping

Client p4p.client.thread.Context accepts an argument nt= which may be None to sure some reasonable defaults. False disables wrapping, and always works with Value. nt= may also be passed a dictionary keyed by top level structure IDs mapped to callables returning objects conforming to WrapperInterface.

The unwrap argument is legacy which functions like nt= but mapping to plain functions instead of wrapper objects.

from p4p.client.thread import Context
ctxt=Context('pva', nt=False) # disable (un)wrap.  All methods use Value

Server p4p.server.thread.SharedPV accepts an argument nt= which is an instance of an object conforming to WrapperInterface.

from p4p.server.thread import SharedPV
from p4p.nt import NTScalar
pv1 = SharedPV() # pv1.open() expects a plain Value
pv2 = SharedPV(nt=NTScalar('d', display=True))

# NTScalar automatically wraps this float into a Value
pv2.open(4.2)

# send change w/ system times
pv2.post(3.3, timestamp=time.time())

# explicitly wrap and set additional fields
V = pv2.wrap(2.2, timestamp=time.time())
V['display.description'] = "My special PV"
pv2.post(V)

Conforming objects include NTScalar, NTNDArray, and others listed below.

p4p.nt.defaultNT()

Returns a copy of the default NT helper mappings.

Since:

3.1.0

NT wrap/unwrap interface

class p4p.nt.WrapperInterface

Since:

3.1.0

classmethod buildtype()

Returns a Type based on some helper specific conditions.

Return type:

Type

__init__()

Each time the type ID of a Channel changes, a new wrapper will be instantiated if available.

unwrap(Value) → object

Called with a Value and may return an arbitrary object.

Called by both clients and servers. eg. during p4p.client.thread.Context.get() and p4p.server.thread.SharedPV.current().

wrap(object) → Value

Called with an arbitrary object which it should try to translate into a Value.

Called by servers. eg. during p4p.server.thread.SharedPV.post().

assign(Value, object)

Called to update a Value based on an arbitrary object.

Called by clients. eg. during p4p.client.thread.Context.put(), where the get= argument effects the state of the Value passed in.

API Reference

class p4p.nt.NTScalar(valtype='d', **kws)

Describes a single scalar or array of scalar values and associated meta-data

>>> stype = NTScalar('d') # scalar double
>>> V = stype.wrap(4.2)
>>> assert isinstance(V, Value)

>>> stype = NTScalar.buildType('ad') # vector double
>>> V = Value(stype, {'value': [4.2, 4.3]})

The result of wrap() is an augmented value object combining ntwrappercommon and a python value type (str, int, float, numpy.ndarray).

Agumented values have some additional attributes including:

• .timestamp - The update timestamp is a float representing seconds since 1 jan 1970 UTC.

• .raw_stamp - A tuple of (seconds, nanoseconds)

• .severity - An integer in the range [0, 3]

• .raw - The complete underlying Value

Parameters:

• valtype (str) – A type code to be used with the ‘value’ field. See Type definitions

• extra (list) – A list of tuples describing additional non-standard fields

• display (bool) – Include optional fields for display meta-data

• control (bool) – Include optional fields for control meta-data

• valueAlarm (bool) – Include optional fields for alarm level meta-data

• form (bool) – Include display.form instead of the deprecated display.format.

static buildType(valtype, extra=[], *args, **kws)

Build a Type

Parameters:

• valtype (str) – A type code to be used with the ‘value’ field. See Type definitions

• extra (list) – A list of tuples describing additional non-standard fields

• display (bool) – Include optional fields for display meta-data

• control (bool) – Include optional fields for control meta-data

• valueAlarm (bool) – Include optional fields for alarm level meta-data

• form (bool) – Include display.form instead of the deprecated display.format.

Returns:

A Type

wrap(value, **kws)

Pack python value into Value

Accepts dict to explicitly initialize fields by name. Any other type is assigned to the ‘value’ field.

assign(V, py)

Store python value in Value

classmethod unwrap(value)

Unpack a Value into an augmented python type (selected from the ‘value’ field)

class p4p.nt.NTNDArray(**kws)

Representation of an N-dimensional array with meta-data

Translates into ntndarray

classmethod buildType(extra=[])

Build type

wrap(value, **kws)

Wrap numpy.ndarray as Value

assign(V, py)

Store python value in Value

classmethod unwrap(value)

Unwrap Value as NTNDArray

class p4p.nt.NTTable(columns=[], extra=[])

A generic table

>>> table = NTTable.buildType(columns=[
    ('columnA', 'ai'),
    ('columnB', 'as'),
])

static buildType(columns=[], extra=[])

Build a table

Parameters:

• columns (list) – List of column names and types. eg [(‘colA’, ‘d’)]

• extra (list) – A list of tuples describing additional non-standard fields

Returns:

A Type

wrap(values, **kws)

Pack an iterable of dict into a Value

>>> T=NTTable([('A', 'ai'), ('B', 'as')])
>>> V = T.wrap([
    {'A':42, 'B':'one'},
    {'A':43, 'B':'two'},
])

static unwrap(value)

Iterate an NTTable

Returns:

An iterator yielding an OrderedDict for each column

class p4p.nt.NTURI(args)

static buildType(args)

Build NTURI

Parameters:

args (list) – A list of tuples of query argument name and PVD type code.

>>> I = NTURI([
    ('arg_a', 'I'),
    ('arg_two', 's'),
])

wrap(path, args=(), kws={}, scheme='', authority='')

Wrap argument values (tuple/list with optional dict) into Value

Parameters:

• path (str) – The PV name to which this call is made

• args (tuple) – Ordered arguments

• kws (dict) – Keyword arguments

Return type:

Value

class p4p.nt.NTMultiChannel(*args, **kws)

Describes a structure holding the equivalent of a number of NTScalar

static buildType(valtype, extra=[])

Build a Type

Parameters:

• valtype (str) – A type code to be used with the ‘value’ field. Must be an array

• extra (list) – A list of tuples describing additional non-standard fields

Returns:

A Type

class p4p.nt.scalar.ntfloat(x=0, /)

Augmented float with additional attributes

• .severity

• .status

• .timestamp - Seconds since 1 Jan 1970 UTC as a float

• .raw_stamp - A tuple (seconds, nanoseconds)

• .raw - The underlying p4p.Value.

class p4p.nt.scalar.ntint

Augmented integer with additional attributes

• .severity

• .status

• .timestamp - Seconds since 1 Jan 1970 UTC as a float

• .raw_stamp - A tuple (seconds, nanoseconds)

• .raw - The underlying p4p.Value.

class p4p.nt.scalar.ntstr

Augmented string with additional attributes

• .severity

• .status

• .timestamp - Seconds since 1 Jan 1970 UTC as a float

• .raw_stamp - A tuple (seconds, nanoseconds)

• .raw - The underlying p4p.Value.

class p4p.nt.scalar.ntnumericarray

Augmented numpy.ndarray with additional attributes

• .severity

• .status

• .timestamp - Seconds since 1 Jan 1970 UTC as a float

• .raw_stamp - A tuple (seconds, nanoseconds)

• .raw - The underlying p4p.Value.

class p4p.nt.scalar.ntstringarray(iterable=(), /)

Augmented list of strings with additional attributes

• .severity

• .status

• .timestamp - Seconds since 1 Jan 1970 UTC as a float

• .raw_stamp - A tuple (seconds, nanoseconds)

• .raw - The underlying p4p.Value.

class p4p.nt.ndarray.ntndarray(*args, **kws)

Augmented numpy.ndarray with additional attributes

• .attrib - dictionary

• .severity

• .status

• .timestamp - Seconds since 1 Jan 1970 UTC as a float

• .raw_stamp - A tuple (seconds, nanoseconds)

• .raw - The underlying p4p.Value.

Keys in the attrib dictionary may be any python which may be stored in a PVA field, including an arbitrary Value. However, special handling is attempted if the provided Value appears to be an NTScalar or similar, in which case the .value, .alarm and .timeStamp are unpacked to the NTAttribute and other fields are discarded.