pyface.base_toolkit module

Common toolkit loading utilities and classes

This module provides common code for ETS packages that need to do GUI toolkit discovery and loading. The common patterns that ETS has settled on are that where different GUI toolkits require alternative implementations of features the toolkit is expected to provide a callable object which takes a relative module path and an object name, separated by a colon and return the toolkit’s implementation of that object (usually this is a class, but it could be anything). The assumption is that this is implemented by objects in sub-modules of the toolkit, but plugin authors are free to use whatever methods they like.

Which toolkit to use is specified via the traits.etsconfig.etsconfig package, but if this is not explicitly set by an application at startup or via environment variables, there needs to be a way of discovering and loading any available working toolkit implementations. The default mechanism is via the now-standard importlib_metadata and setuptools “entry point” system.

This module provides three things:

  • a function import_toolkit() that attempts to find and load a toolkit entry point for a specified toolkit name

  • a function find_toolkit() that attempts to find a toolkit entry point that works

  • a class Toolkit class that implements the standard logic for finding toolkit objects.

These are done in a library-agnostic way so that the same tools can be used not just for different pyface backends, but also for TraitsUI and ETS libraries where we need to switch between different GUI toolkit implementations.

Note that there is no requirement for new toolkit implementations to use this Toolkit implementation, but they should be compatible with it.

Default toolkit loading logic

The find_toolkit() function uses the following logic when attempting to load toolkits:

  • if ETSConfig.toolkit is set, try to load a plugin with a matching name. If it succeeds, we are good, and if it fails then we error out.

  • after that, we try every ‘pyface.toolkit’ plugin we can find. If one succeeds, we consider ourselves good, and set the ETSConfig.toolkit appropriately. The order is configurable, and by default will try to load the qt toolkit first, wx next, then all others in arbitrary order, and null last.

  • finally, if all else fails, we try to load the null toolkit.

pyface.base_toolkit.default_priorities(plugin)
class pyface.base_toolkit.Toolkit(package, toolkit, *packages, **traits)[source]

Bases: HasTraits

A basic toolkit implementation for use by specific toolkits.

This implementation uses pathname mangling to find modules and objects in those modules. If an object can’t be found, the toolkit will return a class that raises NotImplementedError when it is instantiated.

package = ReadOnly

The name of the package (eg. pyface)

toolkit = ReadOnly

The name of the toolkit

packages = List(Str)

The packages to look in for implementations.

pyface.base_toolkit.import_toolkit(toolkit_name, entry_point='pyface.toolkits')[source]

Attempt to import an toolkit specified by an entry point.

Parameters

  • toolkit_name (str) – The name of the toolkit we would like to load.

  • entry_point (str) – The name of the entry point that holds our toolkits.

Returns

toolkit_object – A callable object that implements the Toolkit interface.

Return type

Callable

Raises

RuntimeError – If no toolkit is found, or if the toolkit cannot be loaded for some reason.

pyface.base_toolkit.find_toolkit(entry_point='pyface.toolkits', toolkits=None, priorities=<function <lambda>>)[source]

Find a toolkit that works.

If ETSConfig is set, then attempt to find a matching toolkit. Otherwise try every plugin for the entry_point until one works. The ordering of the plugins is supplied via the priorities function which should be suitable for use as a sorting key function. If all else fails, explicitly try to load the “null” toolkit backend. If that fails, give up.

Parameters

  • entry_point (str) – The name of the entry point that holds our toolkits.

  • toolkits (collection of strings) – Only consider toolkits which match the given strings, ignore other ones.

  • priorities (Callable) – A callable function that returns an priority for each plugin.

Returns

toolkit – A callable object that implements the Toolkit interface.

Return type

Toolkit

Raises

RuntimeError – If no ETSConfig.toolkit is set but the toolkit cannot be loaded for some reason.