Built in data models

Camelot comes with a number of built in data models. To avoid boiler plate models needed in almost any application (like Persons, Addresses, etc.), the developer is encouraged to use these data models as a start for developing custom applications.

Modules

The camelot.model module contains a number of submodules, each with a specific purpose

To activate such a submodule, the submodule should be imported in the setup_model method of settings class, before the tables are created

def setup_model( self ):
    from camelot.core.sql import metadata
    metadata.bind = self.ENGINE()
    from camelot.model import authentication
    from camelot.model import party
    from camelot.model import i18n
    from camelot.core.orm import setup_all
    setup_all( create_tables=True )

Persons and Organizations

Set of classes to store persons, organizations, relationships and contact mechanisms

These structures are modeled like described in ‘The Data Model Resource Book’ by Len Silverston, Chapter 2

class camelot.model.party.Address(*args, **kwargs)[source]

The Address to be given to a Party (a Person or an Organization)

id

The primary key

class camelot.model.party.AddressAdmin(app_admin, entity)[source]

Admin with only the Address information and not the Party information

class camelot.model.party.City(*args, **kwargs)[source]

A subclass of GeographicBoundary used to store the name, the postal code and the Country of a city

id

The primary key

class camelot.model.party.Country(*args, **kwargs)[source]

A subclass of GeographicBoundary used to store the name and the ISO code of a country

id

The primary key

class camelot.model.party.GeographicBoundary(*args, **kwargs)[source]

The base class for Country and City

id

The primary key

class camelot.model.party.Organization(*args, **kwargs)[source]

An organization represents any internal or external organization. Organizations can include businesses and groups of individuals

id

The primary key

class camelot.model.party.Party(*args, **kwargs)[source]

Base class for persons and organizations. Use this base class to refer to either persons or organisations in building authentication systems, contact management or CRM

id

The primary key

class camelot.model.party.Person(*args, **kwargs)[source]

Person represents natural persons

id

The primary key

I18N

Set of classes to store internationalization data in the database. Camelot applications can be translated by the developer using regular PO files, or by the user. In case the user makes a translation, this translation is stored into the Translation table. This table can be exported to PO files for inclusion in the development cycle.

class camelot.model.i18n.Translation(*args, **kwargs)[source]

Table to store user generated translations or customization.

id

The primary key

classmethod translate(source, language)[source]

Translate source to language, return None if no translation is found

classmethod translate_or_register(source, language)[source]

Translate source to language, if no translation is found, register the source as to be translated and return the source

Fixture

class camelot.model.fixture.Fixture(*args, **kwargs)[source]

Keep track of static data loaded into the database. This class keeps track of data inserted into the database by storing the primary key and the class name of the inserted data, and associating this with a fixture key specified by the developer.

The developer can then use the fixture key to find out if this data has been stored in the database, or to update it in future versions of the application.

Only classes which have an integer field as their primary key can be tracked.

classmethod find_fixture(entity, fixture_key, fixture_class=None)[source]

Find data that has been stored for a fixture key.

Parameters:
  • entity – the class of the stored data
  • fixture_key – a string used to refer to the stored data
  • fixture_class – a string used to refer to a group of stored data
Returns:

a instance of type entity, or None if no fixture is found

classmethod find_fixture_key(entity, primary_key)[source]

Find the fixture key for an object of type entity with primary key

Parameters:
  • entity – the class of the stored data
  • primary_key – the integer primary key of the stored data
Returns:

a string with the fixture_key that refers to this data, None if no such data is found

classmethod find_fixture_key_and_class(obj)[source]

Find out if an object was stored in the database through the fixture mechanism and return its fixture_key and fixture_class

Parameters:obj – the object stored in the database
Returns:(fixture_key, fixture_class) if the object was registered

through the fixture mechanism, (None, None) otherwise

classmethod find_fixture_keys_and_classes(entity)[source]

Load all fixture keys of a certain entity class in batch.

Parameters:entity – the class of the stored data
Returns:a dictionary mapping the primary key of a on object of type entity to a tuple of type (fixture key, fixture class)
classmethod find_fixture_reference(entity, fixture_key, fixture_class=None)[source]

Find the Fixture instance that refers to the data stored for a fixture key.

Parameters:
  • entity – the class of the stored data
  • fixture_key – a string used to refer to the stored data
  • fixture_class – a string used to refer to a group of stored data
Returns:

a Fixture instance refering to the stored data, or None of no data was found.

id

The primary key

classmethod insert_or_update_fixture(entity, fixture_key, values, fixture_class=None)[source]

Store data in the database through the fixture mechanism, to be able to keep track of it later.

Parameters:
  • entity – the class of the stored data
  • fixture_key – a string used to refer to the stored data
  • values – a dictionary with the data that should be insert or updated in the database
  • fixture_class – a string used to refer to a group of stored data
Returns:

an object of type entity, either created or modified

classmethod remove_all_fixtures(entity)[source]

Remove all data of a certain class from the database, if it was stored through the fixture mechanism.

Parameters:entity – the class of the stored data
classmethod remove_fixture(entity, fixture_key, fixture_class)[source]

Remove data from the database, if it was stored through the fixture mechanism.

Parameters:
  • entity – the class of the stored data
  • fixture_key – a string used to refer to the stored data
  • fixture_class – a string used to refer to a group of stored data
class camelot.model.fixture.FixtureVersion(*args, **kwargs)[source]

Keep track of the version the fixtures have in the current database, the subversion revision number is a good candidate to be used as a fixture version.

classmethod get_current_version(fixture_class=None, session=None)[source]

Get the current version of the fixtures in the database for a certain fixture class.

Parameters:
  • fixture_class – the fixture class for which to get the version
  • session – the session to use to query the database, if None is given, the default Camelot session is used
