Creating Plugins for PsychoPy^®¶

Naming plugin packages¶

Standalone plugins, which are packages that exist only to extend PsychoPy^® should adhere to the following naming convention to make PsychoPy^® plugins discernible from any other package in public repositories. Plugin project names should always be prefixed with psychopy with individual words separated with a - or _ symbol (i.e. psychopy-quest-procedure or psychopy_quest_procedure are valid). What you chose to name the package is up to you, but keep it concise and informative.

The module or sub-package which defines the objects which entry points refer to should be some variant of the name to prevent possible namespace conflicts. For instance, we would name our module psychopy_quest_procedure if our project was called psychopy-quest-procedure.

Specifying entry points¶

Entry points reference objects in a plugin module that PsychoPy^® will attach to itself. Packages advertise their entry points by having them in their metadata. How entry points are defined and added to package metadata is described in the section Dynamic Discovery of Services and Plugins of the documentation for setuptools.

When loading a specified plugin, the plugin loader searches for a distribution matching the given project name, then gets the entry point mapping from its metadata. Any entry point belonging to groups whose names start with psychopy is loaded. Group names are fully-qualified names of modules or unbound classes within PsychoPy’s namespace to create links to the associated entry points in the plugin module/package.

As an example, using entry point groups and specifiers, we can add a class called MyStim defined in the plugin module psychopy_plugin to appear in psychopy.visual when the plugin is loaded. To do this, we use the following dictionary when defining entry point metadata with the setup() function in the plugin project’s setup.py file:

setup(
    ...
    entry_points={'psychopy.visual': 'MyStim = psychopy_plugin:MyStim'},
    ...
)

If we have additional classes we’d like to add to psychopy.visual, entry entry points for that group can be given as a list of specifiers:

setup(
    ...
    entry_points={
    'psychopy.visual': ['MyStim = psychopy_plugin:MyStim',
                        'MyStim2 = psychopy_plugin:MyStim2']
    },
    ...
)

For more complex (albeit contrived) example to demonstrate how to modify unbound class attributes (ie. methods and properties), say we have a plugin which provides a custom interface to some display hardware called psychopy-display that needs to alter the existing flip() method of the psychopy.visual.Window class to work. Furthermore, we want to add a class to psychopy.hardware called DisplayControl to give the user a way of setting up and configuring the display. Entry points for both objects are defined in the plugin’s psychopy_display module. To get the effect we want, we specify entry points using the following:

setup(
    ...
    entry_points={
        'psychopy.visual.Window': ['flip = psychopy_display:flip'],
        'psychopy.hardware': ['DisplayControl = psychopy_display:DisplayControl']},
    ...
)

After calling loadPlugin('psychopy-display'), the user will be able to create instances of psychopy.hardware.DisplayControl and new instances of psychopy.visual.Window will have the modified flip() method.

The __register__ attribute¶

Plugin modules can define a optional attribute named __register__ which specifies a callable object. The purpose of __register__ is to allow the module to perform tasks before loading entry points based on arguments passed to it by the plugin loader. The arguments passed to the target of __register__, come from the **kwargs given to loadPlugins(). The value of this attribute can be a string of the name or a reference to a callable object (ie. function or method).

As an example, consider a case where an entry point is defined as doThis in plugin python-foobar. There are two possible behaviors which are foo and bar that dothis can have. We can implement both behaviors in separate functions, and use arguments passed to the __register__ target to assign which to use to as the entry point:

__register__ = 'register'

doThis = None

def foo():
    return 'foo'

def bar():
    return 'bar'

def register(**kwargs):
    global dothis
    option = kwargs.get('option', 'foo')
    if option == 'bar':
        dothis = bar
    else:
        dothis = foo

