Flow Reference Guide

Warning

Documentation in Progress…

The Flow let you model you project structure, pipeline and tracking strategies.

< insert introductionnal description here >

Exceptions

exception kabaret.flow.MissingChildError(oid, child_name)[source]
exception kabaret.flow.MissingRelationError(oid, relation_name)[source]
exception kabaret.flow.RefSourceTypeError[source]
exception kabaret.flow.RefSourceError(ref_oid, source_oid)[source]

Object

class kabaret.flow.Object(parent, name)[source]
child_value_changed(child_value)[source]

Called when a watched child Value has changed. See relations.Param.watched() and values.Value.watch()

compute_child_value(child_value)[source]

Called when a ComputeValue child need its value to be computed.

This happens when a computed value was touched before someone asks for its value.

You must set the result of the computation to the child_value.

classmethod get_source_display(oid)[source]

Returns the text to display when showing a Ref pointing to the object of type cls with the id oid.

This is used by Connection relations’ GUI.

touch()[source]

Force notification that the object has changed.

class kabaret.flow.SessionObject(parent, name)[source]

The SessionObject overrides its default value store with a MemoryValueStore() (all value die when the session ends)

As the default value store is inherited by parent Objects, the whole branch under this one will also be “in memory only”.

class kabaret.flow.ThumbnailInfo(parent, name)[source]

This object defines the interface needed to provide “object image view” in the GUI.

You define an object’s thumbnail by defining its get_thumbnail_object() method and returning a related ThumbnailInfo instance:

class MyObject(Object):

_thumbnail = Child(MyThumbnailIn)
get_default_height()[source]

Returns the default height of the thumbnail when first show in GUI.

get_first_last_fps()[source]

If is_sequence() returns True, this must return the index of the first and the last frames, and the frame per second rate

get_label()[source]

Returns the label to display on the thumbnail. A value of None will use the basename of the thumbnail source file.

get_path()[source]

Returns the path of the thumbnail source. If is_sequence() returns True, the path must contain a formater for the frame number:

/path/to/my/images.%04d.jpg

Supported images types are roughtly the same as a standard webbrowser. (I.e: no EXP support here.)

get_resource()[source]
If is_resource() returns True, this must return a 2d string:
resource_folder_name, resource_name
is_image()[source]

Must return True if your thumbnail source is a single image. If this returns True, does methods need to be implemented:

get_default_heigth() get_label() get_path()
is_resource()[source]

Must return True if your thumbnail source is a resource file. If this returns True, does methods need to be implemented:

get_default_heigth() get_label() get_resource()
is_sequence()[source]

Must return True if your thumbnail source is a sequence of images. If this returns True, does methods need to be implemented:

get_default_heigth() get_label() get_path() get_first_and_last()

Relations

class kabaret.flow.object._Relation(related_type)[source]

This is the base class of all relations. You must use one of the subclasses.

Relations are descriptors managing the instantiation and the access to object related to the relation owner.

You can configure the relation behavior using the ui() and editor() methods.

ui(icon=None, editor=None, editable=None, label=None, group=None, hidden=None, tooltip=None, expanded=None, expandable=None, **editor_options)[source]

Configure the relation GUI. This method returns self so that you can chain it in assigment:

meh = MyRelation('example').ui(label='Amazing')
class kabaret.flow.Child(related_type)[source]

The Child relation sets an Object as the Child of the owner of the relation (wich in turn becomes the parent)

class kabaret.flow.Parent(nb_levels=1)[source]

The Parent relation give access to the related object’s parent or grand-parents.

get_ui(of=None)[source]

Overridden to return the ui of the parented Object. See the _Relation.get_ui() class in flow.object.

class kabaret.flow.Param(default_value=None, value_type=None)[source]

A Child relating to a Value or one of its subclasses.

watched(b=True)[source]

Configures the related value to be watched or not (default is False). Watched value call their parent’s child_value_changed() when changed.

kabaret.flow.Separator()[source]

Returns a Param relation showing an horizontal line in GUI.

kabaret.flow.Label(text, label='')[source]

Returns a Param relation showing a (potentially html) text in GUI.

class kabaret.flow.SessionParam(default_value=None, value_type=None)[source]

A Param relating to a SessionValue.

class kabaret.flow.IntParam(default_value=None, value_type=None)[source]