Returns:

an integer representing the current version, 0 if no version found

classmethod set_current_version(fixture_class=None, fixture_version=0, session=None)[source]

Set the current version of the fixtures in the database for a certain fixture class.

Parameters:
  • fixture_class – the fixture class for which to get the version
  • fixture_version – the version number to which to set the fixture version
  • session – the session to use to query the database, if None is given, the default Camelot session is used

Authentication

Set of classes to store authentication and permissions

class camelot.model.authentication.AuthenticationGroup(*args, **kwargs)[source]
A group of users (defined by their AuthenticationMechanism).
Different roles can be assigned to a group.
../_images/new_view_authenticationgroup.png

mapped to authentication_group

id

The primary key, int, required

name

str, required, length : 256

class camelot.model.authentication.AuthenticationGroupRole(*args, **kwargs)[source]

Table with the different roles associated with an AuthenticationGroup

class camelot.model.authentication.AuthenticationMechanism(*args, **kwargs)[source]
../_images/new_view_authenticationmechanism.png

mapped to authentication_mechanism

authentication_type

str, required, possible values : operating_system/database

from_date

date, required

get_representation()[source]
Returns:a QtGui.QImage object with the avatar of the user, or None.
has_role(role_name)[source]
Parameters:role_name – a string with the name of the role
:return; True if the user is associated to this role, otherwise
False.
id

The primary key, int, required

last_login

datetime, not required

password

str, not required, length : 200

representation

str, not required

set_representation(image)[source]
Parameters:image – a QtGui.QImage object with the avatar of the user, or None.
thru_date

date, required

username

str, required, length : 40

camelot.model.authentication.get_current_authentication(_obj=None)[source]

Get the currently logged in :class:’AuthenticationMechanism’

camelot.model.authentication.update_last_login(initial_group_name=None, initial_group_roles=[])[source]

Update the last login of the currently logged in user to now. If there is no AuthenticationGroup yet in the database, create one and add the user to it. This can be used to bootstrap the authentication system and create an admin group and add the user to it.

Parameters:
  • initial_group_name – The name of the authentication group that needs to be created if there is none yet.
  • initial_group_roles – a list with the roles for the initial group

Batch Jobs

Most applications need to perform some scheduled jobs to process information. Users need to be able to monitor the functioning of those scheduled jobs.

These classes provide the means to store the result of batch jobs to enable the user to review or plan them.

class camelot.model.batch_job.BatchJob(*args, **kwargs)[source]

A batch job is a long running task that is scheduled by the user or started periodically. The BatchJob objects can be used to store information on such running task so the end user can review them

add_exception_to_message(exc_type=None, exc_val=None, exc_tb=None)[source]

If an exception occurs in a batch job, this method can be used to add the stack trace of an exception to the message.

If no arguments are given, sys.exc_traceback is used.

Parameters:
  • exc_type – type of the exception, such as in sys.exc_type
  • exc_val – value of the exception, such as in sys.exc_value
  • exc_tb – a traceback object, such as in sys.exc_traceback
add_strings_to_message(strings, color=None)[source]

Add strings to the message of this batch job.

This method executes within it’s own transaction, to make sure the state of the session is rolled back on failure.

Parameters:
  • strings – a list or generator of strings
  • color – the html color to be used for the strings (‘red’,

‘green’, ...), None if the color needs no change.

classmethod create(batch_job_type=None, status='running')[source]

Create a new batch job object in a session of its own. This allows to flus the batch job independent from other objects, as well as to begin/end/rollback it’s session without affecting other objects.

Parameters:
Returns:

a new BatchJob object

id

The primary key

is_canceled()[source]

Verifies if this Batch Job is canceled. Returns True if it is. This method is thus suiteable to call inside a running batch job to verifiy if another user has canceled the running job. Create a batch job object through the create() method to make sure requesting the status does not interfer with the normal session.

This method executes within it’s own transaction, to make sure the state of the session is rolled back on failure.

Returns:True or False
class camelot.model.batch_job.BatchJobType(*args, **kwargs)[source]

The type of batch job, the user will be able to filter his jobs based on their type. A type might be ‘Create management reports’

id

The primary key

A batch job object can be used as a context manager :

        from camelot.model.batch_job import BatchJob, BatchJobType
        synchronize = BatchJobType.get_or_create( u'Synchronize' )
        with BatchJob.create( synchronize ) as batch_job:
            batch_job.add_strings_to_message( [ u'Synchronize part A',
                                                u'Synchronize part B' ] )
            batch_job.add_strings_to_message( [ u'Done' ], color = 'green' )

Whenever an exception happens inside the with block, the stack trace of this exception will be written to the bach job object and it’s status will be set to errors. At the end of the with block, the status of the batch job will be set to finished.

History tracking

The ORM part of the classes that store the change history of objects to the database. The table defined here is used in camelot.core.memento to store the changes.

To prevent this table to be used to store changes, overwrite the camelot.admin.application_admin.ApplicationAdmin.get_memento() method the custom ApplicationAdmin.

class camelot.model.memento.Memento(*args, **kwargs)[source]

Keeps information on the previous state of objects, to keep track of changes and enable restore to that previous state

id

The primary key

class camelot.model.memento.PreviousAttribute(attribute, previous_value)[source]

Helper class to display previous attributes

Customization

Adding fields

Sometimes the built in models don’t have all the fields or relations required for a specific application. Fortunately it is possible to add fields to an existing model on a per application base.

To do so, simply assign the required fields in the application specific model definition, before the tables are created.

        party.Person.language = schema.Column( types.Unicode(30) )
        
        metadata.create_all()
        p = party.Person( first_name = u'Peter', 
                          last_name = u'Principle', 
                          language = u'English' )
        session.flush()