parlay.items

parlay.items.base

class parlay.items.base.BaseItem(item_id, name, adapter=None)[source]

Bases: object

The Base Item that all other Items should inherit from

get_discovery()[source]

The protocol can call this to get discovery from me

get_item_template_string()[source]

This returns the type string for the item eg: sscom/STD_ITEM “

item_name = None

:type Adapter

on_message(msg)[source]

Every time we get a message for us, this method will be called with it. Be sure to override this.

publish(msg)[source]
subscribe(_fn, **kwargs)[source]
class parlay.items.base.INPUT_TYPES[source]

Bases: object

ARRAY = 'ARRAY'
DROPDOWN = 'DROPDOWN'
NUMBER = 'NUMBER'
NUMBERS = 'NUMBERS'
OBJECT = 'OBJECT'
STRING = 'STRING'
STRINGS = 'STRINGS'
class parlay.items.base.MSG_STATUS[source]

Bases: object

ERROR = 'ERROR'
INFO = 'INFO'
OK = 'OK'
PROGRESS = 'PROGRESS'
WARNING = 'WARNING'
class parlay.items.base.MSG_TYPES[source]

Bases: object

COMMAND = 'COMMAND'
DATA = 'DATA'
EVENT = 'EVENT'
PROPERTY = 'PROPERTY'
RESPONSE = 'RESPONSE'
STREAM = 'STREAM'
class parlay.items.base.TX_TYPES[source]

Bases: object

BROADCAST = 'BROADCAST'
DIRECT = 'DIRECT'
parlay.items.base.get_recursive_base_list(cls, base_list=None)[source]

Get the full class heirarchy list for a class, to see all classes and super classes a python class inherits from

parlay.items.parlay_standard

exception parlay.items.parlay_standard.BadStatusError(error, description='')[source]

Bases: exceptions.Exception

Throw this if you want to return a Bad Status!

class parlay.items.parlay_standard.CommandHandle(msg, script)[source]

Bases: object

This is a command handle that wraps a command message and allows blocking until certain messages are recieved

wait_for(*args, **kwargs)[source]

Block and wait for a message in our queue where fn returns true. Return that message

wait_for_ack(*args, **kwargs)[source]

Called from a scripts thread. Blocks until the message is ackd

wait_for_complete(*args, **kwargs)[source]

Called from a scripts thread. Blocks until the message is complete.

class parlay.items.parlay_standard.ParlayCommandItem(item_id=None, name=None, reactor=None, adapter=None)[source]

Bases: parlay.items.parlay_standard.ParlayStandardItem

This is a Parlay Item that defines functions that serve as commands, with arguments.

This class enables you to use the parlay_command() decorator over your command functions. Then, those functions will be available as commands that can be called from the user interface, scripts, or by other items.

Example: How to define a class as a ParlayCommandItem:

from parlay import local_item, ParlayCommandItem, parlay_command

@local_item()
class MotorSimulator(ParlayCommandItem):

    def __init__(self, item_id, item_name):
        self.coord = 0
        ParlayCommandItem.__init__(self, item_id, item_name)

    @parlay_command
    def move_to_coordinate(self, coordinate)
        self.coord = coordinate

Example: How to instantiate an item from the above definition:

import parlay
from motor_sim import MotorSimulator

MotorSimulator("motor1", "motor 1")  # motor1 will be discoverable
parlay.start()

Example: How to interact with the instantiated item from a Parlay script:

# script_move_motor.py

setup()
discover()
motor_sim = get_item_by_name("motor 1")
motor_sim.move_to_coordinate(500)
SUBSYSTEM_ID = 'python'
get_discovery()[source]

Will auto-populate the UI with inputs for commands

on_message(msg)[source]

Will handle command messages automatically. Returns True if the message was handled, False otherwise

send_response(msg, contents=None, msg_status='OK')[source]
wait_for_next_recv_msg()[source]

Returns a deferred that will callback on the next message we RECEIVE

wait_for_next_sent_msg()[source]

Returns a deferred that will callback on the next message we SEND