A Param relating to an IntValue.

class kabaret.flow.BoolParam(default_value=None, value_type=None)[source]

A Param relating to a BoolValue.

class kabaret.flow.FloatParam(default_value=None, value_type=None)[source]

A Param relating to a FloatValue.

class kabaret.flow.StringParam(default_value=None, value_type=None)[source]

A Param relating to a StringValue.

class kabaret.flow.DictParam(default_value=None, value_type=None)[source]

A Param relating to a DictValue.

class kabaret.flow.OrderedStringSetParam(value_type=None)[source]

A Param relating to an OrderedStringSetValue.

class kabaret.flow.HashParam(value_type=None)[source]

A Param relating to a HashValue.

class kabaret.flow.Computed(cached=False, store_value=False, computed_value_type=None)[source]

A Param relating to a ComputedValue

The value computation is delegated to the parent’s compute_child_value() method. The ‘cached’ and ‘store_value’ constuctor arguments will configure the ComputedValue. (See kabaret.flow.values.ComputedValue)

You can use a subclass of ComputedValue by specifying computed_value_type in the constructor

class kabaret.flow.Connection(related_type=None, ref_type=None)[source]

A Child relating to a Ref subclass.

watched(b=True)[source]

Configures the related value to be watched or not (default is False). Watched value call their parent’s child_value_changed() when changed.

Values

class kabaret.flow.values.Value(parent, name)[source]
DEFAULT_EDITOR = None
ICON = 'value'
get()[source]
notify()[source]

Subclasses can override this to do something after values change. Default implementation calls ‘child_value_changed’ in the parent object if self._watched is True.

revert_to_default()[source]
set(value)[source]
set_default_value(value)[source]
set_watched(b)[source]
class kabaret.flow.values.SessionValue(parent, name)[source]

This Value does not store itself in the value store. It will reset to its default value for each session.

get()[source]
set(value)[source]
set_default_value(value)[source]
class kabaret.flow.values.IntValue(parent, name)[source]
DEFAULT_EDITOR = 'int'
decr(by=1)[source]
incr(by=1)[source]
set(value)[source]
validate(value)[source]
class kabaret.flow.values.BoolValue(parent, name)[source]
DEFAULT_EDITOR = 'bool'
set(value)[source]
validate(value)[source]
class kabaret.flow.values.FloatValue(parent, name)[source]
DEFAULT_EDITOR = 'float'
set(value)[source]
validate(value)[source]
class kabaret.flow.values.StringValue(parent, name)[source]
DEFAULT_EDITOR = 'string'
set(value)[source]
validate(value)[source]
class kabaret.flow.values.DictValue(parent, name)[source]
DEFAULT_EDITOR = 'mapping'
set(value)[source]
validate(value)[source]
class kabaret.flow.values.OrderedStringSetValue(parent, name)[source]

A list off string ordered by score. You cant set that value, you can only edit it.

DEFAULT_EDITOR = 'set'
add(member, score)[source]
get()[source]
get_range(first, last)[source]
get_score(member)[source]
has(member)[source]
len()[source]
remove(member)[source]
revert_to_default()[source]
set(value)[source]
set_default_value(value)[source]
set_score(member, score)[source]
class kabaret.flow.values.HashValue(parent, name)[source]
DEFAULT_EDITOR = 'mapping'
as_dict()[source]
del_key(key)[source]
get()[source]
get_key(key)[source]
has_key(key)[source]
keys()[source]
len()[source]
set(value)[source]
set_key(key, value)[source]
update(**new_values)[source]
validate(value)[source]
class kabaret.flow.values.ComputedValue(parent, name)[source]
compute()[source]

Subclasses can override this to compute the value (and call set()). Default implementation calls ‘compute_child_value’ in the parent object.

get()[source]
set(value)[source]
set_cached(b)[source]
set_store_value(b)[source]
touch()[source]

Force notification that the object has changed.

class kabaret.flow.values.ChoiceValue(parent, name)[source]

This Value provides a list of potential/acceptable values. You can set the CHOICE class attribute to define this list.

If STRICT_CHOICES is True, the value must exists in the CHOICES attribute or a ValueError will be raised by set() If STRICT_CHOICES is False, any value can do.

