rum.fields

This modules provides a layer to decouple resource field types from the view factory that will generate the views for the repository items.

These objects just serve as metadata, they do not do anything and do not depend on any specific library. They are here just to serve as a common vocabulary between plugins to know what kind of object a field is.

It is the responsability of the rum.interfaces.IRepositoryFactory implementation to provide this metadata about the resources it knows how to handle.

Two distinct plugins that depend on each other just to share a definition of a Field should get in touch to get the Field declaration included here in order to decouple from each other.

class rum.fields.FieldFactory

defaults(resource)

Returns a dict with default values to populate an instance of resource.

classmethod fields(*fields, **kw)

Associates a series of rum.fields.Field instances to a model class.

This rum.fields.Field are queried by the rum.view.ViewFactory and give it a hint on how it should generate the interface.

It can be placed right in the model class it assigns metadata to like a “class decorator”:

>>> class Peanut(object):
...     FieldFactory.fields(
...         Unicode("name", required=True),
...         Integer("weight")
...     )

Or the binding can be done elsewhere (anywhere both the model and fields can be imported). This is useful to avoid contaminating your models with Rum imports:

>>> class Orange(object):
...     pass

Then in some other module:

>>> FieldFactory.fields(Orange, [
...     Unicode("name", required=True),
...     Integer("weight")
... ])
<class 'rum.fields.Orange'>

Note

This module needs to be imported somehow since if it’s not the fields will not be registered and Rum will try to guess them.

Both ways are equivalent, use the one you find more pleasing to the eye or allows you to structure your code better.

Notice that (in both situations) the original class is returned as-is, it is not modified in any way (the registry lives inside PEAK-Rules if you’re wondering)

There’s a third syntax to override just one field:

>>> FieldFactory.fields(Orange, "weight", Unicode("weight"))
<class 'rum.fields.Orange'>

Fields registered this way will override fields registered in any of the other two ways.

fields() accepts one keyword argument:

prio

Priority of the generated rule, it will be passed to when, again this parameter is very unlikely that it’ll ever be needed.

Note

Remember, the View can do whatever it feels like with this information. These are just hints.

get(resource, attr=None, args=None)

Returns a rum.fields.Field subclass.

rum.fields.rum_setattr(obj, attr, value)

attribute of resource objects should always be set by this function

rum.fields.rum_getattr(obj, attr)

attribute of resource objects should always be fetched by this function

class rum.fields.Boolean(name, required=False, label=None, default=NoDefault, read_only=False, searchable=False, sortable=True, description='')

This Field holds a boolean value

Examples:

>>> Boolean(name='name')
rum.fields.Boolean(name='name', required=False, label='Name', default=NoDefault, read_only=False, searchable=False, sortable=True, description='')

class rum.fields.Collection(name, other, remote_name, required=False, label=None, default=NoDefault, read_only=False, searchable=False, sortable=False, description='', expression='')

This Relation represents a relation to a collection of objects

Examples:

>>> class Related: pass
>>> Collection(name='name', other=Related, remote_name='related') 
rum.fields.Collection(name='name', other=<class rum.fields.Related at ...>, remote_name='related', required=False, label='Name', default=NoDefault, read_only=False, searchable=False, sortable=False, description='', expression='')

class rum.fields.Date(name, required=False, label=None, default=NoDefault, read_only=False, sortable=True, searchable=False, description='')

This Field represents a date

Examples:

>>> Date(name='pub_date')
rum.fields.Date(name='pub_date', required=False, label='Pub date', default=NoDefault, read_only=False, sortable=True, searchable=False, description='')

class rum.fields.DateTime(name, required=False, label=None, default=NoDefault, read_only=False, has_timezone=False, sortable=True, searchable=False, description='')

This Field represents a time with an associated date.

Examples:

>>> DateTime(name='name', has_timezone=True)
rum.fields.DateTime(name='name', required=False, label='Name', default=NoDefault, read_only=False, has_timezone=True, sortable=True, searchable=False, description='')

class rum.fields.Decimal(name, required=False, label=None, default=NoDefault, read_only=False, range=(None, None), precision=4, sortable=True, searchable=True, description='')

This Field holds a real number

Attributes

precision

Number of digits in the decimal part.

Examples:

>>> Decimal(name='name', range=(10,50), precision=10)
rum.fields.Decimal(name='name', required=False, label='Name', default=NoDefault, read_only=False, range=(10, 50), precision=10, sortable=True, searchable=True, description='')

