Fields

SQLAlchemy comes with a default set of field types that can be used. These field types will trigger the use of certain delegates and editors to visualize them in the views. Camelot extends those SQLAlchemy field types with some of its own.

An overview of field types from SQLAlchemy and Camelot is given in the table below :

Field types handled through introspection :

Field type Default delegate Default editor
BOOLEAN BoolDelegate ../_images/BoolEditor_editable.png
Boolean BoolDelegate ../_images/BoolEditor_editable.png
Code CodeDelegate ../_images/CodeEditor_editable.png
Color ColorDelegate ../_images/ColorEditor_editable.png
Date DateDelegate ../_images/DateEditor_editable.png
DateTime DateTimeDelegate ../_images/DateTimeEditor_editable.png
Enumeration EnumerationDelegate ../_images/ChoicesEditor_editable.png
File FileDelegate ../_images/FileEditor_editable.png
Float FloatDelegate ../_images/FloatEditor_editable.png
INTEGER IntegerDelegate ../_images/IntegerEditor_editable.png
IPAddress CodeDelegate ../_images/CodeEditor_editable.png
Image ImageDelegate ../_images/ImageEditor_editable.png
Integer IntegerDelegate ../_images/IntegerEditor_editable.png
Language LanguageDelegate ../_images/LanguageEditor_editable.png
Numeric FloatDelegate ../_images/FloatEditor_editable.png
Rating StarDelegate ../_images/StarEditor_editable.png
RichText RichTextDelegate ../_images/RichTextEditor_editable.png
String PlainTextDelegate ../_images/TextLineEditor_editable.png
TEXT PlainTextDelegate ../_images/TextLineEditor_editable.png
Time TimeDelegate ../_images/TimeEditor_editable.png
Unicode PlainTextDelegate ../_images/TextLineEditor_editable.png
VirtualAddress VirtualAddressDelegate ../_images/VirtualAddressEditor_editable.png

SQLAlchemy field types

SQLAlchemy provides a number of field types that map to available data types in SQL, more information on those can be found on the SQLAlchemy website .

The types used mosed common are :

class sqlalchemy.types.Boolean(create_constraint=True, name=None)[source]

A bool datatype.

Boolean typically uses BOOLEAN or SMALLINT on the DDL side, and on the Python side deals in True or False.

class sqlalchemy.types.Date(*args, **kwargs)[source]

A type for datetime.date() objects.

class sqlalchemy.types.DateTime(timezone=False)[source]

A type for datetime.datetime() objects.

Date and time types return objects from the Python datetime module. Most DBAPIs have built in support for the datetime module, with the noted exception of SQLite. In the case of SQLite, date and time types are stored as strings which are then converted back to datetime objects when rows are returned.

class sqlalchemy.types.Float(precision=None, asdecimal=False, **kwargs)[source]

A type for float numbers.

Returns Python float objects by default, applying conversion as needed.

class sqlalchemy.types.Integer(*args, **kwargs)[source]

A type for int integers.

class sqlalchemy.types.Numeric(precision=None, scale=None, asdecimal=True)[source]

A type for fixed precision numbers.

Typically generates DECIMAL or NUMERIC. Returns decimal.Decimal objects by default, applying conversion as needed.

class sqlalchemy.types.Time(timezone=False)[source]

A type for datetime.time() objects.

class sqlalchemy.types.Unicode(length=None, **kwargs)[source]

A variable length Unicode string.

The Unicode type is a String which converts Python unicode objects (i.e., strings that are defined as u'somevalue') into encoded bytestrings when passing the value to the database driver, and similarly decodes values from the database back into Python unicode objects.

It’s roughly equivalent to using a String object with convert_unicode=True, however the type has other significances in that it implies the usage of a unicode-capable type being used on the backend, such as NVARCHAR. This may affect what type is emitted when issuing CREATE TABLE and also may effect some DBAPI-specific details, such as type information passed along to setinputsizes().

When using the Unicode type, it is only appropriate to pass Python unicode objects, and not plain str. If a bytestring (str) is passed, a runtime warning is issued. If you notice your application raising these warnings but you’re not sure where, the Python warnings filter can be used to turn these warnings into exceptions which will illustrate a stack trace:

import warnings
warnings.simplefilter('error')

Bytestrings sent to and received from the database are encoded using the dialect’s encoding, which defaults to utf-8.

Camelot field types

Camelot extends the SQLAlchemy field types with a number of its own field types. Those field types are automatically mapped to a specific delegate taking care of the visualisation.

Those fields are stored in the camelot.types module.

class camelot.types.Code(parts, separator=u'.', **kwargs)[source]