class parlay.items.parlay_standard.ParlayDatastream(default=None, val_type=None, units='', callback=<function <lambda>>)[source]

Bases: object

A convenience class for creating datastreams within ParlayCommandItems.

Example Usage:

class Balloon(ParlayCommandItem):
    altitude = ParlayDatastream(default=0, units="ft")
listen(instance, listener, requester_id)[source]

Listen to the datastream. Will call calback whenever there is a change

stop(instance, requester_id)[source]

Stop listening

class parlay.items.parlay_standard.ParlayProperty(default=None, val_type=<type 'str'>, read_only=False, write_only=False, custom_read=None, custom_write=None)[source]

Bases: object

A convenience class for creating properties of ParlayCommandItems.

Example: How to define a property:

class MyItem(ParlayCommandItem):
    x = ParlayProperty(default=0, val_type=int)

    def __init__(self, item_id, item_name):
        ParlayCommandItem.__init__(self, item_id, item_name)
    ...

Example: How to access a property from a script:

setup()
discover()
my_item = get_item_by_name("MyItem")
original_value = my_item.x
my_item.x = 5
class parlay.items.parlay_standard.ParlayStandardItem(item_id, name, reactor=None, adapter=None)[source]

Bases: parlay.items.threaded_item.ThreadedItem

This is a parlay standard item. It supports building inputs for the UI in an intuitive manner during discovery. Inherit from it and use the parlay decorators to get UI functionality

add_datastream(id, attr_name=None, units='', name=None)[source]

Add a datastream to this Item. :param id : The id of the stream :param name: The name of the datastream (defaults to id) :param attr_name: the name of the attr to set in ‘self’ when setting and getting (same as name if None) :param units: units of streaming value that will be reported during discovery

add_field(msg_key, input, label=None, required=False, hidden=False, default=None, dropdown_options=None, dropdown_sub_fields=None, topic_field=False)[source]

Add a field to this items discovery. This field will show up in the item’s CARD in the UI

add_property(id, attr_name=None, input='STRING', read_only=False, write_only=False, name=None)[source]

Add a property to this Item. :param id : the id of the name :param name : The name of the property (defaults to ID) :param attr_name = the name of the attr to set in ‘self’ when setting and getting (None if same as name) :param read_only = Read only :param write_only = write_only

clear_fields()[source]

clears all fields. Useful to change the discovery UI

create_field(msg_key, input, label=None, required=False, hidden=False, default=None, dropdown_options=None, dropdown_sub_fields=None)[source]

Create a field for the UI

get_discovery()[source]

Discovery method. You can override this in a subclass if you want, but it will probably be easier to use the self.add_property and self.add_field helper methods and call this method like: def get_discovery(self):

discovery = ParlayStandardItem.get_discovery(self) # do other stuff for subclass here return discovery
send_file(filename, receiver=None)[source]

send file contents as an event message (EVENT is ParlaySendFileEvent) to a receiver

Parameters:
  • filename (str) – path to file that needs to be sent
  • receiver (str) – ID that the file needs to be sent to. by default, the receiver is None meaning the file sending event should be broadcast. If not broadcast this will generally be “UI”

the item will send an event message. The contents will be formatted in the following way:

contents: {
“EVENT”: “ParlaySendFileEvent” “DESCRIPTION”: [filename being sent as string], “INFO”: [contents of file as string]

}

send_message(to=None, from_=None, contents=None, tx_type='DIRECT', msg_type='DATA', msg_id=None, msg_status='OK', response_req=False, extra_topics=None)[source]

Sends a Parlay standard message. contents is a dictionary of contents to send

send_parlay_command(to, command, _timeout=4294967296, **kwargs)[source]

Send a parlay command to an known ID

class parlay.items.parlay_standard.ParlayStandardScriptProxy(discovery, script)[source]

Bases: object

A proxy class for the script to use, that will auto-detect discovery information and allow script writers to intuitively use the item

class PropertyProxy(id, item_proxy, blocking_set=True)[source]

Bases: object

Proxy class for a parlay property