CHOICES = []
DEFAULT_EDITOR = 'choice'
STRICT_CHOICES = True
choices()[source]
set(value)[source]
class kabaret.flow.values.MultiChoiceValue(parent, name)[source]

A MultiChoiceValue is like a Choice but stores a list of those acceptable values.

DEFAULT_EDITOR = 'multichoice'
add(extra_choice)[source]
set(value)[source]
class kabaret.flow.values.Ref(parent, name)[source]

A Ref stores a reference to an Object. The set() method accepts only Object of the type (or list of types) in SOURCE_TYPE class attribute. The get() method returns the Object. If you only need the Object’s oid, use get_source_oid() as it does not require object lookup.

DEFAULT_EDITOR = 'ref'
ICON = 'ref'
SOURCE_TYPE = None
can_set(source_object)[source]
get()[source]
get_source_oid()[source]
static resolve_refs(object)[source]
set(new_source_object)[source]
source_touched()[source]
source_value_changed(old_value, new_value)[source]

Actions

class kabaret.flow.Action(parent, name)[source]
allow_context(context)[source]

Override this to control where the action will be accessible. Return True to allow the action in the given context, False to disallow it, and None to fall back to legacy behavior (SHOW_IN_PARENT_* class attributes)

Default is to return None.

Parameters:context – string. the context fetching the actions to show.

Usually the type name of the View, optionally followed by sub-categories. The built-in Flow view will send:

Flow.details the action’s parent details representation Flow.inline the action’s parent inline representation Flow.indline>>> the inline representation of (the number of ‘>’ depicts the depth of the inline action)
Returns:True/False/None
get_buttons()[source]

Returns a list of string suitable as the ‘button’ argument for a call to self.run().

NB: If the action cannot run, you should set a desciption why in self.message, return [‘Cancel’] and handle that in run(). This is far better than returning False from needs_dialog() or let the run() method decide to do nothing since the user will not have a clear feedback showing that nothing happened…

classmethod get_result(close=None, refresh=None, goto=None, goto_target=None, goto_target_type=None, next_action=None)[source]

The value returned by run(button) will be inspected by callers to decide how they should react. This helper class method will generate a result matching its args:

close: (bool)
Prevent the action dialog to be closed when set to False
refresh: (bool)
Force a reload of the parent page avec dialog close (This should not be needed anymore thanks to touch() calls…)
goto: (oid)
Force the caller to load the given oid page.
goto_target: (string or “_NEW_”)
The string identifer of the view targeted by the goto directive. The default targeted view is the current one or the one that created the action dialog. Spcecifying a target can be usefull to alter another view. If the specified target is not found, a new view will be created with this identifier so that further use of the action will affect this new view. The special identifier “_NEW_” can be used to force the creation of a new view.
goto_target_type: (string)
The type of the view targeted by the goto directive. Default is ‘Flow’ An easy way to find out the available type names is to use a obviously invalid value like “???” and look for the error message: it will contain a list of available type names.
next_action: (oid)
Force the dialog to not close but load the ui for the action with the given oid. This is the way to implement “Wizard Pages”
needs_dialog()[source]

May be overriden by subclasses to return False if the action does not need to show a dialog. Action without dialog are called with run(button=None), plus the ‘goto’ and ‘next_action’ fields of the returned value do the same.

NB: If the action cannot run, it should show a dialog with a desciption why in self.message (override get_button() to do so).

run(button)[source]

The return value should be None or the return value of a self.get_result() call. GUI will inspect the returned value and act upon it.

class kabaret.flow.ConnectAction(parent, name)[source]
Subclasses will want to overwrite those methods:
  • accept_label:
    return the label to show in GUI if the objects and urls are acceptable, None otherwise.
  • run:
    to do the job.

The run method is guaranted to be called only if accept_label did not return None.

class kabaret.flow.ChoiceValueSetAction(parent, name)[source]
needs_dialog()[source]

May be overriden by subclasses to return False if the action does not need to show a dialog. Action without dialog are called with run(button=None), plus the ‘goto’ and ‘next_action’ fields of the returned value do the same.

NB: If the action cannot run, it should show a dialog with a desciption why in self.message (override get_button() to do so).

run(button)[source]

The return value should be None or the return value of a self.get_result() call. GUI will inspect the returned value and act upon it.

class kabaret.flow.ChoiceValueSelectAction(parent, name)[source]
get_buttons()[source]

