enhance documentation
- flatten hierarchy (some links do not work when using folders) + fix a bug with the redorder flag in Override + allow removal of parameters + clean description using inspect.cleandoc Change-Id: I3dde4f4cb29c46e8a21014f1fad7aa3ad610a1bf
This commit is contained in:
@ -50,17 +50,28 @@ class Module(HasProperties, metaclass=ModuleMeta):
|
||||
|
||||
all SECoP modules derive from this.
|
||||
|
||||
note: within modules, parameters should only be addressed as ``self.<pname>``
|
||||
i.e. ``self.value``, ``self.target`` etc...
|
||||
these are accessing the cached version.
|
||||
they can also be written to, generating an async update
|
||||
:param name: the modules name
|
||||
:param logger: a logger instance
|
||||
:param cfgdict: the dict from this modules section in the config file
|
||||
:param srv: the server instance
|
||||
|
||||
if you want to 'update from the hardware', call ``self.read_<pname>()`` instead
|
||||
the return value of this method will be used as the new cached value and
|
||||
be an async update sent automatically.
|
||||
Notes:
|
||||
|
||||
- the programmer normally should not need to reimplement :meth:`__init__`
|
||||
- within modules, parameters should only be addressed as ``self.<pname>``, i.e. ``self.value``, ``self.target`` etc...
|
||||
|
||||
- these are accessing the cached version.
|
||||
- they can also be written to, generating an async update
|
||||
|
||||
- if you want to 'update from the hardware', call ``self.read_<pname>()`` instead
|
||||
|
||||
- the return value of this method will be used as the new cached value and
|
||||
be an async update sent automatically.
|
||||
|
||||
- if you want to 'update the hardware' call ``self.write_<pname>(<new value>)``.
|
||||
|
||||
- The return value of this method will also update the cache.
|
||||
|
||||
if you want to 'update the hardware' call ``self.write_<pname>(<new value>)``.
|
||||
The return value of this method will also update the cache.
|
||||
"""
|
||||
# static properties, definitions in derived classes should overwrite earlier ones.
|
||||
# note: properties don't change after startup and are usually filled
|
||||
@ -69,22 +80,22 @@ class Module(HasProperties, metaclass=ModuleMeta):
|
||||
# note: the names map to a [datatype, value] list, value comes from the cfg file,
|
||||
# datatype is fixed!
|
||||
properties = {
|
||||
'export': Property('Flag if this Module is to be exported', BoolType(), default=True, export=False),
|
||||
'group': Property('Optional group the Module belongs to', StringType(), default='', extname='group'),
|
||||
'description': Property('Description of the module', TextType(), extname='description', mandatory=True),
|
||||
'meaning': Property('Optional Meaning indicator', TupleOf(StringType(),IntRange(0,50)),
|
||||
'export': Property('flag if this Module is to be exported', BoolType(), default=True, export=False),
|
||||
'group': Property('optional group the Module belongs to', StringType(), default='', extname='group'),
|
||||
'description': Property('description of the module', TextType(), extname='description', mandatory=True),
|
||||
'meaning': Property('dptional Meaning indicator', TupleOf(StringType(),IntRange(0,50)),
|
||||
default=('',0), extname='meaning'),
|
||||
'visibility': Property('Optional visibility hint', EnumType('visibility', user=1, advanced=2, expert=3),
|
||||
'visibility': Property('optional visibility hint', EnumType('visibility', user=1, advanced=2, expert=3),
|
||||
default='user', extname='visibility'),
|
||||
'implementation': Property('Internal name of the implementation class of the module', StringType(),
|
||||
'implementation': Property('internal name of the implementation class of the module', StringType(),
|
||||
extname='implementation'),
|
||||
'interface_classes': Property('Offical highest Interface-class of the module', ArrayOf(StringType()),
|
||||
'interface_classes': Property('offical highest Interface-class of the module', ArrayOf(StringType()),
|
||||
extname='interface_classes'),
|
||||
}
|
||||
|
||||
# properties, parameters and commands are auto-merged upon subclassing
|
||||
parameters = {}
|
||||
commands = {}
|
||||
parameters = {} #: definition of parameters
|
||||
commands = {} #: definition of commands
|
||||
|
||||
# reference to the dispatcher (used for sending async updates)
|
||||
DISPATCHER = None
|
||||
@ -354,12 +365,31 @@ class Module(HasProperties, metaclass=ModuleMeta):
|
||||
return False
|
||||
|
||||
def earlyInit(self):
|
||||
# may be overriden in derived classes to init stuff
|
||||
"""may be overriden in derived classes to init stuff
|
||||
|
||||
after creating the module (no super call needed)
|
||||
"""
|
||||
self.log.debug('empty %s.earlyInit()' % self.__class__.__name__)
|
||||
|
||||
def initModule(self):
|
||||
"""may be overriden to do stuff after all modules are intiialized
|
||||
|
||||
no super call needed
|
||||
"""
|
||||
self.log.debug('empty %s.initModule()' % self.__class__.__name__)
|
||||
|
||||
def startModule(self, started_callback):
|
||||
"""runs after init of all modules
|
||||
|
||||
:param started_callback: argument less function to be called when the thread
|
||||
spawned by startModule has finished its initial work
|
||||
:return: None or a timeout value, if different from default (30 sec)
|
||||
|
||||
override this method for doing stuff during startup, after all modules are
|
||||
initialized. do not forget the super call
|
||||
"""
|
||||
mkthread(self.writeInitParams, started_callback)
|
||||
|
||||
def pollOneParam(self, pname):
|
||||
"""poll parameter <pname> with proper error handling"""
|
||||
try:
|
||||
@ -391,15 +421,6 @@ class Module(HasProperties, metaclass=ModuleMeta):
|
||||
if started_callback:
|
||||
started_callback()
|
||||
|
||||
def startModule(self, started_callback):
|
||||
"""runs after init of all modules
|
||||
|
||||
started_callback to be called when the thread spawned by startModule
|
||||
has finished its initial work
|
||||
might return a timeout value, if different from default
|
||||
"""
|
||||
mkthread(self.writeInitParams, started_callback)
|
||||
|
||||
|
||||
class Readable(Module):
|
||||
"""basic readable module"""
|
||||
@ -421,7 +442,7 @@ class Readable(Module):
|
||||
readonly=False,
|
||||
datatype=FloatRange(0.1, 120),
|
||||
),
|
||||
'status': Parameter('current status of the Module',
|
||||
'status': Parameter('*(rd, tuple of (Readable.Status, str))* current status of the Module',
|
||||
default=(Status.IDLE, ''),
|
||||
datatype=TupleOf(EnumType(Status), StringType()),
|
||||
readonly=True, poll=True,
|
||||
@ -496,7 +517,8 @@ class Drivable(Writable):
|
||||
}
|
||||
|
||||
overrides = {
|
||||
'status': Override(datatype=StatusType(Status)),
|
||||
'status': Override('*(rd, tuple of (Drivable.Status, str))* current status of the Module',
|
||||
datatype=StatusType(Status)),
|
||||
}
|
||||
|
||||
def isBusy(self, status=None):
|
||||
@ -561,7 +583,7 @@ class Communicator(Module):
|
||||
|
||||
|
||||
class Attached(Property):
|
||||
"""a special property, defining an attached modle
|
||||
"""a special property, defining an attached module
|
||||
|
||||
assign a module name to this property in the cfg file,
|
||||
and the server will create an attribute with this module
|
||||
|
||||
Reference in New Issue
Block a user