Object-Oriented API¶

The low-level commands are documented in the section of this documentation Tile-Commands. There is an alternative way to access much of the same functions that uses an object-oriented interface. This object-oriented interface tends to be easier to read and right, and there is less to remember in terms of special-purpose commands. However, in some cases, the code will run more slowly.

Accessing and manipulating the collection¶

Collection¶

Collection is a global containing a TacticCollection object corresponding to: the collection in the current project. self.collection can also be used.

class TacticCollection¶

Iterating over the TacticCollection object iterates over the documents in the collection, giving TacticDocument objects. These can also be accessed by name.

doc = Collection["doc_name"]  # Get the document named doc_name
for doc in Collection:  # iterate of over documents in the collection
    print(doc.name)

len(Collection)  # returns the number of documents in the collection
Collection[docname] = detached_doc  # adds or replaces a document to the collection
del Collection[docname]  # deletes the document from the collection

document_names¶: A list of the names of the documents in the collection.

current_document¶: A TacticDocument object corresponding to the currently visible document.

column(column_name)¶: Returns, as a list, the data in the specified column from all of the documents in the collection.

tokenize(column_name=None, tokenizer_func=None)¶

In table documents, applies tokenizer_func to each entry in the column column_name, in every document, and returns the result as a list.

In freeform documents, applies tokenizer_func to each line in every document and returns the result as a list.

If tokenizer_func is None then uses nltk.word_tokenize.

detach()¶: Returns a DetachedTacticCollection with the data corresponding to this collection.

rewind()¶: Reset the iterator to the first document.

class TacticDocument¶

Objects in this class correspond to one of the documents in the collection in the current project. It is only for table documents. Freeform documents have their own class, FreeformTacticDocument described below.

Keep in mind that modifying rows in a TacticDocument object modify the collection within the current project.

Iterating over a document iterates over the rows.

doc = self.collection.current_document
doc[3]  # Gets the third row in the document as a TacticRow
doc[3] = new_row  # new_row can be either a dict or a TacticRow
doc[3:5]  # Gets the third and fourth rows
del doc[3]  # Deletes the third row
len(doc)  # Returns the number of rows

It is possible to change a row in the document by assigning it to a new value. In the following, new_row can be a TacticRow, a DetachedTacticRow, or a dict.

doc[3] = new_row

name¶: The name of the document.

metadata¶

A dictionary with the metadata for the document.

Writing self.metadata = a_dictionary sets the metadata to the provided dictionary.

column_names¶: A list of the column_names for the document.

df¶: Returns the document as a pandas DataFrame.

insert(index, detached_row_or_row_dict)¶: Inserts a new row at the specified index. The new row can either be a DetachedTacticRow or a dict.

column(column_name)¶: Returns, as a list, the data in the specified column.

dict_list¶: The contents of the document as a list of dictionaries.

get_matching_rows(filter_function)¶: Returns a list of rows meeting the requirement in filter_function. filter_function should expect a TacticRow as an argument, and it should return True or False. See get_matching_rows().

tokenize(column_name, tokenizer_func=None)¶: Applies tokenizer_func to each entry in the column column_name and returns the result as a list. If tokenizer_func is None then uses nltk.word_tokenize.

set_column_data(column_name, column_data, cellchange=False)¶: Sets the column in the document using column_data. column_data can be either a dict or a list. If it’s a dict, then the keys are interpreted as the row_id. If it’s a list, then the ordinal position in the list is interpreted as the row_id. See set_column_data().

to_html(title=None, click_type="word-clickable", sortable=True, sidebyside=False, has_header=True,
max_rows=None, header_style=None, body_style=None,
column_order=None, include_row_labels=False): Returns an html table for the document. See html_table()

detach()¶: Returns a DetachedTacticDocument object with the data in this document.

rewind()¶: Reset the iterator to the first row.

class TacticRow¶

Objects in this class correspond to a row in one of the the documents in the current project. Keep in mind that changes to a row will be reflected in the project’s table.

The fields in a row can be accessed either as attributes or items.

doc = self.collection.current_document
a_row = doc[3]  # Get a TacticRow corresponding to the third row
a_row["some_column"]  # Returns the value in the field some_column
a_row.some_column  #  Also returns the value in the field some_column
a_row["some_column"] = "This is some text"  #  Sets the field
a_row.some_column = "This is some text"  # Also sets the field

row_dict¶: A dictionary with the data corresponding to the row.

series¶: Returns the row as a pandas Series.

detach()¶: Returns a DetachedTacticRow object with the data in this document.

class FreeformTacticDocument¶

This is the document object class for freeform collections.

Iterating over a FreeformTacticDocument document object iterates over the lines.

