service - Fundation classes for services implementation

Root class and helpers for implementing CSTBox D-Bus based services.

The concept of service container is provided to leverage the possibility of accessing several service objects through a single bus name. This container takes care of running the main loop and catching signals to terminating it gracefully.

Services objects are added to the container to provide the required services, each one being associated to a given path inside the container.

class pycstbox.service.ServiceContainer(name, conn=None, svc_objects=None, auto_fw_object=True)

A service container is used to host one or many service objects, made accessible via its connection to a bus.

Service objects can be added either at container creation time or afterwards.

A service object providing framework level features, such as termination request is automatically created and added (unless specified otherwise). Its path is defined by the SYSTEM_OBJECT_PATH constant.

Simple usage :
class SvcObject1(dbus.service.Object):
...
class SvcObject2(dbus.service.Object):
...

obj1 = SvcObject1(...) obj2 = SvcObject2(...) svc = ServiceContainer(

‘my_service’, –> will claim ‘fr.cstb.cstbox.my_service’ bus name on SessionBus [(obj1, ‘/path/to/obj1’),(obj2, ‘/path/to/obj2’)] )

svc.start()

Since automatic framework service object has been used (default), it is then possible possible to send to fr.cstb.cstbox.my_service a a method call message to framework.terminate

Parameters:
  • name (str) – the container’s name. It is used to build the well-known name which will be claimed (see pycstbox.commons.make_bus_name())
  • conn (dbus_connection) – the connection to the bus used by the service. Set to the session bus if not provided.
  • svc_objects (list) – an optional list of service objects, which will be automatically added to the container during its initialization. The items of this list are tuples containing the service object instance and the path to be associated for it
  • auto_fw_object (bool) – if True (the default) a service object implementing framework level functions is automatically created and added. If False, it is the responsibility of the application to provide it and adding it if framework level functions are required.
log_setLevel(level)

Local override of log_setLevel fo handing the propagation of the level setting to the child service objects.

add(svc_object, path)

Adds a service object to the container.

Parameters:
  • svc_object (ServiceObject) – the service object
  • path (str) – the path to which the object is accessed
Raises ValueError:
 

if parameters are None or not the right type
add_objects(svc_objects)

Adds a list of service object.

Parameters:svc_objects (list) – an optional list of service objects, which will be automatically added to the container during its initialization. The items of this list are tuples containing the service object instance and the path to be associated for it
remove(svc_object)

Removes a service object from the container.

Parameters:svc_object (ServiceObject) – the service object to be removed
Raises ValueError:
 if parameter is None or not the right type
start()

Starts the container.

This starts the D-Bus main loop and allows the service to receive calls and signals from the outside.

The container can be stopped then by : - calling its terminate() method - sending it a SIGTERM signal or a KeyboardInterrupt

Starting a running container has no effect, apart a warning message in the log.

terminate()

Stops the container.

This makes the event loop to exit and resources to be freed.

Stopping a not running container has no effect, apart a warning message in the log.

class pycstbox.service.SimpleService(name, conn=None, path='/service')

This class is just a helper for implementation of a service composed of a single object.

It is an hybrid class which packages the service container and the service object, and “connects” them automatically. If not provided, the service object path is set to ‘/service’.

It must be sub-classed to implement the required methods and/or signals.

IMPORTANT don’t use this for the moment, it is a bit buggy

Parameters:path (str) – the path to be associated to the service object. Default: ‘/service’

For other parameters, see ServiceContainer