class rum.fields.Email(name, required=False, label=None, default=NoDefault, read_only=False, length=None, sortable=True, searchable=True, description='')

This Field is a String but signals the GUI and validation framework that is should contain a valid email address.

Examples:

>>> Email(name='name', length=50)
rum.fields.Email(name='name', required=False, label='Name', default=NoDefault, read_only=False, length=50, sortable=True, searchable=True, description='')

class rum.fields.Field(name, required=False, label=None, default=NoDefault, read_only=False, searchable=False, sortable=False, description='')

A field base class

Attributes

name

The name of the field. Should be the same as the name of the attribute of the resource it models.

required

Is this field required?

label

The label for this field. If None it will be derived from name

default

Default value for this field.

read_only

Set to True if no GUI should be generated to allow this field to be modified

Examples:

>>> Field(name='name')
rum.fields.Field(name='name', required=False, label='Name', default=NoDefault, read_only=False, searchable=False, sortable=False, description='')

class rum.fields.ForeignKey(type, order=None, searchable=False, target='')

This Field represents a foreign key. It normally signals the GUI not to render it at all and use the associated Relation instead.

It’s name and required flag are derived from type

Attributes

type

The Field for this FK.

order

If this is a composite foreign key the this is the index of the fk tuple this key goes in. If the FK is not composite then leave it to None

target

Textual representation of the constraint target column. This just for documentation.

Examples:

>>> ForeignKey(Integer('id'))
rum.fields.ForeignKey(type=rum.fields.Integer(name='id', required=False, label='Id', default=NoDefault, read_only=False, range=(None, None), sortable=True, searchable=True, description=''), order=None, searchable=False, target='')
>>> ForeignKey(Integer('id', required=True, description=''), order=0)
rum.fields.ForeignKey(type=rum.fields.Integer(name='id', required=True, label='Id', default=NoDefault, read_only=False, range=(None, None), sortable=True, searchable=True, description=''), order=0, searchable=False, target='')

class rum.fields.HTMLText(name, required=False, label=None, default=NoDefault, read_only=False, length=None, sortable=True, searchable=True, description='')

This Field is a UnicodeText but the GUI should render some sort of fancy control to edit HTML.

Examples:

>>> HTMLText(name='name', length=50)
rum.fields.HTMLText(name='name', required=False, label='Name', default=NoDefault, read_only=False, length=50, sortable=True, searchable=True, description='')

class rum.fields.Integer(name, required=False, label=None, default=NoDefault, read_only=False, range=(None, None), sortable=True, searchable=True, description='')

This Field is a Number that can only hold int or long numbers.

Examples:

>>> Integer(name='name', range=(10,50))
rum.fields.Integer(name='name', required=False, label='Name', default=NoDefault, read_only=False, range=(10, 50), sortable=True, searchable=True, description='')

class rum.fields.InternalField(type, searchable=False, description='')

This Field represents a field which is an implementation detail. An should not be shown in the GUI.

Attributes

type

The real Field this attribute represents if it weren’t an implementation detail. name and required are autogenerated from this Field

Examples:

>>> InternalField(Integer('id'))
rum.fields.InternalField(type=rum.fields.Integer(name='id', required=False, label='Id', default=NoDefault, read_only=False, range=(None, None), sortable=True, searchable=True, description=''), searchable=False, description='')

class rum.fields.List(name, other, remote_name, required=False, label=None, default=NoDefault, read_only=False, searchable=False, sortable=False, description='', expression='')

This Relation represents a relation to an ordered list of objects

Examples:

>>> class Related: pass
>>> List(name='name', other=Related, remote_name='related', expression='') 
rum.fields.List(name='name', other=<class rum.fields.Related at ...>, remote_name='related', required=False, label='Name', default=NoDefault, read_only=False, searchable=False, sortable=False, description='', expression='')

class rum.fields.Mapping(name, other, remote_name, required=False, label=None, default=NoDefault, read_only=False, searchable=False, sortable=False, description='', expression='')

This Relation represents a relation to mapping of objects by some key. (think of a dictionary)

Examples:

>>> class Related: pass
>>> Mapping(name='name', other=Related, remote_name='related') 
rum.fields.Mapping(name='name', other=<class rum.fields.Related at ...>, remote_name='related', required=False, label='Name', default=NoDefault, read_only=False, searchable=False, sortable=False, description='', expression='')