doc = self.collection.current_document
doc[3]    # Returns the third line
doc[3:5]  # Gets the third and fourth lines
len(doc)  # Returns the number of lines

text¶: The text of the entire current document as a string.

line_list¶: A list of TacticLine objects corresponding to the lines in the document.

metadata¶

A dictionary with the metadata for the document.

Writing self.metadata = a_dictionary sets the metadata to the provided dictionary.

tokenize(tokenizer_func=None)¶: Applies tokenizer_func to each line and returns the result as a list. If tokenizer_func is None then uses nltk.word_tokenize.

download(file_name=None)¶: Downloads the text of the document to the local client.

rewind()¶: Resets the iterator to the first line.

class TacticLine¶

Objects in this class correspond to a line in one of the the documents in a freeform project. Keep in mind that changes to a row will be reflected in the project’s table.

doc = self.collection.current_document
my_line = doc[3]
my_line[5]  # Gives the fifth character in the line.

text¶: The text of the line as a string.

Creating and manipulating detached data¶

The above classes all provide access to classes that are directly linked to the collection in the current project. This means, for example, that if you change a row, you will see that change reflected in the table.

However, in some cases you will want to work with data that is not connected to the current collection. For this purpose, there are “detached” versions of each of the classes described above.

class DetachedTacticCollection¶

A DetachedTacticCollection can be created either via the .detach() method of project collection or using the create_collection_object() method of TileBase.

dcollection = self.create_collection_object("table")
dcollection["new_document"] = a_detached_document  # Adds a new document to the collection
dcollection["new_document"]  # Returns the document
len(dcollection)  # Returns the number of documents
for doc in dcollection:  # Iterate over documents
    print(doc.name)

dcollection += other_dcollection  # Updates dcollection with the documents in other_dcollection
new_collection = dcollection + other_collection  # Combines dcollection and other_collection in a new collection

document_names¶: A list of the names of the documents in the collection.

append(detached_tactic_document)¶: Adds the specified DetachedTacticDocument object to the collection.

column(column_name)¶: Returns, as a list, the data in the specified column from all of the documents in the collection.

update(other_collection)¶: This works like a dictionary update. other_collection can be a DetachedTacticCollection or a TacticCollection.

rewind()¶: Reset the iterator to the first document.

add_to_library(collection_name)¶: Creates a new collection in the user’s library, with the name collection_name, with all of the data in the collection.

class DetachedTacticDocument(TacticDocument)¶

A DetachedTacticDocument can be created either via the .detach() method of a TacticDocument or using the create_document() method of TileBase.

Note that this class inherits from TacticDocument.

new_doc = self.collection.current_document.detach()
new_doc += other_detached_doc  # Appends the row of other-detached_doc
doc[3] = new_row  # new_row can be either a dict or a DetachedTacticRow
new_doc

name¶: The name of the document. The name can be set with doc.name = new_name.

add_column(column_name)¶: Adds a new column with the given name. The value of the corresponding field in all rows will be initialized to None.

append(detached_row)¶: Appends the DetachedTacticRow object to the collection.

insert(position, element)¶: Inserts the element in the specified position. Element can be either a DetachedTacticRow or a dict.

class DetachedTacticRow¶

A DetachedTacticDocument can be created either via the .detach() method of a TacticRow or using the create_row() method of TileBase.

row_dict¶: A dictionary with the data corresponding to the row.

series¶: Returns the row as a pandas Series.

The fields in a row can be accessed and set just as in a TacticRow:

doc = self.collection.current_document
a_row = doc[3].detach()  # Get a DetachedTacticRow corresponding to the third row
a_row["some_column"]  # Returns the value in the field some_column
a_row.some_column  #  Also returns the value in the field some_column
a_row["some_column"] = "This is some text"  #  Sets the field
a_row.some_column = "This is some text"  # Also sets the field

Fields can also be deleted:

del arow["some_column"]
del arow.some_column

class DetachedFreeformTacticDocument(FreeformTacticDocument)¶

A DetachedFreeformTacticDocument can be created either via the .detach() method of a TacticDocument or using the create_freeform_document() method of TileBase.

Note that this class inherits from FreeformTacticDocument.

new_doc = self.collection.current_document.detach()
new_doc += other_detached_freeform_doc  # Appends the row of other-detached_doc
doc[3] = new_line  # new_line can be either a str or a DetachedTacticLine

name¶: The name of the document. The name can be set with doc.name = new_name.

append(detached_line)¶: Appends the DetachedTacticLine object to the collection.

class DetachedTacticLine¶

A DetachedTacticDocument can be created either via the .detach() method of a TacticLine or using the create_line() method of TileBase.

dline = self.collection.current_document[3]
dline[5]  # Returns the fifth character

