Table Of Contents

Previous topic

Heterogeneous Relation Graphs

Next topic

SRelation

SItem

class speect.SItem

A class for containing the items (arbitrary objects). Items are nodes in a relation which is again linked to an utterance. Items contain a key-value (string/object) set of features. An Item can have a list of daughter items as well. Items can be shared between relations.

Note

The SItem object inherits from SObject in the Speect Engine and can therefore be used in functions/methods that require parameters of type SObject.

Summary

SItem.append([toShare = None]) Create a new item and append it after this one.
SItem.prepend([toShare = None]) Create a new item and prepend it after this one.
SItem.add_daughter([toShare = None]) Create a new item and add it as a daughter of this item.
SItem.delete() Delete this item from it’s relation.
SItem.next() Get the item next to this one in the current relation.
SItem.prev() Get the item previous to this one in the current relation.
SItem.parent() Get this item’s parent item.
SItem.daughter([nth = 0]) Get this item’s daughter item.
SItem.feature_get(key) Get the raw SObject feature of the item that is associated with the given key.
SItem.path(path) Follow the given path, relative to the given item, and return the object at the path.
SItem.path_to_derived_feature(path) Execute the given feature processor, on the item from the given path, relative to the given item.
SItem.path_to_feature(path) Get the item feature, from the given path, relative to this item.
SItem.path_to_item(path) Get the item, from the given path, relative to this item.
SItem.relation() Get this item’s relation.
SItem.as_relation(relname) Find the item in the given relation that has the same shared content as this item.
SItem.in_relation(relname) Query if this item is in the named relation.
SItem.utterance() Get this item’s utterance.
SItem.voice() Get this item’s voice.

Creation/Deletion

Methods relating to the creation of items:

SItem.append()

append([toShare = None])

Create a new item and append it after this one.

Parameters:toShare (SItem) – The item with which the newly created item will share it’s content. If None then a new content will be created for the appended item.
Returns:Newly created and appended item object.
Return type:SItem
Raises :RuntimeError if Speect was unable to create the item.
SItem.prepend()

prepend([toShare = None])

Create a new item and prepend it after this one.

Parameters:toShare (SItem) – The item with which the newly created item will share it’s content. If None then a new content will be created for the prepended item.
Returns:Newly created and prepended item object.
Return type:SItem
Raises :RuntimeError if Speect was unable to create the item.
SItem.add_daughter()

add_daughter([toShare = None])

Create a new item and add it as a daughter of this item.

Parameters:toShare (SItem) – The item with which the newly created item will share it’s content. If None then a new content will be created for the daughter item.
Returns:Newly created daughter item object.
Return type:SItem
Raises :RuntimeError if Speect was unable to create the item.

Deleting an item:

SItem.delete()

delete()

Delete this item from it’s relation. Does not delete related items from other relations.

Traversing

Methods relating to the traversing of items:

List Traversal

SItem.next()

next()

Get the item next to this one in the current relation.

Returns:The next item, or None if this is the last item in the relation.
Return type:SItem
SItem.prev()

prev()

Get the item previous to this one in the current relation.

Returns:The previous item, or None if this is the first item in the relation.
Return type:SItem

Tree Traversal

SItem.parent()

parent()

Get this item’s parent item.

Returns:The parent item of this item, or None if no parent item.
Return type:SItem
SItem.daughter()

daughter([nth = 0])

Get this item’s daughter item.

Parameters:nth (int) – 0 for first daughter, -1 for last daughter and nth > 0 for nth daughter.
Returns:The nth daughter item of this item, or None if no daughter item.
Return type:SItem
Raises :TypeError if nth < -1

Features

An item’s features are accessible through the standard Python container functions. SItem supports the following container functions:

len(item)

Return the number of features in the item.

key in item

Return True if item has a feature named key, else False.

key not in item

Equivalent to not key in item.

item_a == item_b

Comparison operator. Return True if item_a equals item_b, else False. Equal meaning that the items share the same contents.

item[key]

Return the feature named key of item. Note that None is returned if no feature named key.

item[key] = value

Set item[key] to value. If a feature named key already exists in item, it will be deleted and replaced with value.

del item[key]

Remove item[key] from item. Nothing will be done if no feature named key is in item.

for key in item

SItem also supports the Python iterator protocol and therefore one can iterate over an item’s feature keys.

str(item)

SItem supports the Python method __str__() and can therefore be used in the str() built-in function and by the print statement to compute the “informal” string representation of the item.

SObject Features

SItem.feature_get()

feature_get(key)

Get the raw SObject feature of the item that is associated with the given key. This function can be used in place of the normal:

item['feature_name']

The reason for this is that the above will try to convert the returned feature into a Python object if possible. Sometimes we want the feature as a Speect object. So instead we can use this function:

item.feature_get('feature_name')

which will return the feature object as it is in Speect, i.e. an SObject.

Parameters:key (str) – The key of the key-value pair to get.
Returns:The feature associated with the given key or None if no such key-value pair.
Return type:SObject

Paths Features

Extract items, item features and item functions by navigating given paths on the HRG structure (see HRG Path topic). Paths are strings that are composed of period (”.”) separated tokens describing the path of the requested item/feature, relative to a given item. The possible tokens are:

Token Meaning
p previous item
n next item
daughter first daughter item
daughtern last daughter item
parent parent item
R:relname item as it is in the given relation relname

Methods relating to items paths:

SItem.path()

path(path)

Follow the given path, relative to the given item, and return the object at the path. The object may be another item, a feature, or a feature that has been calculated by a feature processor. This function can be used as a replacement for SItem.path_to_derived_feature(), SItem.path_to_item(), or SItem.path_to_item().

Parameters:path (str) – The path to the desired item, feature, or feature processor, relative to the given item.
Returns:The object at the end of the path, which may be another item, a item feature, or a feature that has been calculated by a feature processor.
SItem.path_to_item()

path_to_item(path)

Get the item, from the given path, relative to this item.

Parameters:path (str) – The path to the desired item, relative to this item.
Returns:The item from the path, relative to this item.
Return type:SItem
SItem.path_to_feature()

path_to_feature(path)

Get the item feature, from the given path, relative to this item.

Parameters:path (str) – The path to the desired item’s feature, relative to this item.
Returns:The feature object from the path, relative to this item.
SItem.path_to_derived_feature()

path_to_derived_feature(path)

Execute the given feature processor, on the item from the given path, relative to the given item. The name of the feature processor is the last element of the path.

Parameters:path (str) – The path to the desired item, relative to this item, with the last element being the name of the feature processor.
Returns:The extracted feature object from the path, relative to this item.

HRG

Methods relating to the item’s heterogeneous relation graph information:

SItem.relation()

relation()

Get this item’s relation.

Returns:This item’s relation.
Return type:SRelation
SItem.as_relation()

as_relation(relname)

Find the item in the given relation that has the same shared content as this item.

Parameters:relname – The relation name.
Returns:This item as it is in the named relation, or None if this item does not share it’s contents with any item in the named relation.
Return type:SItem
SItem.in_relation()

in_relation(relname)

Query if this item is in the named relation.

Parameters:relname – The relation name.
Returns:True or False.
Return type:bool
SItem.utterance()

utterance()

Get this item’s utterance.

Returns:This item’s utterance, or None if no utterance has been set.
Return type:SUtterance
SItem.voice()

voice()

Get this item’s voice.

Returns:This item’s voice, or None if no voice has been set.
Return type:SVoice