API

This part of the documentation covers all the core classes and services of iPOPO.

BundleContext Object

The bundle context is the link between a bundle and the framework. It’s by the context that you can register services, install other bundles.

class pelix.framework.BundleContext(framework: Framework, bundle: 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: BundleListener) → bool

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).

Parameters:: listener – The bundle listener to register
Returns:: True if the listener has been registered, False if it already was

add_framework_stop_listener(listener: FrameworkStoppingListener) → bool

Registers a listener that will be called back right before the framework stops

The framework listener must have a method with the following prototype:

def framework_stopping(self):
    '''
    No parameter given
    '''
    # ...

Parameters:: listener – The framework stop listener
Returns:: True if the listener has been registered

Registers a service listener

The service listener must have a method with the following prototype:

def service_changed(self, event):
    '''
    Called by Pelix when some service properties changes

    event: A ServiceEvent object
    '''
    # ...

Parameters:

listener – The listener to register
ldap_filter – Filter that must match the service properties (optional, None to accept all services)
specification – The specification that must provide the service (optional, None to accept all services)

Returns:

True if the listener has been successfully registered

Returns an array of ServiceReference objects. The returned array of ServiceReference objects contains services that were registered under the specified class and match the specified filter expression.

Parameters:

clazz – Class implemented by the service
ldap_filter – Service filter

Returns:

The sorted list of all matching service references, or None

get_bundle(bundle_id: None | int | Bundle = None) → Bundle

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 object
Raises:: BundleException – The given ID doesn’t exist or is invalid

get_bundles() → List[Bundle]

Returns the list of all installed bundles

Returns:: A list of Bundle objects

get_framework() → Framework

Returns the Framework that created this bundle context

Returns:: The Framework object

get_property(name: str) → Any

Returns the value of a property of the framework, else returns the OS environment value.

Parameters:: name – A property name

get_service(reference: ServiceReference[T]) → T

Returns the service described with the given reference

Parameters:: reference – A ServiceReference object
Returns:: The service object itself

get_service_objects(reference: ServiceReference[T]) → ServiceObjects[T]

Returns the ServiceObjects object for the service referenced by the specified ServiceReference object.

Parameters:: reference – Reference to a prototype service factory
Returns:: An intermediate object to get more instances of a service

Returns a ServiceReference object for a service that implements and was registered under the specified class

Parameters:

clazz – The class name with which the service was registered.
ldap_filter – A filter on service properties

Returns:

A service reference, None if not found

Returns the service references for services that were registered under the specified class by this bundle and matching the given filter

Parameters:

clazz – The class name with which the service was registered.
ldap_filter – A filter on service properties

Returns:

The list of references to the services registered by the calling bundle and matching the filters.

install_bundle(name: str, path: None | str | Path = None) → Bundle

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.

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 bundle

Raises:

BundleException – Error importing the module or one of its dependencies

install_package(path: str | Path, recursive: bool = False) → Tuple[Set[Bundle], Set[str]]

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: str | Path, visitor: Callable[[str, bool, str], bool]) → Tuple[Set[Bundle], Set[str]]

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

register_service(clazz: str | Type[T] | Iterable[str | Type[Any]], service: T, properties: Dict[str, Any] | None, send_event: bool = True, factory: bool = False, prototype: bool = False) → ServiceRegistration[T]

Registers a service

Parameters:

clazz – Class or Classes (list) implemented by this service
service – The service instance
properties – The services properties (dictionary)
send_event – If not, doesn’t trigger a service registered event
factory – If True, the given service is a service factory
prototype – If True, the given service is a prototype service factory (the factory argument is considered True)

Returns:

A ServiceRegistration object

Raises:

BundleException – An error occurred while registering the service

remove_bundle_listener(listener: BundleListener) → bool

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

remove_framework_stop_listener(listener: FrameworkStoppingListener) → bool

Unregisters a framework stop listener

Parameters:: listener – The framework stop listener
Returns:: True if the listener has been unregistered

remove_service_listener(listener: ServiceListener) → bool

Unregisters a service listener

Parameters:: listener – The service listener
Returns:: True if the listener has been unregistered

unget_service(reference: ServiceReference[Any]) → bool

Disables a reference to the service

Returns:: True if the bundle was using this reference, else False

Framework Object

The Framework object is a singleton and can be accessed using get_bundle(0). This class inherits the methods from pelix.framework.Bundle.

class pelix.framework.Framework(properties: Dict[str, Any] | None = None)