text¶: The text of the line as a string. Also, dline.text = new_text sets the text of the line.

Communicating with other tiles¶

These classes provide a means of communicating with tiles other than the one within which code is executing.

Tiles¶

Tiles is a global containing a RemoteTiles object corresponding to: the tiles in the current project. self.tiles can also be used.

class RemoteTiles¶

Iterating over this object iterates over the tiles in the project, giving RemoteTile objects. These can also be accessed by name.

len(Tiles)  # returns the number of other tiles
Tile["tile_name"]  # returns a RemoteTile object corresponding to the tile
for tile in Tiles:  # iterate of over tiles in the project
    print(tile.name)

names¶: A list of the names of other tiles in the project.

rewind()¶: Reset the iterator.

class RemoteTile¶

Object corresponding to another tile in a project.

You can ask a tile for a pipe value as in the code below.

other_tile = Tiles["other_tile_name"]
pipe_value = other_tile["pipe_name"]

name¶: The name of the tile.

pipe_names¶: A list of the names of the pipes (exports) of the tile.

pipe_tags¶: A dict where the keys are the names of the pipes, and the values are the tags associated with those pipes.

tile_id¶: The id of this tile.

send_message(event_name, data=None, callback_func=None)¶: Send a message from the tile in which the code is executing to this RemoteTile object. Refer to py:meth:send_tile_message.

The Pipes Object¶

Pipes¶

Pipes is a global containing a RemotePipes object corresponding to: the pipes in the current project.

class RemotePipes¶

This class provides easy access to pipe values.

Pipes.names  # Returns the keys for all of the pipes
Pipes["pipe_key"]  # Returns the value of the pipe

names¶: Returns the keys for all of the pipes.

The Library Object¶

These classes provide access to the resources in a user’s library.

Library¶

Library is a global containing a TacticLibrary object corresponding to: the user’s library.

class TacticLibrary¶

Library returns a TacticLibrary object corresponding to the user’s library.

collections¶: Returns a TacticCollectionSet object corresponding to a user’s collection resources

lists¶: Returns a TacticListSet object corresponding to a user’s list resources

functions¶: Returns a TacticFunctionSet object corresponding to a user’s function resources

classes¶: Returns a TacticClassnSet object corresponding to a user’s class resources

Library.lists  # Returns a TacticListSet object corresponding to a user's list resources
Library.lists.names()  # Returns a list of the names of all list resources.

class TacticListSet¶

Object corresponding to a user’s list resources.

my_lists = Library.lists
my_lists.names()  # Returns the names of all list resources
my_lists["list_name"]  # Returns ListResource object corresponding to the list

names(tag_filter=None, search_filter=None)¶: Returns the names of the user’s list resources. If tag_filter or search_filter are specified, then the results are filtered accordingly. (This behaves just as it does when typing into the corresponding fields in the library interface.)

class ListResource(list)¶

Corresponds to an item in the list library. It behaves just like a list except that it has a metadata attribute.

my_list = Library.lists["list_name"]
my_list.metadata

metadata¶: Returns the ListResource’s metadata

class TacticCollectionSet¶

Object corresponding to a user’s collection resources.

my_collections = Library.collections
my_collections.names()  # Returns the names of all list resources
my_collection["collection _name"]  # Returns DetachedTacticCollection object corresponding to the collection

names(tag_filter=None, search_filter=None)¶: Returns the names of the user’s collection resources. If tag_filter or search_filter are specified, then the results are filtered accordingly. (This behaves just as it does when typing into the corresponding fields in the library interface.)

class TacticFunctionSet¶

Object corresponding to a user’s function resources.

my_functions = Library.functions
my_functions.names()  # Returns the names of all function resources
afunc = my_functions["function_name"]  # Returns FunctionResource object corresponding to the function
afunc(arguments)  # executes the function on the arguments

names(tag_filter=None, search_filter=None)¶: Returns the names of the user’s function resources. If tag_filter or search_filter are specified, then the results are filtered accordingly. (This behaves just as it does when typing into the corresponding fields in the library interface.)

class FunctionResource¶

Corresponds to a function library resource. It should be have like a function, except it has a couple of attributes, as noted below.

afunc = my_functions["function_name"]  # Returns FunctionResource object corresponding to the function
afunc(arguments)  # executes the function on the arguments

metadata¶: Returns the FunctionResource’s metadata

code_resource¶: Returns the the name of the code resource containing the function.

The Settings Object¶

This object provides easy access to user’s account-level settings.

Settings¶

Settings is a global containing a TacticSettings object corresponding to: the user’s settings.

class TacticSettings¶

Settings.names  # Returns the keys for all of the settings
Settings["theme"]  # Returns the value of the setting "theme"

names¶: Returns the keys for all of the settings.