class ParlayStandardScriptProxy.StreamProxy(id, item_proxy, rate)[source]

Bases: object

Proxy class for a parlay stream

MAX_LOG_SIZE = 1000000
attach_listener(listener)[source]
clear_log()[source]

Resets the internal log

get()[source]
get_log()[source]

Public interface to get the stream log

start_logging(rate)[source]

Script function that enables logging. When a new value is pushed to the datastream the value will get pushed to the end of the log.

stop()[source]

Stop streaming :return:

stop_logging()[source]

Script function that disables logging.

wait_for_value()[source]
If in thread:
Will block until datastream is updated
If in Broker:
Will return deferred that is called back with the datastream value when updated
ParlayStandardScriptProxy.get_datastream_handle(name)[source]
ParlayStandardScriptProxy.send_parlay_command(command, **kwargs)[source]

Manually send a parlay command. Returns a handle that can be paused on

parlay.items.parlay_standard.parlay_command(async=False, auto_type_cast=True)[source]

Make the decorated method a parlay_command.

Parameters:
  • async – If True, will run as a normal twisted async function call. If False, parlay will spawn a separate thread and run the function synchronously (Default false)
  • auto_type_cast – If true, will search the function’s docstring for type info about the arguments, and provide that information during discovery

parlay.items.threaded_item

exception parlay.items.threaded_item.AsyncSystemError(error_msg)[source]

Bases: exceptions.Exception

This error class is for asynchronous system errors.

exception parlay.items.threaded_item.ErrorResponse(error_msg)[source]

Bases: exceptions.Exception

class parlay.items.threaded_item.ListenerStatus[source]

Bases: object

Enum object for keeping or removing listeners

KEEP_LISTENER = False
REMOVE_LISTENER = True
class parlay.items.threaded_item.ThreadedItem(item_id, name, reactor=None, adapter=None)[source]

Bases: parlay.items.base.BaseItem

Base object for all Parlay scripts

add_listener(listener_function)[source]

Add functions to the listener list

close_protocol(protocol_id)[source]

close a protocol by id :param protocol_id: :return:

discover(force=True)[source]

Run a discovery so that the script knows what items are attached and can get handles to them.

Parameters:force – If True, will force a rediscovery, if False will take the last cached discovery
discovery = None

The current discovery information to pull from

get_all_items_with_name(*args, **kwargs)[source]

Returns a handler object that can be used to send messages to an item.

Parameters:item_name – globally unique name of the item
Returns:a proxy object for the item
get_item_by_id(*args, **kwargs)[source]

Returns a handler object that can be used to send messages to an item.

Parameters:item_id – globally unique id of the item
Returns:a proxy object for the item
get_item_by_name(*args, **kwargs)[source]

Returns a handler object that can be used to send messages to an item.

Parameters:item_name – globally unique name of the item
Returns:a proxy object for the item
load_discovery(path)[source]

Load discovery from a file.

Parameters:path – The path to the file that has the JSON discovery
make_msg(to, command, msg_type='COMMAND', direct=True, response_req=True, _extra_topics=None, **kwargs)[source]

Prepare a message for the broker to disperse

open(protocol, **params)[source]
Parameters:
  • protocol – protocol being used
  • params – other parameters
Returns:

publish(msg)[source]
save_discovery(path)[source]

Save the current discovery information to a file so it can be loaded later

Parameters:path – The Path to the file to save to (Warning: will be overwritten)
send_parlay_message(msg, timeout=120, wait=None)[source]

Send a command. This will be sent from the reactor thread. If a response is required, we will wait for it. :param msg The Message to send :param timeout If we require a response and don’t get one back int timeout seconds, raise a timeout exception :param wait If set to True, will block until a response, if false will continue without blocking, If set to None, till auto discover based on message RESPONSE_REQ.

sleep(timeout)[source]

Sleep for <timeout> seconds. This call is BLOCKING.

Parameters:timeout – number of seconds to sleep
stop_reactor_on_close = True
parlay.items.threaded_item.cleanup()[source]