The Pelix framework (main) class. It must be instantiated using FrameworkFactory

Sets up the framework.

Parameters:: properties – The framework properties

add_property(name: str, value: Any) → bool

Adds a property to the framework if it is not yet set.

If the property already exists (same name), then nothing is done. Properties can’t be updated.

Parameters:

name – The property name
value – The value to set

Returns:

True if the property was stored, else False

delete(force: bool = False) → bool

Deletes the current framework

Parameters:: force – If True, stops the framework before deleting it
Returns:: True if the framework has been delete, False if is couldn’t

Finds all services references matching the given filter.

Parameters:

clazz – Class implemented by the service
ldap_filter – Service filter
only_one – Return the first matching service reference only

Returns:

A list of found reference, or None

Raises:

BundleException – An error occurred looking for service references

get_bundle_by_id(bundle_id: int) → Bundle | Framework

Retrieves the bundle with the given ID

Parameters:: bundle_id – ID of an installed bundle
Returns:: The requested bundle
Raises:: BundleException – The ID is invalid

get_bundle_by_name(bundle_name: str) → Bundle | None

Retrieves the bundle with the given name

Parameters:: bundle_name – Name of the bundle to look for
Returns:: The requested bundle, None if not found

get_bundles() → List[Bundle]

Returns the list of all installed bundles

Returns:: the list of all installed bundles

get_properties() → Dict[str, Any]: Retrieves a copy of the stored framework properties.

get_property(name: str) → Any

Retrieves a framework or system property. As framework properties don’t change while it’s running, this method don’t need to be protected.

Parameters:: name – The property name

get_property_keys() → Tuple[str, ...]

Returns an array of the keys in the properties of the service

Returns:: An array of property keys.

get_service(bundle: Bundle, reference: ServiceReference[T]) → T

Retrieves the service corresponding to the given reference

Parameters:

bundle – The bundle requiring the service
reference – A service reference

Returns:

The requested service

Raises:

BundleException – The service could not be found
TypeError – The argument is not a ServiceReference object

get_symbolic_name() → str

Retrieves the framework symbolic name

Returns:: Always “pelix.framework”

install_bundle(name: str, path: str | Path | None = None) → Bundle

Installs the bundle with the given name

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 – A bundle name
path – Preferred path to load the module

Returns:

The installed Bundle object

Raises:

BundleException – Something happened

install_package(path: str | Path, recursive: bool = False, prefix: str | None = None) → Tuple[Set[Bundle], Set[str]]

Installs all the modules found in the given package

Parameters:

path – Path of the package (folder)
recursive – If True, install the sub-packages too
prefix – (internal) Prefix for all found modules

Returns:

A 2-tuple, with the list of installed bundles and the list of failed modules names

Raises:

ValueError – Invalid path

install_visiting(path: str | Path, visitor: Callable[[str, bool, str], bool], prefix: str | None = None) → Tuple[Set[Bundle], Set[str]]

Installs all the modules found in the given path if they are accepted by the 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
visitor – The visiting callable
prefix – (internal) Prefix for all found modules

Returns:

A 2-tuple, with the list of installed bundles and the list of failed modules names

Raises:

ValueError – Invalid path or visitor

register_service(bundle: Bundle, clazz: str | Type[T] | Iterable[str | Type[Any]], service: T, properties: Dict[str, Any] | None, send_event: bool, factory: bool = False, prototype: bool = False) → ServiceRegistration[T]

Registers a service and calls the listeners

Parameters:

bundle – The bundle registering the service
clazz – Name(s) of the interface(s) implemented by service
service – The service to register
properties – Service properties
send_event – If not, doesn’t trigger a service registered event
factory – If True, the given service is a service factory
prototype – If True, the given service is a prototype service factory (the factory argument is considered True)

Returns:

A ServiceRegistration object

Raises:

BundleException – An error occurred while registering the service

start() → bool

Starts the framework

Returns:: True if the bundle has been started, False if it was already running
Raises:: BundleException – A bundle failed to start

stop() → bool

Stops the framework

Returns:: True if the framework stopped, False it wasn’t running

uninstall() → None

A framework can’t be uninstalled

Raises:: BundleException – This method must not be called

uninstall_bundle(bundle: Bundle) → None

Ends the uninstallation of the given bundle (must be called by Bundle)

Parameters:: bundle – The bundle to uninstall
Raises:: BundleException – Invalid bundle