SQLAlchemy column type to store codes. Where a code is a list of strings on which a regular expression can be enforced.

This column type accepts and returns a list of strings and stores them as a string joined with points.

eg: ['08', 'AB'] is stored as 08.AB

../_images/CodeEditor_editable.png
Code.impl

alias of Unicode

class camelot.types.Color[source]

The Color field returns and accepts tuples of the form (r,g,b,a) where r,g,b,a are integers between 0 and 255. The color is stored as an hexadecimal string of the form AARRGGBB into the database, where AA is the transparency, RR is red, GG is green BB is blue:

class MovieType(Entity):
    color = Field(camelot.types.Color())
../_images/ColorEditor_editable.png

The colors are stored in the database as strings.

Use:

QColor(*color) 

to convert a color tuple to a QColor.

Color.impl

alias of Unicode

class camelot.types.Enumeration(choices=[], **kwargs)[source]

The enumeration field stores integers in the database, but represents them as strings. This allows efficient storage and querying while preserving readable code.

Typical use of this field would be a status field.

Enumeration fields are visualized as a combo box, where the labels in the combo box are the capitalized strings:

class Movie(Entity):
  title = Field(Unicode(60), required=True)
  state = Field(camelot.types.Enumeration([(1,'planned'), (2,'recording'), (3,'finished'), (4,'canceled')]), 
                                          index=True, required=True, default='planning')
../_images/ChoicesEditor_editable.png

If None should be a possible value of the enumeration, add (None, None) to the list of possible enumerations. None will be presented as empty in the GUI.

Enumeration.impl

alias of Integer

class camelot.types.File(max_length=100, upload_to='', storage=<class 'camelot.core.files.storage.Storage'>, **kwargs)[source]

Sqlalchemy column type to store files. Only the location of the file is stored

This column type accepts and returns a StoredFile. The name of the file is stored as a string in the database. A subdirectory upload_to can be specified:

class Movie(Entity):
  script = Field(camelot.types.File(upload_to='script'))
../_images/FileEditor_editable.png

Retrieving the actual storage from a File field can be a little cumbersome. The easy way is taking it from the field attributes, in which it will be put by default. If no field attributes are available at the location where the storage is needed, eg in some function doing document processing, one needs to go through SQLAlchemy to retrieve it.

For an ‘task’ object with a File field named ‘document’, the storage can be retrieved:

from sqlalchemy import orm

task_mapper = orm.object_mapper( task )
document_property = task_mapper.get_property('document')
storage = document_property.columns[0].type.storage
File.impl

alias of Unicode

File.stored_file_implementation

alias of StoredFile

class camelot.types.Image(max_length=100, upload_to='', storage=<class 'camelot.core.files.storage.Storage'>, **kwargs)[source]

Sqlalchemy column type to store images

This column type accepts and returns a StoredImage, and stores them in the directory specified by settings.CAMELOT_MEDIA_ROOT. The name of the file is stored as a string in the database.

The Image field type provides the same functionallity as the File field type, but the files stored should be images.

../_images/ImageEditor_editable.png
Image.stored_file_implementation

alias of StoredImage

class camelot.types.Language[source]

The languages are stored as a string in the database of the form language[_country], where :

  • language is a lowercase, two-letter, ISO 639 language code,
  • territory is an uppercase, two-letter, ISO 3166 country code

This used to be implemented using babel, but this was too slow and used too much memory, so now it’s implemented using QT.

Language.impl

alias of Unicode

class camelot.types.Rating(*args, **kwargs)[source]

The rating field is an integer field that is visualized as a number of stars that can be selected:

class Movie(Entity):
  title = Field(Unicode(60), required=True)
  rating = Field(camelot.types.Rating())
../_images/StarEditor_editable.png
Rating.impl

alias of Integer

class camelot.types.RichText(*args, **kwargs)[source]

RichText fields are unlimited text fields which contain html. The html will be rendered in a rich text editor.

../_images/RichTextEditor_editable.png
RichText.impl

alias of UnicodeText

class camelot.types.VirtualAddress(*args, **kwargs)[source]

A single field that can be used to enter phone numbers, fax numbers, email addresses, im addresses. The editor provides soft validation of the data entered. The address or number is stored as a string in the database.

This column type accepts and returns tuples of strings, the first string is the virtual_address_type, and the second the address itself.

eg: ('email','project-camelot@conceptive.be') is stored as email://project-camelot@conceptive.be

../_images/virtualaddress_editor.png
VirtualAddress.impl

alias of Unicode

Table Of Contents

Previous topic

Creating models

Next topic

Calculated Fields

This Page


Comments
blog comments powered by Disqus