Bundles¶
A bundle is a Python module installed using the Pelix
Framework
instance or a
BundleContext
object.
Each bundle is associated to an ID, an integer that is unique for a framework instance, and to a symbolic name, i.e. its module name. The framework itself is seen as the bundle which ID is always 0.
Because installing a bundle is in fact importing a module, no code should be written to be executed at module-level (except the definition of constants, the import of dependencies, …). Initialization must be done in the bundle activator (see below).
Life-cycle¶
Unlike a module, a bundle has a life-cycle and can be in one of the following states:

State | Description |
---|---|
INSTALLED | The Python module has been correctly imported, the bundle goes to the RESOLVED state |
RESOLVED | The bundle has not been started yet or has been stopped |
STARTING | The start() method of the bundle activator is being called (transition to ACTIVE or RESOLVED) |
ACTIVE | The bundle activator has been called and didn’t raise any error |
STOPPING | The stop() method of the bundle activator is being called (transition to RESOLVED) |
UNINSTALLED | The bundle has been removed from the framework (only visible by remaining references to the bundle) |
The update process of a bundle is simple:
- if it was active, the bundle is stopped: other bundles are notified of this transition, and its services are unregistered
- the module is updated, using the
importlib.reload()
method (or imp.reload()
when not available)
- if the update fails, the previous version of the module is kept, but the bundle is not restarted.
- if the update succeeds and the bundle was active, the bundle its restarted
Bundle Activator¶
A bundle activator is a class defining the
start()
and
stop()
methods, which are called by the
framework according to the bundle life-cycle.
The framework is locked during transitions in bundles states, which means during
the calls to start()
and
stop()
.
Therefore, it is heavily recommended to return fast from those methods.
For example, it may be necessary to use threads to complete the initialization
before registering services when the bundle starts.
On the other hand, it is recommended to wait for all resources to be released
before exiting the stop()
, e.g. to
wait for all threads started by the bundle to terminate.
-
class
pelix.constants.
BundleActivator
¶ This decorator must be applied to the class that will be notified of the life-cycle events concerning the bundle. A bundle can only have one activator, which must implement the following methods:
-
start
(context)¶ This method is called when the bundle is in STARTING state. If this method doesn’t raise an exception, the bundle goes immediately into the ACTIVE state. If an exception is raised, the bundle is stopped.
During the call of this method, the framework is locked. It is therefore necessary that this method returns as soon as possible: all time-consuming tasks should be executed in a new thread.
-
stop
(context)¶ This method is called when the bundle is in STOPPING state. After this method returns or raises an exception, the bundle goes into the RESOLVED state.
All resources consumed by the bundle should be released before this method returns.
-
A class is defined as the bundle activator if it is decorated with
@BundleActivator
, as shown in the following snippet:
import pelix.constants
@pelix.constants.BundleActivator
class Activator(object):
"""
Bundle activator template
"""
def start(self, context):
"""
Bundle is starting
"""
print("Start")
def stop(self, context):
"""
Bundle is stopping
"""
print("Stop")
Note
The previous declaration of the activator, i.e. declaring module member
named activator
, is deprecated and its support will be removed in
version 1.0.
Bundle Context¶
A context is associated to each bundle, and allows it to interact with the
framework.
It is unique for a bundle and can be used until the latter is removed from
the framework.
It is not recommended to keep references to BundleContext
objects as they
can imply a stall reference to the bundle they describe.
A bundle must use its context to register and to look up services, to request
framework information, etc..
All the available methods are described in the API chapter. Here are the most used ones concerning the handling of bundles:
-
class
pelix.framework.
BundleContext
(framework, bundle) The bundle context is the link between a bundle and the framework. It is unique for a bundle and is created by the framework once the bundle is installed.
Parameters: - framework – Hosting framework
- bundle – The associated bundle
-
add_bundle_listener
(listener) Registers a bundle listener, which will be notified each time a bundle is installed, started, stopped or updated.
- The listener must be a callable accepting a single parameter:
- event – The description of the event
(a
BundleEvent
object).
- event – The description of the event
(a
Parameters: listener – The bundle listener to register Returns: True if the listener has been registered, False if it already was
-
get_bundle
(bundle_id=None) Retrieves the
Bundle
object for the bundle matching the given ID (int). If no ID is given (None), the bundle associated to this context is returned.Parameters: bundle_id – A bundle ID (optional) Returns: The requested Bundle
objectRaises: BundleException – The given ID doesn’t exist or is invalid
-
get_bundles
() Returns the list of all installed bundles
Returns: A list of Bundle
objects
-
install_bundle
(name, path=None) Installs the bundle (module) with the given name.
If a path is given, it is inserted in first place in the Python loading path (
sys.path
). All modules loaded alongside this bundle, i.e. by this bundle or its dependencies, will be looked after in this path in priority.Note
Before Pelix 0.5.0, this method returned the ID of the installed bundle, instead of the Bundle object.
Warning
The behavior of the loading process is subject to changes, as it does not allow to safely run multiple frameworks in the same Python interpreter, as they might share global module values.
Parameters: - name – The name of the bundle to install
- path – Preferred path to load the module (optional)
Returns: The
Bundle
object of the installed bundleRaises: BundleException – Error importing the module or one of its dependencies
-
install_package
(path, recursive=False) Installs all the modules found in the given package (directory). It is a utility method working like
install_visiting()
, with a visitor accepting every module found.Parameters: - path – Path of the package (folder)
- recursive – If True, installs the modules found in sub-directories
Returns: A 2-tuple, with the list of installed bundles (
Bundle
) and the list of the names of the modules which import failed.Raises: ValueError – The given path is invalid
-
install_visiting
(path, visitor) Looks for modules in the given path and installs those accepted by the given visitor.
- The visitor must be a callable accepting 3 parameters:
- fullname – The full name of the module
- is_package – If True, the module is a package
- module_path – The path to the module file
Parameters: - path – Root search path (folder)
- visitor – The visiting callable
Returns: A 2-tuple, with the list of installed bundles (
Bundle
) and the list of the names of the modules which import failed.Raises: ValueError – Invalid path or visitor
-
remove_bundle_listener
(listener) Unregisters the given bundle listener
Parameters: listener – The bundle listener to remove Returns: True if the listener has been unregistered, False if it wasn’t registered