unregister_service(registration: ServiceRegistration[Any]) → bool

Unregisters the given service

Parameters:: registration – A ServiceRegistration to the service to unregister
Raises:: BundleException – Invalid reference

update() → None

Stops and starts the framework, if the framework is active.

Raises:: BundleException – Something wrong occurred while stopping or starting the framework.

wait_for_stop(timeout: int | None = None) → bool

Waits for the framework to stop. Does nothing if the framework bundle is not in ACTIVE state.

Uses a threading.Condition object

Parameters:: timeout – The maximum time to wait (in seconds)
Returns:: True if the framework has stopped, False if the timeout raised

Service management

The lookup methods of the bundle context will return ServiceReference objects that can be used to check the metadata of a service before using it.

class pelix.internals.registry.ServiceReference(bundle: Bundle, properties: Dict[str, Any])

Represents a reference to a service

Parameters:

bundle – The bundle registering the service
properties – The service properties

Raises:

BundleException – The properties doesn’t contain mandatory entries

get_bundle() → Bundle

Returns the bundle that registered this service

Returns:: the bundle that registered this service

get_properties() → Dict[str, Any]

Returns a copy of the service properties

Returns:: A copy of the service properties

get_property(name: str) → Any

Retrieves the property value for the given name

Returns:: The property value, None if not found

get_property_keys() → Tuple[str, ...]

Returns an array of the keys in the properties of the service

Returns:: An array of property keys.

get_using_bundles() → List[Bundle]

Returns the list of bundles that use this service

Returns:: A list of Bundle objects

is_factory() → bool

Returns True if this reference points to a service factory

Returns:: True if the service provides from a factory

is_prototype() → bool

Returns True if this reference points to a prototype service factory

Returns:: True if the service provides from a prototype factory

needs_sort_update() → bool

Checks if the sort key must be updated

Returns:: True if the sort key must be updated

unused_by(bundle: Bundle) → None

Indicates that this reference is not being used anymore by the given bundle. This method should only be used by the framework.

Parameters:: bundle – A bundle that used this reference

update_sort_key() → None

Recomputes the sort key, based on the service ranking and ID

See <https://docs.osgi.org/javadoc/osgi.core/8.0.0/org/osgi/framework/ServiceReference.html#compareTo-java.lang.Object->

used_by(bundle: Bundle) → None

Indicates that this reference is being used by the given bundle. This method should only be used by the framework.

Parameters:: bundle – A bundle using this reference

When registering a service, the bundle context will return a ServiceRegistration. That object must not be shared to others as it can be used to update service properties and to unregister it.

class pelix.internals.registry.ServiceRegistration(framework: Framework, reference: ServiceReference[T], properties: Dict[str, Any], update_callback: Callable[[ServiceReference[T]], None])

Represents a service registration object

Parameters:

framework – The host framework
reference – A service reference
properties – A reference to the ServiceReference properties dictionary object
update_callback – Method to call when the sort key is modified

get_reference() → ServiceReference[T]

Returns the reference associated to this registration

Returns:: A ServiceReference object

set_properties(properties: Dict[str, Any]) → None

Updates the service properties

Parameters:: properties – The new properties
Raises:: TypeError – The argument is not a dictionary

unregister() → None: Unregisters the service

Bundle Object

This object gives access to the description of an installed bundle. It is useful to check the path of the source module, the version, etc.

class pelix.framework.Bundle(framework: Framework, bundle_id: int, name: str, module_: ModuleType)

Represents a “bundle” in Pelix

Sets up the bundle descriptor

Parameters:

framework – The host framework
bundle_id – The ID of the bundle in the host framework
name – The bundle symbolic name
module – The bundle module

get_bundle_context() → BundleContext

Retrieves the bundle context

Returns:: The bundle context

get_bundle_id() → int

Retrieves the bundle ID

Returns:: The bundle ID

get_location() → str

Retrieves the location of this module

Returns:: The location of the Pelix module, or an empty string

get_module() → ModuleType

Retrieves the Python module corresponding to the bundle

Returns:: The Python module

get_registered_services() → List[ServiceReference[Any]]

Returns this bundle’s ServiceReference list for all services it has registered or an empty list

The list is valid at the time of the call to this method, however, as the Framework is a very dynamic environment, services can be modified or unregistered at any time.

Returns:: An array of ServiceReference objects
Raises:: BundleException – If the bundle has been uninstalled

get_services_in_use() → List[ServiceReference[Any]]

