Table Of Contents

Previous topic

UDS Modules

Next topic

Form Fields

This Page

Base Module

The Base module is the base class used for all modules of UDS.

In order to deveplop an UDS Module, there is a number of basic methods that you must provide.

There are the clases that are base of BaseModule, that are:

BaseModule

class uds.core.Module(environment, values=None)

Base class for all modules used by UDS. This base module provides all the needed methods that modules must implement

All modules must, at least, implement the following:

  • Attributes:
    • typeName: Name for this type of module (human readable) to assign to the module (string) This name will be used to let the administrator identify this module.
    • typeType: Name for this type of module (machine only) to assing to the module (string) This name will be used internally to identify when a serialized module corresponds with this class.
    • typeDescription: Description for this type of module. This descriptio will be used to let the administrator identify what this module provides
    • iconFile: This is an icon file, in png format, used at administration client to identify this module. This parameter may be optionall if you override the “icon” method.
  • Own Methods:
    • __init__() The default constructor. The environment value is always provided (see Environment), but the default values provided can be None. Remember to allow the instantiation of the module with default params, because when deserialization is done, the process is first instatiate with an environment but no parameters and then call “unmarshal” from Serializable.

    • test()

    • check()

    • destroy(): Optional

    • icon(): Optional, if you provide an icon file, this method loads it from module folder, but you can override this so the icon is obtained from other source.

    • marshal() By default, this method serializes the values provided by user in form fields. You can override it, but now it’s not needed because you can access config vars using Form Fields.

      Anyway, if you override this method, you must also override next one

    • unmarshal() By default, this method de-serializes the values provided by user in form fields. You can override it, but now it’s not needed because you can access config vars using Form Fields.

      Anyway, if you override this method, you must also override previous one

  • UserInterface Methods:

Environmentable is a base class that provides utility method to access a separate Environment for every single module.

exception ValidationException

Exception used to indicate that the params assigned are invalid

Module.check()

Method that will provide the “check” capability for the module.

The return value that this method must provide is simply an string, preferable internacionalizated.

Returns:
Internacionalized (using ugettext) string of result of the check.
classmethod Module.description()

This method returns the “translated” description, that is, using ugettext for transforming cls.typeDescription.

Args:
cls: This is a class method, so cls is the class
Returns:
Translated description (using ugettext)
Module.destroy()

Invoked before deleting an module from database.

Do whatever needed here, as deleting associated data if needed (no example come to my head right now... :-) )

Returns:
Nothing
classmethod Module.icon(inBase64=True)

Reads the file specified by iconFile at module folder, and returns it content. This is used to obtain an icon so administration can represent it.

Args:

cls: Class

inBase64: If true, the image will be returned as base 64 encoded

Returns:
Base 64 encoded or raw image, obtained from the specified file at ‘iconFile’ class attribute
Module.isDirty()

This method informs the core if the module has changed serializable data, and that must be re-serialized

Default implemetation is that on every method call, module will be dirty

Note: The implementation of this is a work in progress, so right now the module will be serialized out on every acess

Module.marshal()

By default and if not overriden by descendants, this method, overridden from Serializable, and returns the serialization of form field stored values.

classmethod Module.name()

Returns “translated” typeName, using ugettext for transforming cls.typeName

Args:
cls: This is a class method, so cls is the class
Returns:
Translated type name (using ugettext)
static Module.test(env, data)

Test if the connection data is ok.

Returns an array, first value indicates “Ok” if true, “Bad” or “Error” if false. Second is a string describing operation

Args:

env: environment passed for testing (temporal environment passed)

data: data passed for testing (data obtained from the form definition)

Returns:
Array of two elements, first is True of False, depending on test (True is all right, false is error), second is an String with error, preferably internacionalizated..
classmethod Module.type()

Returns typeType

Args:
cls: This is a class method, so cls is the class
Returns:
the typeType of this class (or derived class)
Module.unmarshal(str_)

By default and if not overriden by descendants, this method recovers data serialized using serializeForm

Environmentable

