Framework Concepts¶

Limitations¶

API Overview¶

The example application demonstrates some the features of the framework.

Module Level Objects¶

ScriptManager¶

IBindEvent¶

StartRecordingAction¶

StopRecordingAction¶

Implementing Application Scripting¶

Static Specification¶

from apptools.appscripting.api import scriptable, Scriptable
from traits.api import HasTraits, Int, Str
class DataModel(HasTraits):
    foo = Scriptable(Str)
    bar = Scriptable(Int, has_side_effects=True)
    @scriptable
    def baz(self):
        pass
    def weeble(self)
        pass
# Create the scriptable object.  It's creation won't be recorded because
# __init__() isn't decorated.
obj = DataModel()
# These will be recorded.
obj.foo = ''
obj.bar = 10
obj.baz()
# This will not be recorded.
obj.weeble()
# This won't be recorded unless 'f' is passed to something that is
# recorded.
f = obj.foo
# This will be recorded because we set 'has_side_effects'.
b = obj.bar

Dynamic Specification¶

from apptools.appscripting.api import create_scriptable_type
from traits.api import HasTraits, Int, Str
class DataModel(HasTraits):
    foo = Str
    bar = Int
    def baz(self):
        pass
    def weeble(self)
        pass
# Create a scriptable type based on the above.
ScriptableDataModel = create_scriptable_type(DataModel, excludes=['weeble'])
# Now create scriptable objects from the scriptable type.  Note that each
# object has the same type.
obj1 = ScriptableDataModel()
obj2 = ScriptableDataModel()

Instead we could bypass the type and make the objects themselves scriptable as follows:

from apptools.appscripting.api import make_object_scriptable
from traits.api import HasTraits, Int, Str
class DataModel(HasTraits):
    foo = Str
    bar = Int
    def baz(self):
        pass
    def weeble(self)
        pass
# Create unscriptable objects.
obj1 = DataModel()
obj2 = DataModel()
# Now make the objects scriptable.  Note that each object has a different
# type, each a sub-type of 'DataModel'.
make_object_scriptable(obj1, excludes=['weeble'])
make_object_scriptable(obj2, excludes=['weeble'])

With a more sophisticated design we may choose to specify the scriptable API as an interface as follows:

from apptools.appscripting.api import make_object_scriptable
from traits.api import HasTraits, Int, Interface, Str
class DataModel(HasTraits):
    foo = Str
    bar = Int
    def baz(self):
        pass
    def weeble(self)
        pass
class IScriptableDataModel(Interface):
    foo = Str
    bar = Int
    def baz(self):
        pass
# Create an unscriptable object.
obj = DataModel()
# Now make the object scriptable.
make_object_scriptable(obj, api=IScriptableDataModel)

Scripting __init__()¶

The disadvantage is that, if you have a complex data model, with many interdependencies, then defining a complete and consistent scripting API that allows a script to run independently may prove difficult. In such cases it is better to have the application create and bind the scriptable objects itself.

Framework Concepts¶

Framework APIs¶

The complete API documentation is available as endo generated HTML.

What Do I Need to Reimplement?¶

Q: Do you want to use roles to group permissions and assign them to users?

Q: Do you want users to be authenticated using a password?

Q: Do you want to store your user accounts as pickled data in a local file?

Deploying Alternative Managers¶

Specifically the framework looks for the following classes:

The example server is such a package that provides PolicyStorage and UserStorage implementations that use an XML-RPC based server to provide remote (and consequently more secure) policy and user databases.

Using the Default Storage Implementations¶

Note that this directory is normally in the user's own directory structure whereas it needs to be available to all users of the application.

If the ETS_PERMS_DATA_DIR environment variable is set then its value is used instead.

The directory must be writeable by all users of the application.

It should be restated that the default implementations do not provide secure access to the permissions and user data. They are useful in a cooperative environment and as working examples.

Defining Permissions¶

A permission has an id and a human readable description. Permission ids must be unique. By convention a dotted notation is used for ids to give them a structure. Ids should at least be given an application or plugin specific prefix to ensure their uniqueness.

