client spec v3.0

[shroffk]

No description provided.

[dxmaxwell]

SET

set(channel={'name':'channelName', 'owner':'channelOwner'})
set(channels=[{'name':'chName1','owner':'chOwner'},{'name':'chName2','owner':'chOwner'}])
# Do these methods support passing 'properties' and 'tags' within the channel dictionary???

# YES, Jjust like the update() API

set(tag={'name':'tagName','owner':'tagOwner'})
set(tag={'name':'tagName','owner':'tagOwner', 'channels':[{ 'name':'ch1'}, { 'name':'ch2' }] })
set(tags=[{'name':'tag1','tagOwner'},{'name':'tag2','owner':'tagOwner'}])

set(property={'name':'propertyName','owner':'propertyOwner'})
set(property={'name':'propName','owner':'propOwner', 'channels':[
    { 'name':'ch1', 'properties':[{ 'name':'propName', 'owner':'propOwner', 'value':'val1' }] },
    { 'name':'ch2', 'properties':[{ 'name':'propName', 'owner':'propOwner', 'value':'val2' }] }
   ]}
)
set(properties=[{'name':'prop1','owner':'propOwner'},'prop2','propOwner']) 

set(tag={'name':'tagName','owner':'tagOwner'}, channelName='chName')
set(tag={'name':'tagName','owner':'tagOwner'}, channelNames=['ch1','ch2','ch3'])

# Keyword argument 'channelNames' does not seem to be supported.
# Instead it looks like 'channels' is used, but its not documented
# Using 'channels' is the newer API, needs documentation.
set(property={'name':'propName','owner':'propOwner','value':'propValue'}, channelName='ch1')

# Same as above, 'channelNames' not supported
set(property={'name':'propName','owner':'propOwner','value':'propValue'}, channelNames=['ch1','ch2'])

UPDATE

## The update() API should be identical to the set() API.

update(channel = {'name':'existingCh', 'owner':'chOwner',
                              'properties':'[
                                        {'name':'newProp','owner':'propOwner','value':'Val'},
                                        {'name':'existingProp','owner':'propOwner','value':'newVal'}
                              ],
                              'tags':[
                                       {'name':'mytag','owner':'tagOwner'}
                               ]}
               )
# updates the channel 'existingCh' with the new provided properties and tags 
# without affecting the other tags and properties of this channel

update(channels = [...]) 
# Not implemented, maybe a good addition to have parity with set()???

update(property = { 'name':'prop', 'owner':'propOwner', 'value':'newValue' })
# Not sure if this supports passing a value, maybe just changing the owner??

update(tag = { 'name':'tag', 'owner':'tagOwner' } )
# Change the owner of a tag?

update(property={'name':'propName', 'owner':'propOwner', 'value':'propValue'},  channelName='ch1')
# Add Property to the channel with the name 'ch1'
# without affecting the other channels using this property
# BROKEN: missing method self.__encodeProperty()

update(property={'name':'propName', 'owner':'propOwner', 'value':'propValue'}, 
                                   channelNames=['ch1','ch2','ch3'])
# Add Property to the channels with the names in the list channelNames
# without affecting the other channels using this property
# BROKEN: missing method self.__encodeProperty()

update(tag = {'name':'myTag', 'owner':'tagOwner'}, channelName='chName')
# Add tag to channel with name chName
# without affecting the other channels using this tag
# BROKEN: missing method self._encodeTag()

update(tag = {'name':'tagName'}, channelNames=['ch1','ch2','ch3'])
# Add tag to channels with names in the list channeNames
# without affecting the other channels using this tag 
# BROKEN: missing method self._encodeTag()

## RENAME OPERATIONS ##    

update(channel = {'name':'newChannelName','owner':'channelOwner'}, 
                                     originalChannelName = 'oldChannelName')
# rename the channel 'oldChannelName' to 'newChannelName'

update(property = {'name':'newPropertyName','owner':'propOwner'}, 
                                       originalPropertyName = 'oldPropertyName')
# rename the property 'oldPropertyName' to 'newPropertyName'
# the channels with the old property are also updated
# BROKEN: missing method self.__encodeProperty()

update(tag = {'name':'newTagName','owner':'tagOwner'}, originalTagName = 'oldTagName')
# rename the tag 'oldTagName' to 'newTagName'
# the channel with the old tag are also updated

DELETE

# Methods to delete a channel, property, tag

delete(channelName = 'ch1')

delete(tagName = 'myTag')
# tagName = tag name of the tag to be removed from all channels

delete(propertyName = 'position')
# propertyName = property name of property to be removed from all channels

delete(tag={'name':'myTag','owner':'tagOwner'}, channelName = 'chName') 
# delete the tag from the specified channel _chName_

delete(tag={'name':'myTag', 'owner':'tagOwner'}, channelNames=['ch1','ch2','ch3'])
# delete the tag from all the channels specified in the channelNames list

delete(property = {'name':'propName','propOwner':'propOwner'} ,channelName = 'chName')
# delete the property from the specified channel

delete(property = {'name':'propName','owner':'propOwner'} ,channelNames = ['ch1','ch2','ch3'])
# delete the property from all the channels in the chann

FIND

# Method allows you to query for a channel/s based on name, properties, tags

find(name='*')
find(name='SR:C01*')

find(tagName = 'myTag')

find(property=[('position','*')])
find(property=[('position','*'),('cell','')])      
#        returns a _list_ of matching Channels
#       special pattern matching char 
#        * for multiple char
#        ? for single char

        Searching with multiple parameters
find(name='SR:C01*', tagName = 'myTag', property=[('position','pattern1')])
#        return all channels with name matching 'SR:C01*' AND 
#                           with tagName = 'mytag' AND 
#                            with property 'position' with value matching 'pattern1'     

#        For multiValued searches
find(name='pattern1,pattern2')
#        will return all the channels which match either pattern1 OR pattern2

find(property=[('propA','pattern1,pattern2')])
#      will return all the channels which have the property propA  and 
#      whose values match pattern1 OR pattern2

find(property=[('propA', 'pattern1'),('propB', 'pattern2')])
#      will return all the channels which have properties
#      _propA_ with value matching _pattern1_ AND _propB_ with value matching _pattern2_

find(tagName='pattern1,pattern2')
#   will return all the channels which have the tags matching pattern1 AND pattern2

#       To query for the existance of a tag or property use findTag and findProperty.

findTag('tagName')
# Searches for the _exact_ tagName and returns a single Tag object if found

findProperty('propertyName')
#  Searches for the _exact_ propertyName and return a single Property object if found

getAllTags()
#  return a list of all the Tags present - even the ones not associated w/t any channel

getAllProperties()
# return a list of all the Properties present - even the ones not associated w/t any channel

[shroffk]

Todo:

• Update the version number to 3.0.0
• The pydocs for all the method calls need to be updated
• The update method with multiple parameters need to be fixed (remove references to the old encoders)
• Unit tests for the old update api need to be readded
• Ensure unit tests cover the documented API
• Ensure the doxygen config file is updated to the correct version and creates the correct pydocs