class uds.core.Environmentable(environment)

This is a base class provided for all objects that have an environment associated. These are mainly modules

cache()

Utility method to access the cache of the environment containe by this object

Returns:
Cache for the object
env()

Utility method to access the envionment contained by this object

Returns:
Environmnet for the object
idGenerators(generatorId)

Utility method to access the id generator of the environment containe by this object

Args:
generatorId: Id of the generator to obtain
Returns:
Generator for the object and the id specified
setEnv(environment)

Assigns a new environment

Args:
environment: Environment to assign
storage()

Utility method to access the storage of the environment containe by this object

Returns:
Storage for the object

Serializable

class uds.core.Serializable

This class represents the interface that all serializable objects must provide.

Every single serializable class must implement marshall & unmarshall methods. Also, the class must allow to be initialized without parameters, so we can: - Initialize the object with default values - Read values from seralized data

marshal()

This is the method that must be overriden in order to serialize an object.

The system will use in fact ‘seralize’ and ‘deserialize’ methods, but theese are only suitable methods to “codify” serialized values

Note:This method must be overridden
serialize()

Serializes and “obfuscates’ the data.

The codec used to encode the string is obtained from the instance CODEC, so derived classes can overwrite this attribute to set another codec

unmarshal(str_)

This is the method that must be overriden in order to unserialize an object.

The system will use in fact ‘seralize’ and ‘deserialize’ methods, but theese are only convenients methods to “codify” serialized values.

Take into account that _str can be ‘’ (empty string), but hopefully it will never be none. In that case, initialize the object with default values

Args:
str_ _ : String readed from persistent storage to deseralilize
Note:This method must be overridden
unserialize(str_)

des-obfuscates the data and then de-serializes it via unmarshal method

The codec used to decode the string is obtained from the instance CODEC, so derived classes can overwrite this attribute to set another codec

UserInterface

UserInterface is the class responsible for managing the Field Descriptions of modules.

This fields descriptions are intended for allowing an easy exposition of configuration form via the administration interface.

You can obtain more information about user interface fields at User interface fields types.

class uds.core.ui.UserInterface.UserInterface(values=None)[source]

This class provides the management for gui descriptions (user forms)

Once a class is derived from this one, that class can contain Field Descriptions, that will be managed correctly.

By default, the values passed to this class constructor are used to fill the gui form fields values.

classmethod guiDescription(obj=None)[source]

This simple method generates the gui description needed by the administration client, so it can represent it at user interface and manage it.

Args:
object: If not none, object that will get its “initGui” invoked
This will only happen (not to be None) in Services.
initGui()[source]

This method gives the oportunity to initialize gui fields before they are send to administartion client. We need this because at initialization time we probably don’t have the data for gui.

Note:This method is used as a “trick” to allow to modify default form data for services. Services are child of Service Providers, and will probably need data from Provider to fill initial form data. The rest of modules will not use this, and this only will be used when the user requests a new service or wants to modify existing one.
Note:There is a drawback of this, and it is that there is that this method will modify service default data. It will run fast (probably), but may happen that two services of same type are requested at same time, and returned data will be probable a nonsense. We will take care of this posibility in a near version...
serializeForm()[source]

All values stored at form fields are serialized and returned as a single string Separating char is

The returned string is zipped and then converted to base 64

Note: Hidens are not serialized, they are ignored

unserializeForm(values)[source]

This method unserializes the values previously obtained using serializeForm(), and stores the valid values form form fileds inside its corresponding field

valuesDict()[source]

Returns own data needed for user interaction as a dict of key-names -> values. The values returned must be strings.

Example:

we have 2 text field, first named “host” and second named “port”, we can do something like this:

return { 'host' : self.host, 'port' : self.port }

(Just the reverse of __init__(), __init__ receives this dict, valuesDict must return the dict)

Names must coincide with fields declared.

Returns:
Dictionary, associated with declared fields. Default implementation returns the values stored at the gui form fields declared.
Note:By default, the provided method returns the correct values extracted from form fields