lino.core.fields

Defines extended database field classes and utility functions related to fields.

(This module's source code is available here.)

Functions

ForeignKey(*args, **kwargs)

Instantiate a django.db.models.ForeignKey using pointer_factory().

OneToOneField(*args, **kwargs)

Instantiate a django.db.models.OneToOneField using pointer_factory().

constant()

Decorator to turn a function into a Constant.

displayfield(*args, **kw)

Decorator to turn a method into a VirtualField of type DisplayField.

fields_list(model, field_names)

Return a set with the names of the specified fields, checking whether each of them exists.

htmlbox(*args, **kwargs)

Decorator shortcut to turn a method into a a VirtualField of type HtmlBox.

make_remote_field(model, name)

pointer_factory(cls, othermodel, *args, **kw)

Instantiate a ForeignKey or OneToOneField with some subtle differences:

requestfield(*args, **kw)

Decorator shortcut to turn a method into a a VirtualField of type RequestField.

set_default_verbose_name(f)

If the verbose_name of a ForeignKey was not set by user code, Lino sets it to the verbose_name of the model pointed to.

unused_get_data_elem_from_model(cls, name)

Return the named data element from model if it exists.

use_as_wildcard(de)

validate_incomplete_date(value)

Raise ValidationError if user enters e.g.

virtualfield(return_type, **kwargs)

Decorator to turn a method into a VirtualField.

wildcard_data_elems(model)

Yield names to be used as wildcard in the column_names of a table or when fields_list() finds a *.

Classes

CharField(*args, **kw)

An extension around Django's models.CharField.

Constant(text_fn)

Deserves more documentation.

CustomField

Mixin to create a custom field.

DatePickerField([verbose_name, name, ...])

A DateField that uses a DatePicker instead of a normal DateWidget.

DisplayField([verbose_name])

A field to be rendered like a normal read-only form field, but with plain HTML instead of an <input> tag.

Dummy

DummyField(*args, **kw)

Represents a field that doesn't exist in the current configuration but might exist in other configurations.

DurationField(*args, **kw)

A field that stores Duration values as CHAR.

FakeField(**kwargs)

Base class for RemoteField and DisplayField.

HtmlBox([verbose_name])

Like DisplayField, but to be rendered as a panel rather than as a form field.

ImportedFields

Mixin for models which have "imported fields".

IncompleteDateField(*args, **kw)

A field that behaves like a DateField, but accepts incomplete dates represented using lino.utils.format_date.IncompleteDate.

MonthField(*args, **kw)

A DateField that uses a MonthPicker instead of a normal DateWidget

PasswordField(*args, **kwargs)

Stored as plain text in database, but not displayed in user interface.

PercentageField(*args, **kwargs)

A field to express a percentage.

PriceField([verbose_name, max_digits])

A thin wrapper around Django's DecimalField which adds default values for decimal_places, max_length and max_digits.

QuantityField(*args, **kw)

A field that accepts Quantity, Percentage and Duration values.

RecurrenceField(*args, **kw)

Deserves more documentation.

RemoteField(getter, name, fld[, setter])

A field on a related object.

RequestField(get, *args, **kw)

A VirtualField whose values are table action requests to be rendered as a clickable integer containing the number of rows.

RichTextField(*args, **kw)

TableRow

Base class for everything that can be used as a table row.

TimeField([verbose_name, name, auto_now, ...])

Like a TimeField, but allowed values are between calendar_start_hour and calendar_end_hour.

VirtualField(return_type, get, **kwargs)

Represents a virtual field.

lino.core.fields.validate_incomplete_date(value)

Raise ValidationError if user enters e.g. a date 30.02.2009.

lino.core.fields.set_default_verbose_name(f)

If the verbose_name of a ForeignKey was not set by user code, Lino sets it to the verbose_name of the model pointed to. This rule holds also for virtual FK fields.

For every FK field defined on a model (including virtual FK fields) this is called during kernel startup. Django sets the verbose_name of every field to field.name.replace('_', ' ').

For virtual FK fields defined on an actor or an action it is called a bit later. These fields don't have a name.

class lino.core.fields.PasswordField(*args, **kwargs)

Bases: django.db.models.fields.CharField

Stored as plain text in database, but not displayed in user interface.

class lino.core.fields.PercentageField(*args, **kwargs)

Bases: django.db.models.fields.DecimalField

A field to express a percentage. The database stores this like a DecimalField. Plain HTML adds a "%".

class lino.core.fields.TimeField(verbose_name=None, name=None, auto_now=False, auto_now_add=False, **kwargs)

Bases: django.db.models.fields.TimeField

Like a TimeField, but allowed values are between calendar_start_hour and calendar_end_hour.

class lino.core.fields.DatePickerField(verbose_name=None, name=None, auto_now=False, auto_now_add=False, **kwargs)

Bases: django.db.models.fields.DateField

A DateField that uses a DatePicker instead of a normal DateWidget. Doesn't yet work.

class lino.core.fields.MonthField(*args, **kw)

Bases: django.db.models.fields.DateField

A DateField that uses a MonthPicker instead of a normal DateWidget

class lino.core.fields.PriceField(verbose_name=None, max_digits=10, **kwargs)

Bases: django.db.models.fields.DecimalField

A thin wrapper around Django's DecimalField which adds default values for decimal_places, max_length and max_digits.

class lino.core.fields.FakeField(**kwargs)

Bases: object

Base class for RemoteField and DisplayField.

wildcard_data_elem = False

Whether to consider this field as wildcard data element.

sortable_by = None

A list of names of real fields to be used for sorting when this fake field is selected. For remote fields this is set automatically, on virtual fields you can set it yourself.

is_enabled(lh)

Overridden by mti.EnableChild

class lino.core.fields.RemoteField(getter, name, fld, setter=None, **kwargs)

Bases: lino.core.fields.FakeField

A field on a related object.

Remote fields are created by lino.core.model.Model.get_data_elem() when needed.

field

The bottom-level field object.

value_from_object(obj, ar=None)

Return the value of this field in the specified model instance obj. ar may be None, it's forwarded to the getter method who may decide to return values depending on it.

class lino.core.fields.DisplayField(verbose_name=None, **kwargs)

Bases: lino.core.fields.FakeField

A field to be rendered like a normal read-only form field, but with plain HTML instead of an <input> tag.

This is to be used as the return_type of a VirtualField.

The value to be represented is either some unicode text, a translatable text or a HTML element.

class lino.core.fields.HtmlBox(verbose_name=None, **kwargs)

Bases: lino.core.fields.DisplayField

Like DisplayField, but to be rendered as a panel rather than as a form field.

class lino.core.fields.VirtualField(return_type, get, **kwargs)

Bases: lino.core.fields.FakeField

Represents a virtual field. Values of virtual fields are not stored in the database, but computed on the fly each time they get read. Django doesn't see them.

A virtual field must have a return_type, which can be either a Django field type (CharField, TextField, IntegerField, BooleanField, ...) or one of Lino's custom fields DisplayField, HtmlBox or RequestField.

The get must be a callable which takes two arguments: obj the database object and ar an action request.

The model of a VirtualField is the class where the field was defined. This can be an abstract model. The VirtualField instance does not have a list of the concrete models which use it (because they inherit from that class).

lino_resolve_type()

Called on every virtual field when all models are loaded.

set_value_in_object(request, obj, value)

Stores the specified value in the specified model instance obj. request may be None.

Note that any implementation must also return obj, and callers must be ready to get another instance. This special behaviour is needed to implement lino.utils.mti.EnableChild.

value_from_object(obj, ar=None)

Return the value of this field in the specified model instance obj. ar may be None, it's forwarded to the getter method who may decide to return values depending on it.

select_format(compiler, sql, params)

Custom format for select clauses. For example, GIS columns need to be selected as AsText(table.col) on MySQL as the table.col data can't be used by Django.

lino.core.fields.virtualfield(return_type, **kwargs)

Decorator to turn a method into a VirtualField.

class lino.core.fields.Constant(text_fn)

Bases: object

Deserves more documentation.

lino.core.fields.constant()

Decorator to turn a function into a Constant. The function must accept one positional argument datasource.

class lino.core.fields.RequestField(get, *args, **kw)

Bases: lino.core.fields.VirtualField

A VirtualField whose values are table action requests to be rendered as a clickable integer containing the number of rows. Clicking on it will open a window with the table.

lino.core.fields.displayfield(*args, **kw)

Decorator to turn a method into a VirtualField of type DisplayField.

lino.core.fields.htmlbox(*args, **kwargs)

Decorator shortcut to turn a method into a a VirtualField of type HtmlBox.

lino.core.fields.requestfield(*args, **kw)

Decorator shortcut to turn a method into a a VirtualField of type RequestField.

class lino.core.fields.CharField(*args, **kw)

Bases: django.db.models.fields.CharField

An extension around Django's models.CharField.

Adds two keywords mask_re and strip_chars_re which, when using the ExtJS ui, will be rendered as the maskRe and stripCharsRe config options of TextField as described in the ExtJS documentation, converting naming conventions as follows:

regex

regex

A JavaScript RegExp object to be tested against the field value during validation (defaults to null). If the test fails, the field will be marked invalid using regexText.

mask_re

maskRe

An input mask regular expression that will be used to filter keystrokes that do not match (defaults to null). The maskRe will not operate on any paste events.

strip_chars_re

stripCharsRe

A JavaScript RegExp object used to strip unwanted content from the value before validation (defaults to null).

Example usage:

belgian_phone_no = dd.CharField(max_length=15,strip_chars_re='')

class lino.core.fields.QuantityField(*args, **kw)

Bases: lino.core.fields.CharField

A field that accepts Quantity, Percentage and Duration values.

Implemented as a CharField (sorting or filter ranges may not work as expected).

When you set blank=True, then you should also declare null=True.

to_python(value)

Excerpt from Django docs:

As a general rule, the method should deal gracefully with any of the following arguments:

  • An instance of the correct type (e.g., Hand in our ongoing example).

  • A string (e.g., from a deserializer).

  • Whatever the database returns for the column type you’re using.

I'd add "Any value potentially specified for this field when instantiating a model."

>>> to_python(None)
>>> to_python(30)
>>> to_python(30L)
>>> to_python('')
>>> to_python(Decimal(0))
class lino.core.fields.DurationField(*args, **kw)

Bases: lino.core.fields.QuantityField

A field that stores Duration values as CHAR.

Note that you cannot use SUM or AVG agregators on these fields since the database does not know how to calculate sums from them.

class lino.core.fields.IncompleteDateField(*args, **kw)

Bases: django.db.models.fields.CharField

A field that behaves like a DateField, but accepts incomplete dates represented using lino.utils.format_date.IncompleteDate.

class lino.core.fields.DummyField(*args, **kw)

Bases: lino.core.fields.FakeField

Represents a field that doesn't exist in the current configuration but might exist in other configurations. The "value" of a DummyField is always None.

See e.g. ForeignKey() and fields_list().

class lino.core.fields.RecurrenceField(*args, **kw)

Bases: django.db.models.fields.CharField

Deserves more documentation.

lino.core.fields.OneToOneField(*args, **kwargs)

Instantiate a django.db.models.OneToOneField using pointer_factory().

lino.core.fields.ForeignKey(*args, **kwargs)

Instantiate a django.db.models.ForeignKey using pointer_factory().

class lino.core.fields.CustomField

Bases: object

Mixin to create a custom field.

It defines a single method create_layout_elem().

create_layout_elem(base_class, layout_handle, field, **kw)

Return the widget to represent this field in the specified layout_handle.

The widget must be an instance of the given base_class.

self and field are identical unless self is a :class`RemoteField` or a VirtualField.

class lino.core.fields.ImportedFields

Bases: object

Mixin for models which have "imported fields".

class lino.core.fields.TableRow

Bases: object

Base class for everything that can be used as a table row.

classmethod get_default_table()

Used internally. Lino chooses during the kernel startup, for each model, one of the discovered Table subclasses as the "default table".

obj2href(ar, *args, **kwargs)

Return a html representation of a pointer to the given database object.

Examples see Pointing to a database object.

get_detail_action(ar)

Return the (bound) detail action to use for showing this object in a detail window. Return None when no detail form exists or the requesting user has no permission to see it.

ar is the action request who asks to see a detail. If the action requests's actor can be used for this model, then use its detail_action. Otherwise use the detail_action of this model's default table.

When ar is None, the permission check is bypassed.

If self has a special attribute _detail_action defined, return this. This magic is used by Menu.add_instance_action.

Usage example: courses.Course overrides this to return the detail_action depending on the CourseArea.

get_choices_text(request, actor, field)

Return the text to be displayed when an instance of this model is being used as a choice in a combobox of a ForeignKey field pointing to this model. request is the web request, actor is the requesting actor.

The default behaviour is to simply return str(self).

A usage example is lino_xl.lib.countries.Place.

lino.core.fields.wildcard_data_elems(model)

Yield names to be used as wildcard in the column_names of a table or when fields_list() finds a *.

lino.core.fields.fields_list(model, field_names)

Return a set with the names of the specified fields, checking whether each of them exists.

Arguments: model is any subclass of django.db.models.Model. It may be a string with the full name of a model (e.g. "myapp.MyModel"). field_names is a single string with a space-separated list of field names.

If one of the names refers to a dummy field, this name will be ignored silently.

For example if you have a model MyModel with two fields foo and bar, then dd.fields_list(MyModel,"foo bar") will return ['foo','bar'] and dd.fields_list(MyModel,"foo baz") will raise an exception.

TODO: either rename this to fields_set or change it to return an iterable on the fields.

lino.core.fields.pointer_factory(cls, othermodel, *args, **kw)

Instantiate a ForeignKey or OneToOneField with some subtle differences:

  • It supports othermodel being None or the name of some non-installed model and returns a DummyField in that case. This difference is useful when designing reusable models.

  • Explicitly sets the default value for on_delete to CASCADE (as required by Django 2).

lino.core.fields.unused_get_data_elem_from_model(cls, name)

Return the named data element from model if it exists. This can be a database field, a lino.core.fields.RemoteField, a lino.core.fields.VirtualField or a Django-style virtual field (GenericForeignKey).

Works for edge cases like ContentType (which is a pure Django model) or lino_xl.lib.cal.Day (which is not a Django model at all)