Conventionally all an applications permissions are defined in a single permissions.py module. The following is an extract of the example's permissions.py module:

from apptools.permissions.api import Permission
# Add a new person.
NewPersonPerm = Permission(id='ets.permissions.example.person.new',
        description=u"Add a new person")
# Update a person's age.
UpdatePersonAgePerm = Permission(id='ets.permissions.example.person.age.update',
        description=u"Update a person's age")
# View or update a person's salary.
PersonSalaryPerm = Permission(id='ets.permissions.example.person.salary',
        description=u"View or update a person's salary")

Applying Permissions¶

Permissions can be applied to TraitsUI view items and to any object which can be wrapped in a SecureProxy.

TraitsUI View Items¶

In order for the view to be correctly updated when the user's permissions change (ie. when they become authenticated) the view must use the SecureHandler handler. This handler is a simple sub-class of the standard Traits Handler class.

The following extract from the example shows a default view of the Person object that enables the age item when the user has the UpdatePersonAgePerm permission and shows the salary item when the user has the PersonSalaryPerm permission:

from apptools.permissions.api import SecureHandler
from traits.api import HasTraits, Int, Unicode
from traitsui.api import Item, View
from permissions import UpdatePersonAgePerm, PersonSalaryPerm
class Person(HasTraits):
    """A simple example of an object model"""
    # Name.
    name = Unicode
    # Age in years.
    age = Int
    # Salary.
    salary = Int
    # Define the default view with permissions attached.
    age_perm = UpdatePersonAgePerm
    salary_perm = PersonSalaryPerm
    traits_view = View(
            Item(name='name'),
            Item(name='age', enabled_when='object.age_perm.granted'),
            Item(name='salary', visible_when='object.salary_perm.granted'),
            handler=SecureHandler)

Wrapping in a SecureProxy¶

Adapters are included for the following types of object:

See Writing SecureProxy Adapters for a description of how to write adapters for other types of objects.

The following extract from the example shows the wrapping of a standard PyFace action and the application of the NewPersonPerm permission:

from apptools.permissions.api import SecureProxy
from permissions import NewPersonPerm
...
    def _new_person_action_default(self):
        """Trait initializer."""
        # Create the action and secure it with the appropriate permission.
        act = Action(name='New Person', on_perform=self._new_person)
        act = SecureProxy(act, permissions=[NewPersonPerm])
        return act

A SecureProxy also accepts a show argument that, when set to False, hides the object when it becomes disabled.

Authenticating the User¶

The code fragment to authenticate the current user is:

from apptools.permissions.api import get_permissions_manager
get_permissions_Manager().user_manager.authenticate_user()

Unauthorising the current user is done using the unauthenticate_user() method.

As a convenience two PyFace actions, called LoginAction and LogoutAction, are provided that wrap these two methods.

As a further convenience a PyFace menu manager, called UserMenuManager, is provided that contains all the user and management actions (see below) in the permissions framework. This is used by the example.

The user menu, login and logout actions can be imported from apptools.permissions.action.api.

Getting and Setting User Data¶

The IUser interface has a blob trait that holds any binary data (as a Python string). The data will be read when the user is authenticated. The data will be written whenever it is changed.

Integrating Management Actions¶

User managers also have a user_actions trait that is a list of PyFace actions that invoke appropriate dialogs that allow the user to manage themselves. For example, the default user manager provides an action that allows a user to change their password.

The default policy manager provides actions that allows roles to be defined in terms of sets of permissions, and allows users to be assigned one or more roles.

The default user manager provides actions that allows users to be added, modified and deleted. A user manager that integrates with an enterprise's secure directory service may not provide any management actions.

All management actions have appropriate permissions attached to them.

Writing SecureProxy Adapters¶

Adapters tend to be one of two styles according to how the object's enabled and visible states are changed. If the states are changed via attributes (typically Traits based objects) then the adapter will cause a proxy to be created for the object. If the states are changed via methods (typically toolkit widgets) then the adapter will probably modify the object itself. We will refer to these two styles as wrapping adapters and patching adapters respectively.

The following gives a brief overview of the AdapterBase class:

The AdapterBase class is defined in adapter_base.py.

The PyFace action adapter is an example of a wrapping adapter.

The PyQt widget adapter is an example of a patching adapter.

Overview of IPolicyStorage¶

In the event of an error a method must raise the PolicyStorageError exception. The string representation of the exception is used as an error message that is displayed to the user.

Overview of IUserStorage¶

In the event of an error a method must raise the UserStorageError exception. The string representation of the exception is used as an error message that is displayed to the user.

Overview of IUserDatabase¶

Each of these capability traits has a corresponding method which has the same name except for the can_ prefix. The method only needs to be implemented if the corresponding traits is True. The method, for example add_user() is called by the user manager to implement the capability.

The interface has two other methods.

The bootstrapping() method is called by the user manager to determine if the database is bootstrapping. Typically this is when the database is empty and no users have yet been defined. The permissions framework treats this situation as a special case and is able to relax the enforcement of permissions to allow users and permissions to be initially defined.

The user_factory() method is called by the user manager to create a new user object, ie. an object that implements the IUser interface. This allows an implementation to extend the IUser interface and store additional user related data in the object if the blob trait proves insufficient.

Strings, Glorious Strings¶

>>> preferences.get('acme.ui.width')
'50'
>>> preferences.set('acme.ui.width', 100)
>>> preferences.get('acme.ui.width')
'100'
>>> preferences.get('acme.ui.visible')
'True'
>>> preferences.set('acme.ui.visible', False)
>>> preferences.get('acme.ui.visible')
'False'

This is obviously not terribly convenient, and so the following section discusses how we associate type information with our preferences to make getting and setting them more natural.

Accessing a particular scope¶

>>> preferences.set('default/acme.ui.bgcolor', 'red')
>>> preferences.get('default/acme.ui.bgcolor')
'red'
>>> preferences.dump()
  Node() {}
    Node(application) {}
      Node(acme) {}
        Node(ui) {'bgcolor': 'red', 'ratio': '1.0', 'width': '50', 'visible': 'True'}
          Node(splash_screen) {'image': 'splash', 'fgcolor': 'red'}
    Node(default) {}
      Node(acme) {}
        Node(ui) {'bgcolor': 'red'}

You can also get hold of a scope via:

>>> default = preferences.get_scope('default')

And then perform any of the usual operations on it.

The scripting API¶

The quickest way to get started is to look at a small example.

A tour by example¶

from traits.api import (HasTraits, Float, Instance,
        Str, List, Bool, HasStrictTraits, Tuple, Range, TraitPrefixMap,
        Trait)
from apptools.scripting.api import (Recorder, recordable,
    set_recorder)
class Property(HasStrictTraits):
    color = Tuple(Range(0.0, 1.0), Range(0.0, 1.0), Range(0.0, 1.0))
    opacity = Range(0.0, 1.0, 1.0)
    representation = Trait('surface',
                           TraitPrefixMap({'surface':2,
                                           'wireframe': 1,
                                           'points': 0}))
class Toy(HasTraits):
    color = Str
    type = Str
    # Note the use of the trait metadata to ignore this trait.
    ignore = Bool(False, record=False)
class Child(HasTraits):
    name = Str('child')
    age = Float(10.0)
    # The recorder walks through sub-instances if they are marked
    # with record=True
    property = Instance(Property, (), record=True)
    toy = Instance(Toy, record=True)
    friends = List(Str)
    # The decorator records the method.
    @recordable
    def grow(self, x):
        """Increase age by x years."""
        self.age += x
class Parent(HasTraits):
    children = List(Child, record=True)
    recorder = Instance(Recorder, record=False)

Using these simple classes we first create a simple object hierarchy as follows:

p = Parent()
c = Child()
t = Toy()
c.toy = t
p.children.append(c)

Given this hierarchy, we'd like to be able to record a script. To do this we setup the recording infrastructure:

from mayavi.core.recorder import Recorder, set_recorder
# Create a recorder.
r = Recorder()
# Set the global recorder so the decorator works.
set_recorder(r)
r.register(p)
r.recording = True