Returns a list of string suitable as the ‘button’ argument for a call to self.run().

NB: If the action cannot run, you should set a desciption why in self.message, return [‘Cancel’] and handle that in run(). This is far better than returning False from needs_dialog() or let the run() method decide to do nothing since the user will not have a clear feedback showing that nothing happened…

run(button)[source]

The return value should be None or the return value of a self.get_result() call. GUI will inspect the returned value and act upon it.

Maps

class kabaret.flow.Map(parent, name)[source]

A Map manages a per-instance list of children Objects.

add(name, object_type=None)[source]

Adds an object to the map. If provided, object_type must be a subclass of the map’s mapped_type (returned by the classmethod mapped_type())

bake_order()[source]

Stores a new mapped names order according to the _item_cmp() method. This should not be useful but in edge cases like you loaded the order from an external source and did not get a satisfying order in mapped items.

Note that this cannot express an order based on anything else than the mapped name.

child_value_changed(child_value)

Called when a watched child Value has changed. See relations.Param.watched() and values.Value.watch()

clear()[source]

Remove all Objects from the Map.

columns()

Returns the list of columns name. Subclasses may reimplement this and rows() to provide inline informations about the children.

Default is to return [‘Name’] which will contain the mapped object name in rows()

compute_child_value(child_value)

Called when a ComputeValue child need its value to be computed.

This happens when a computed value was touched before someone asks for its value.

You must set the result of the computation to the child_value.

current_page_num()

Subclasses must override this and page_size() to enable paging.

get_mapped(name)

Returns the item mapped under ‘name’, instanciating it if not yet done.

classmethod get_source_display(oid)

Returns the text to display when showing a Ref pointing to the object of type cls with the id oid.

This is used by Connection relations’ GUI.

classmethod mapped_type()

Returns the default (which is also be the base) type of the mapped objects. Subclasses may override this to specialize the children type.

Default is to return Object.

page_size()

Subclasses must override this and current_page_num() to enable paging.

remove(name)[source]

Removes an Object from the map.

row(item)

Returns one of the entry returned by rows:

(item_oid, cells_data)
rows()

Returns a list of

(oid, dict) 

per child in the order given by mapped_names(). All dicts must contains the keys found in self.columns() + an optional “_style” key.

Subclasses should not reimplement this but _fill_row_cells() and _fill_row_style() to customize table cells for the mapped items.

Default behavior is to return the ‘name’ keys only in rows.

The _style value in the row must be a dict with those optional keys:
  • icon: the icon in first column
  • background-color: the whole row background-color
  • foreground-color: the row font color
  • <col_name>_<property>: set the <property> style in column <col_name> (example: ‘name_icon’)
touch()

Force notification that the object has changed.

class kabaret.flow.DynamicMap(parent, name)[source]

A DynamicMap contains a procedural list of items. This list is computed every time its is needed.

One must subclass this an implement the methods:
mapped_names(self, page_num=0, page_size=None)
and optionnaly:
_get_mapped_item_type(self, mapped_name)
columns()[source]

Returns the list of columns name. Subclasses may reimplement this and rows() to provide inline informations about the children.

Default is to return [‘Name’] which will contain the mapped object name in rows()

current_page_num()[source]

Subclasses must override this and page_size() to enable paging.

get_mapped(name)[source]

Returns the item mapped under ‘name’, instanciating it if not yet done.

classmethod mapped_type()[source]

Returns the default (which is also be the base) type of the mapped objects. Subclasses may override this to specialize the children type.

Default is to return Object.

page_size()[source]

Subclasses must override this and current_page_num() to enable paging.

row(item)[source]

Returns one of the entry returned by rows:

(item_oid, cells_data)
rows()[source]

Returns a list of

(oid, dict) 

per child in the order given by mapped_names(). All dicts must contains the keys found in self.columns() + an optional “_style” key.

Subclasses should not reimplement this but _fill_row_cells() and _fill_row_style() to customize table cells for the mapped items.

Default behavior is to return the ‘name’ keys only in rows.

The _style value in the row must be a dict with those optional keys:
  • icon: the icon in first column
  • background-color: the whole row background-color
  • foreground-color: the row font color
  • <col_name>_<property>: set the <property> style in column <col_name> (example: ‘name_icon’)