Coverage for src/robotide/pluginapi/__init_

4# Licensed under the Apache License, Version 2.0 (the "License");

5# you may not use this file except in compliance with the License.

6# You may obtain a copy of the License at

8# http://www.apache.org/licenses/LICENSE-2.0

10# Unless required by applicable law or agreed to in writing, software

11# distributed under the License is distributed on an "AS IS" BASIS,

12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

13# See the License for the specific language governing permissions and

14# limitations under the License.

16"""RIDE Plugin API

18.. contents::

19 :depth: 2

20 :local:

22Introduction

23------------

25RIDE can be extended with plugins written in Python starting with version 0.16.

26The plugin API went through a major overhaul in the 0.20 release and this

27documentation describes how to write plugins against the new API. After the

28changes in RIDE 0.20, the goal is to limit backwards incompatible changes to

29the minimum at least until the 1.0 release sometime in the spring 2010.

31Finding plugins

32---------------

34Plugins are loaded automatically when RIDE starts up. RIDE will look in the

35following directories for plugins:

37- ``<RIDE_INSTALLATION_DIR>/site-plugins``

38- ``<USER_DATA>/plugins``

40Location of the ``<USER_DATA>`` directory will vary depending on your platform.

41On Linux and OSX this will be ``~/.robotframework/ride`` while on Windows the

42location is ``%APPDATA%\\RobotFramework\\ride``.

44Each Python file that is found in these directories is dynamically imported and

45inspected. Every subclass of the `Plugin` class in these files will be

46instantiated as a plugin. This has a few noteworthy consequences:

48- Common utility code may be distributed as separate files, located in the

49 plugin directories.

50- All the top level code in the found Python files is executed as they are

51 imported. Beware of the side effects.

52- A Python file may contain more than one plugin.

54Initialization

55--------------

57As stated earlier, every plugin *must* inherit from the `Plugin` base class.

58This class is exposed directly from the `pluginapi` module, similarly as all

59other classes that plugins most often need, and can thus be imported like::

61 from robotide.pluginapi import Plugin

63When a plugin class is found, an instance of it will be created. Different

64initialization options are explained in the documentation of the

65`Plugin.__init__` method. If creating an instance of a plugin class fails, an

66error message is shown to the user and the plugin is disabled.

68Enabling and disabling

69----------------------

71Plugins can control are they enabled by default when they are loaded for the

72first time. Afterwards users can enable and disable plugins from the plugin

73manager, which is available from the menu through ``Tools > Manage Plugins``.

74Plugins' enabled/disabled state is stored into RIDE's settings file and read

75from there when plugins are loaded again later.

77When the plugin is enabled, the `Plugin.enable` method is called. This is the

78point where the plugin is actually turned on and also the time when possible

79integration into RIDE UI should happen. The `Plugin.disable` method is called

80when the plugin is disabled, and its purpose is to undo whatever was done in

81the `Plugin.enable` method.

83Creating menu entries and shortcuts

84-----------------------------------

86Plugins can create new entries to menus, buttons to the toolbar, and register

87shortcuts using `ActionInfo` objects and the `Plugin.register_action` method.

88Registering actions is thoroughly documented in the `robotide.action` module.

89Notice that all the relevant action classes are exposed also through the

90`pluginapi` module and plugins should import them like::

92 from robotide.pluginapi import ActionInfo

94Messaging

95---------

97RIDE has a messaging system that allows both sending messages when something

98happens and subscribing to certain messages. Messages sent upon some

99user action, like selecting an item in the tree or saving a file, are the

100main communication mechanism from RIDE to plugins, but sometimes plugins may

101also have a need to sent their own messages. Plugins can subscribe to messages

102using the `Plugin.subscribe` method. The whole messaging system is documented

103in the `robotide.publish` module, but plugins can import the relevant classes

104through the `pluginapi` module like::

105

106 from robotide.pluginapi import RideTreeSelection, RideSaved

107

108Settings

109--------

110

111Plugin can store information persistently to RIDE's setting file. The initial

112values can be given to the `Plugin.__init__` method and new values saved using

113`Plugin.save_setting`. Saved settings can be accessed using direct attribute

114access via `Plugin.__getattr__`.

115

116Settings are stored into the setting file under ``[Plugins]`` section into

117plugin specific subsections. Settings names starting with an underscore

118(currently only ``_enabled``) are reserved for RIDE's internal usage. The saved

119settings may look something like this::

120

121 [Plugins]

122 [[Release Notes]]

123 version_shown = 'trunk'

124 _enabled = True

125 [[Recent Files]]

126 max_number_of_files = 4

127 recent_files = []

128 _enabled = False

129"""

130

131from ..action import action_info_collection, ActionInfo 2 ctx1ab

132from .plugin import Plugin 2 ctx1ab

133from .tree_aware_plugin_mixin import TreeAwarePluginMixin 2 ctx1ab

Coverage for src/robotide/pluginapi/init.py: 100%

3 statements