The key method here is the r.register(p) call above. It looks at the traits of p and finds all traits and nested objects that specify a record=True in their trait metadata (all methods starting and ending with _ are ignored). All sub-objects are in turn registered with the recorder and so on. Callbacks are attached to traits changes and these are wired up to produce readable and executable code. The set_recorder(r) call is also very important and sets the global recorder so the framework listens to any functions that are decorated with the recordable decorator.

Now lets test this out like so:

# The following will be recorded.
c.name = 'Shiva'
c.property.representation = 'w'
c.property.opacity = 0.4
c.grow(1)

To see what's been recorded do this:

print r.script

This prints:

child = parent.children[0]
child.name = 'Shiva'
child.property.representation = 'wireframe'
child.property.opacity = 0.40000000000000002
child.grow(1)

The recorder internally maintains a mapping between objects and unique names for each object. It also stores the information about the location of a particular object in the object hierarchy. For example, the path to the Toy instance in the hierarchy above is parent.children[0].toy. Since scripting with lists this way can be tedious, the recorder first instantiates the child:

child = parent.children[0]

Subsequent lines use the child attribute. The recorder always tries to instantiate the object referred to using its path information in this manner.

To record a function or method call one must simply decorate the function/method with the recordable decorator. Nested recordable functions are not recorded and trait changes are also not recorded if done inside a recordable function.

NOTE:

To stop recording do this:

r.unregister(p)
r.recording = False

The r.unregister(p) reverses the r.register(p) call and unregisters all nested objects as well.

Advanced use cases¶

For more details on the recorder itself we suggest reading the module source code. It is fairly well documented and with the above background should be enough to get you going.

Framework Concepts¶

Typically an application will have one undo manager and one undo stack for each data type that can be edited. However this is not a requirement: how the command stack's in particular are organised and linked (with the user manager's sequence number) can need careful thought so as not to confuse the user - particularly in a plugin based application that may have many editors.

To support this typical usage the PyFace Workbench class has an undo_manager trait and the PyFace Editor class has a command_stack trait. Both are lazy loaded so can be completely ignored if they are not used.

API Overview¶

The example application demonstrates all the major features of the framework.

UndoManager¶

CommandStack¶

ICommand¶

AbstractCommand¶

CommandAction¶

UndoAction¶

RedoAction¶

The SelectionService object¶

Selection providers are components that wish to publish information about their current selection for public consumption. They register to a selection service instance when they first have a selection available (e.g., when the UI showing a list of selectable items is initialized), and un-register as soon as the selection is not available anymore (e.g., the UI is destroyed when the windows is closed).

Selection listeners can query the selection service to get the current selection published by a provider, using the provider unique ID.

The service acts as a broker between providers and listeners, making sure that they are notified when the selection event is fired.

Selection providers¶

Selection providers must provide a unique ID provider_id, which is used by listeners to request its current selection.

Whenever its selection changes, providers fire a selection event. The content of the event is an instance implementing ISelection that contains information about the selected items. For example, a ListSelection object contains a list of selected items, and their indices.

Selection providers can also be queried directly about their current selection using the get_selection method, and can be requested to change their selection to a new one with the set_selection method.

Registration¶

Typically, selection providers are UI objects showing a list or tree of items, they register as soon as the UI component is initialized, and un-register when the UI component disappears (e.g., because their window has been closed). In more complex applications, the registration could be done by a controller object instead.

Selection listeners¶

Passive listening¶

It is possible for a listener to connect to a provider ID before it is registered. As soon as the provider is registered, the listener will receive a notification containing the provider's initial selection.

To disconnect a listener use the methods disconnect_selection_listener.

Active querying¶

The get_selection method calls the corresponding method on the provider with the given ID and returns an ISelection instance.

Setting a selection¶

If the items specified in the arguments are not available in the provider, a ProviderNotRegisteredError is raised, unless the optional keyword argument ignore_missing is set to True.

API Reference¶

apptools.selection Package¶

selection_service Module¶

i_selection_provider Module¶

is_selection Module¶

list_selection Module¶

errors Module¶