Returns this bundle’s ServiceReference list for all services it is using or an empty list. A bundle is considered to be using a service if its use count for that service is greater than zero.

The list is valid at the time of the call to this method, however, as the Framework is a very dynamic environment, services can be modified or unregistered at any time.

Returns:: An array of ServiceReference objects
Raises:: BundleException – If the bundle has been uninstalled

get_state() → int

Retrieves the bundle state

Returns:: The bundle state

get_symbolic_name() → str

Retrieves the bundle symbolic name (its Python module name)

Returns:: The bundle symbolic name

get_version() → str

Retrieves the bundle version, using the __version__ or __version_info__ attributes of its module.

Returns:: The bundle version, “0.0.0” by default

start() → bool

Starts the bundle. Does nothing if the bundle is already starting or active.

Raises:: BundleException – The framework is not yet started or the bundle activator failed.

stop() → bool

Stops the bundle. Does nothing if the bundle is already stopped.

Raises:: BundleException – The bundle activator failed.

uninstall() → None: Uninstalls the bundle

update() → None: Updates the bundle

ACTIVE = 32: The bundle is now running

INSTALLED = 2: The bundle is installed but not yet resolved

RESOLVED = 4: The bundle is resolved and is able to be started

STARTING = 8: The bundle is in the process of starting

STOPPING = 16: The bundle is in the process of stopping

UNINSTALLED = 1: The bundle is uninstalled and may not be used

Events Objects

Those objects are given to listeners when a bundle or a service event occurs.

class pelix.internals.events.BundleEvent(kind: int, bundle: Bundle)

Represents a bundle event

Sets up the event

get_bundle() → Bundle: Retrieves the modified bundle

get_kind() → int: Retrieves the kind of event

INSTALLED = 1: The bundle has been installed.

STARTED = 2: The bundle has been started.

STARTING = 128: The bundle is about to be activated.

STOPPED = 4: The bundle has been stopped. All of its services have been unregistered.

STOPPING = 256: The bundle is about to deactivated.

STOPPING_PRECLEAN = 512: The bundle has been deactivated, but some of its services may still remain.

UNINSTALLED = 16: The bundle has been uninstalled.

UPDATED = 8: The bundle has been updated. (called after STARTED)

UPDATE_BEGIN = 32: The bundle will be updated (called before STOPPING)

UPDATE_FAILED = 64: The bundle update has failed. The bundle might be in RESOLVED state

class pelix.internals.events.ServiceEvent(kind: int, reference: ServiceReference[T], previous_properties: Dict[str, Any] | None = None)

Represents a service event

Sets up the event

Parameters:

kind – Kind of event
reference – Reference to the modified service
previous_properties – Previous service properties (for MODIFIED and MODIFIED_ENDMATCH events)

get_kind() → int

Returns the kind of service event (see the constants)

Returns:: the kind of service event

get_previous_properties() → Dict[str, Any] | None

Returns the previous values of the service properties, meaningless if the the event is not MODIFIED nor MODIFIED_ENDMATCH.

Returns:: The previous properties of the service

get_service_reference() → ServiceReference[T]

Returns the reference to the service associated to this event

Returns:: A ServiceReference object

MODIFIED = 2: The properties of a registered service have been modified

MODIFIED_ENDMATCH = 8: The properties of a registered service have been modified and the new properties no longer match the listener’s filter

REGISTERED = 1: This service has been registered

UNREGISTERING = 4: This service is in the process of being unregistered

class pelix.ipopo.constants.IPopoEvent(kind: int, factory_name: str, component_name: str | None)

An iPOPO event descriptor.

Sets up the iPOPO event

Parameters:

kind – Kind of event
factory_name – Name of the factory associated to the event
component_name – Name of the component instance associated to the event

get_component_name() → str | None

Retrieves the name of the component associated to the event

Returns:: the name of the component

get_factory_name() → str

Retrieves the name of the factory associated to the event

Returns:: the name of the component factory

get_kind() → int

Retrieves the kind of event

Returns:: the kind of event

BOUND = 5: A reference has been injected in the component

INSTANTIATED = 2: A component has been instantiated, but not yet validated

INVALIDATED = 4: A component has been invalidated

KILLED = 9: A component has been killed (removed from the list of instances)

REGISTERED = 1: A component factory has been registered

UNBOUND = 6: A reference has been removed from the component

UNREGISTERED = 10: A component factory has been unregistered

VALIDATED = 3: A component has been validated