class rum.fields.Number(name, required=False, label=None, default=NoDefault, read_only=False, range=(None, None), sortable=True, searchable=True, description='')

This Field holds a number

Attributes

range

A tuple that holds the bounds of the range of (min,max) values the field can hold. A value of None at either end means the range is not bounded on that direction.

Examples:

>>> Number(name='name', range=(10,50))
rum.fields.Number(name='name', required=False, label='Name', default=NoDefault, read_only=False, range=(10, 50), sortable=True, searchable=True, description='')

class rum.fields.Password(name, required=False, label=None, default=NoDefault, read_only=False, length=None, sortable=False, searchable=False, description='')

This Field is a Unicode which holds a password. It signals the GUI to handle it in a special way (eg: by not showing it, etc...)

Examples:

>>> Password(name='password', length=50)
rum.fields.Password(name='password', required=False, label='Password', default=NoDefault, read_only=False, length=50, sortable=False, searchable=False, description='')

class rum.fields.PolymorphicDiscriminator(type, searchable=False, description='')

This Field represents a polymorphic discriminator. This makes sense for SQLAlchemy really but other backend might find it useful perhaps.

>>> PolymorphicDiscriminator(String('type'))
rum.fields.PolymorphicDiscriminator(type=rum.fields.String(name='type', required=False, label='Type', default=NoDefault, read_only=False, length=None, sortable=True, searchable=True, description=''), searchable=False, description='')

class rum.fields.PreformattedText(name, required=False, label=None, default=NoDefault, read_only=False, length=None, sortable=True, searchable=True, description='')

This Field is a PreformattedText, which should use html pre tags when displayed.

Examples:

>>> PreformattedText(name='name', length=50)
rum.fields.PreformattedText(name='name', required=False, label='Name', default=NoDefault, read_only=False, length=50, sortable=True, searchable=True, description='')

class rum.fields.PrimaryKey(type, auto=True, order=None)

This Field represents a primary key. It normally signals the GUI to render a disabled field or not render it at all on edit forms.

If it is autogenerated then it will probably not be rendered at all.

Attributes

auto

A flag that signals that the underlying data store will autogenerate the key This will probably make the GUI hide the field when creating a new object and mark this field as not required so validation doesn’t fail when it’s missing. (The underlying type will still be marked as required though)

order

If this is a composite primary key the this is the index of the pk tuple this key goes in. If the PK is not composite then leave it to None

Examples:

>>> PrimaryKey(Integer('id'))
rum.fields.PrimaryKey(type=rum.fields.Integer(name='id', required=True, label='Id', default=NoDefault, read_only=False, range=(None, None), sortable=True, searchable=True, description=''), auto=True, order=None)
>>> PrimaryKey(Integer('id'), auto=False)
rum.fields.PrimaryKey(type=rum.fields.Integer(name='id', required=True, label='Id', default=NoDefault, read_only=False, range=(None, None), sortable=True, searchable=True, description=''), auto=False, order=None)

class rum.fields.RelatedField(related_to, real_field, label=None)

This Field represents a field of a related object. An should not be shown in the GUI.

Attributes

real_field

The real Field this attribute represents

related_to

The resource real_field belongs to, given as a Relation

Examples::

>>> class Foo(object): pass
>>> RelatedField(real_field=Integer('id'), related_to=Relation('foo', other=Foo, remote_name=None), label='foo.id')
rum.fields.RelatedField(related_to=rum.fields.Relation(name='foo', other=<class 'rum.fields.Foo'>, remote_name=None, required=False, label='Foo', default=NoDefault, read_only=False, searchable=False, sortable=False, description='', expression=''), real_field=rum.fields.Integer(name='id', required=False, label='Id', default=NoDefault, read_only=False, range=(None, None), sortable=True, searchable=True, description=''), label='foo.id')

next_relation_in_chain()

for person.address.town return Person class, the next resource in the chain of the relation. This in encapsulated deep in the field >>> class Person(object): pass >>> class Address(object): pass >>> class town(object): pass >>> f=RelatedField(related_to=RelatedField( related_to=Relation(name=’person’, remote_name=None, other=Person), real_field=Relation(name=’address’, remote_name=None, other=Address), label=’person.address’ ), real_field=String(name=’town’), label=’person.address.town’) >>> f.next_relation_in_chain() rum.fields.Relation(name=’person’, other=<class ‘rum.fields.Person’>, remote_name=None, required=False, label=’Person’, default=NoDefault, read_only=False, searchable=False, sortable=False, description=’‘, expression=’‘)