When the user calls loadPlugin('python-foobar', option='bar'), the plugin will assign function bar()` to doThis. If option is not specified or given as ‘foo’, the behavior of doThis will be that of foo().

Project files¶

First, we need to create a directory called psychopy-rect-area which all our Python packages and code will reside. Inside that directory, we create the following files and directories:

psychopy-rect-area/
    psychopy_rect_area/
        __init__.py
    MANIFEST.in
    README.md
    setup.py

The implementation for the getArea() method will be defined in a file called psychopy_rect_area/__init__.py, it should contain the following:

#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""Plugin entry points for `psychopy-rect-area`."""

def get_area(self):
    """Compute the area of a `Rect` stimulus in `units`.

    Returns
    -------
    float
        Area in units^2.

    """
    return self.size[0] * self.size[1]

The setup.py script is used to generate an installable plugin package. This should contain something like the following:

#!/usr/bin/env python
# -*- coding: utf-8 -*-
from setuptools import setup

setup(name='psychopy-rect-area',
    version='1.0',
    description='Compute the area of a Rect stimulus.',
    long_description='',
    url='http://repo.example.com',
    author='Nobody',
    author_email='nobody@example.com',
    license='GPL3',
    classifiers=[
        'Development Status :: 4 - Beta',
        'License :: OSI Approved :: GLP3 License',
        'Programming Language :: Python :: 2.7',
        'Programming Language :: Python :: 3'
    ],
    keywords='psychopy stimulus',
    packages=['psychopy_rect_area'],
    install_requires=['psychopy'],
    include_package_data=True,
    entry_points={
        'psychopy.visual.Rect': ['getArea = psychopy_rect_area:get_area']
    },
    zip_safe=False)

Looking at entry_points we can see that were assigning psychopy_rect_area.get_area to psychopy.visual.Rect.getArea. Attributes assigned to entry points should follow the naming conventions of PsychoPy^® (camel case), however plugins are free to use internally whatever style the author chooses (eg. PEP8). You should also use appropriate classifiers for your plugin, a full list can be found here (https://pypi.org/pypi?%3Aaction=list_classifiers).

You can also specify install_requires to indicate which versions of PsychPy are compatible with your plugin. Visit https://packaging.python.org/discussions/install-requires-vs-requirements/ for more information.

One should also include a README.md file which provides detailed information about the plugin. This file can be read and passed to the long_description argument of setup() in setup.py if desired by inserting the following into the setup script:

from setuptools import setup

def get_readme_text():
    with open('README.md') as f:
        return f.read()

setup(
    ...
    long_description=get_readme_text(),
    ...
)

Finally, we need specify README.md in our MANIFEST.in file to tell the packaging system to include the file when packaging. Simply put the following line in MANIFEST.in:

README.md

Building packages¶

PsychoPy^® plugin packages are built like any other Python package. We can build a wheel distribution by calling the following console command:

python setup.py sdist bdist_wheel

The resulting .whl files will appear in directory psychopy-rect-area/dist. The generated packages can be installed with pip or uploaded to the Python Package Index. for more information about building and uploading packages, visit: https://packaging.python.org/tutorials/packaging-projects/

If uploaded to PyPI, other PsychoPy^® users can install your plugin by entering the following into their command prompt:

python -m pip install psychopy-rect-area

Using the plugin¶

Once installed the plugin can be activated by using the psychopy.plugins.loadPlugin() function. This function should be called after the import statements in your script:

from psychopy import visual, core, plugins
plugins.loadPlugin('psychopy-demo-plugin')  # load the plugin

After calling loadPlugin(), all instances of Rect will have the method getArea():

rectStim = visual.Rect(win)
rectArea = rectStim.getArea()

Creating patches¶

As an example, consider a fictional scenario where a bug was introduced in a recent release of PsychoPy^® by a hardware vendor updating their drivers. As a result, PsychoPy’s builtin support for their devices provided by the psychopy.hardware.Widget class is now broken. You notice that it has been fixed in a pending release of PsychoPy^®, and that it involves a single change to the getData() method of the psychopy.hardware.Widget class to get it working exactly as before. However, you cannot wait for the next release because you are in the middle of running scheduled experiments, even worse, you have dozens of test stations using the hardware.

In this case, you can create a plugin to not only fix the bug, but apply it across multiple existing installations to save the day. Creating a package for our patch is no different than a regular plugin (see the Plugin example project section for more information), so you go about creating a project for a plugin called psychopy-hotfix which defines the working version of the getData() method in a sub-module called psychopy_hotfix like this:

# method copy and pasted from the bug fix commit
def getData(self):
    """This function reads data from the device."""
    # code here ...

In the setup.py file of the plugin package, specify the entry points like this to override the defective method in our installations:

setup(
    name='psychopy-hotfix'
    ...
    entry_points={
        'psychopy.hardware.Widget': ['getData = psychopy_patch:getData']
    },
    ...
)

That’s it, just build a distributable package and install it on all the systems affected by the bug.

Applying patches¶

Whether you create your own patch, or obtain one provided by the PsychoPy^® community, they are applied using the loadPlugin() function after installing them. Experiment scripts will need to have the following lines added under the import statements at the top of the file for the plugin to take effect (but it’s considerably less work than manually patching in the code across many separate installations):

import psychopy.plugin as plugin
plugin.loadPlugin('psychopy-patch')

After loadPlugin is called, the behaviour of the getData() method of any instances of the psychopy.hardware.Widget class will change to the correct one.

Once a new release of PsychoPy^® comes out with the patch incorporated into it and your installations are upgraded, you can remove the above lines.

Example¶

For example, say we have a backend class called CustomBackend defined in module custom_backend in the plugin package psychopy-custom-backend. We can tell the plugin loader to register it to be used when a Window instance is created with winType='custom' by adding the winTypeName class attribute to CustomBackend:

class CustomBackend(BaseBackend):
    winTypeName = 'custom'
    ...

We define the entry point for our custom backend in setup.py as:

setup(
    ...
    entry_points={
    `'psychopy.visual.backends': 'custom_backend = custom_backend'},
    ...
)

Optionally, we can point to the backend class directly:

setup(
    ...
    entry_points={
        'psychopy.visual.backends':
            'custom_backend = custom_backend:CustomBackend'},
    ...
)

After the plugin is installed and loaded, we can use our backend for creating windows by specifying winType as winTypeName:

loadPlugin('psychopy-custom-backend')
win = Window(winType='custom')