class rum.fields.Relation(name, other, remote_name, required=False, label=None, default=NoDefault, read_only=False, searchable=False, sortable=False, description='', expression='')

This Field represents a relation to another object

Attributes

other

The resource class this field relates to.

expression

textual presentation of a join condition if present, for documentation only.

Examples:

>>> class Related: pass
>>> Relation(name='name', other=Related, remote_name='related') 
rum.fields.Relation(name='name', other=<class rum.fields.Related at ...>, remote_name='related', required=False, label='Name', default=NoDefault, read_only=False, searchable=False, sortable=False, description='', expression='')

class rum.fields.String(name, required=False, label=None, default=NoDefault, read_only=False, length=None, sortable=True, searchable=True, description='')

This Field represents an ascii string.

Attributes

length

The maximum number of characters this field can hold. Leave as None if length should not be checked.

Examples:

>>> String(name='name', length=50)
rum.fields.String(name='name', required=False, label='Name', default=NoDefault, read_only=False, length=50, sortable=True, searchable=True, description='')

class rum.fields.Text(name, required=False, label=None, default=NoDefault, read_only=False, length=None, sortable=True, searchable=True, description='')

This Field is a String but the GUI should render a textarea of some other sort of control to manipulate a chunk of text.

Examples:

>>> Text(name='name', length=50)
rum.fields.Text(name='name', required=False, label='Name', default=NoDefault, read_only=False, length=50, sortable=True, searchable=True, description='')

class rum.fields.Time(name, required=False, label=None, default=NoDefault, read_only=False, has_timezone=False, sortable=True, searchable=False, description='')

This Field represents a time

Attributes

has_timezone

A flag that indicates if this field is timezone aware

Examples:

>>> Time(name='name', has_timezone=True)
rum.fields.Time(name='name', required=False, label='Name', default=NoDefault, read_only=False, has_timezone=True, sortable=True, searchable=False, description='')

class rum.fields.ToOneRelation(name, other, remote_name, required=False, label=None, default=NoDefault, read_only=False, searchable=False, sortable=False, description='', expression='')

This Field represents a relation to another object

Examples:

>>> class Related: pass
>>> ToOneRelation(name='name', other=Related, remote_name='related') 
rum.fields.ToOneRelation(name='name', other=<class rum.fields.Related at ...>, remote_name='related', required=False, label='Name', default=NoDefault, read_only=False, searchable=False, sortable=False, description='', expression='')

class rum.fields.Unicode(name, required=False, label=None, default=NoDefault, read_only=False, length=None, sortable=True, searchable=True, description='')

This Field is a String but can hold unicode strings.

Examples:

>>> Unicode(name='name', length=50, description='foo')
rum.fields.Unicode(name='name', required=False, label='Name', default=NoDefault, read_only=False, length=50, sortable=True, searchable=True, description='foo')

class rum.fields.UnicodeText(name, required=False, label=None, default=NoDefault, read_only=False, length=None, sortable=True, searchable=True, description='')

This Field is a Unicode but the GUI should render a textarea of some other sort of control to manipulate a chunk of text.

Examples:

>>> Unicode(name='name', length=50)
rum.fields.Unicode(name='name', required=False, label='Name', default=NoDefault, read_only=False, length=50, sortable=True, searchable=True, description='')

class rum.fields.Url(name, required=False, label=None, default=NoDefault, read_only=False, length=None, sortable=True, searchable=True, description='')

This Field is a String but signals the GUI and validation framework that is should contain a valid URL.

Examples:

>>> Url(name='name', length=50)
rum.fields.Url(name='name', required=False, label='Name', default=NoDefault, read_only=False, length=50, sortable=True, searchable=True, description='')

class rum.fields.VersionID(type, searchable=False, description='')

This Field represents a version id field used implement optimistic locking of model instances to avoid concurrent modification. This makes sense for SQLAlchemy really but other backend might find it useful too.

>>> VersionID(Integer('version'))
rum.fields.VersionID(type=rum.fields.Integer(name='version', required=False, label='Version', default=NoDefault, read_only=False, range=(None, None), sortable=True, searchable=True, description=''), searchable=False, description='')