Welcome | Get started | Dive | Contribute | Topics | Reference | Changes | More

lino.core.fields

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

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().

choices_for_field(ar, holder, field)

Return the choices for the given field and the given HTTP request whose holder is either a Model, an Actor or an Action.

constant()

Decorator to turn a function into a Constant.

delayedhtmlbox(*args, **kwargs)

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)

none_getter(obj[, ar])

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.

return_none(obj, ar)

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.

use_as_wildcard(de)

validate_incomplete_date(value)

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

virtualfield(return_type, **kwargs)

Decorator to turn a model 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 of Django's models.CharField.

Constant(text_fn, **kwargs)

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.

DelayedHtmlBox(*args, **kwargs)

A simple extension of HtmlBox that uses the DelayedValue for its related store field value.

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[, db_collation])

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

PercentageField(*args, **kwargs)

A field to express a percentage.

PreviewTextField(*args, **kw)

PriceField([verbose_name, max_digits])

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

PriceRange(field_name[, verbose_name])

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.

VirtualBooleanField(ref_attr[, label])

An editable virtual boolean field.

VirtualField(return_type[, get])

Represents a virtual field.

VirtualModel(model)

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, db_collation=None, **kwargs)

Bases: CharField

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

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

Bases: 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: 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: DateField

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

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

Bases: 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: 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: 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 (leaf) 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: 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: DisplayField

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

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

Bases: HtmlBox

A simple extension of HtmlBox that uses the DelayedValue for its related store field value.

class lino.core.fields.VirtualField(return_type, get=<function return_none>, **kwargs)

Bases: 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(ar, obj, value)

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

Note that any implementation must 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.

class lino.core.fields.VirtualBooleanField(ref_attr, label=None, **kw)

Bases: VirtualField

An editable virtual boolean field.

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

Decorator to turn a model method into a VirtualField.

class lino.core.fields.Constant(text_fn, **kwargs)

Bases: FakeField

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: 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: CharField

An extension of Django’s models.CharField.

Adds two keywords mask_re and strip_chars_re which, when using the ExtJS front end, 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: CharField

A field that accepts Quantity, Percentage and Duration values.

Implemented as a CharField, which means that sorting or filter ranges may not work as expected, and you cannot use SUM or AVG agregators on quantity fields since the database does not know how to calculate sums from them.

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

to_python(value)

Excerpt from Django docs:

As a general rule, to_python() 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).

  • None (if the field allows null=True)

I’d add “Any value allowed for this field when instantiating a model.”

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

Bases: QuantityField

A field that stores Duration values as CHAR.

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

Bases: 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: 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: 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 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.

extra_display_modes = None

A set of extra display modes to make available on actors that use this model.

See Activating extra display modes.

hidden_columns = frozenset({})

If specified, this is the default value for hidden_columns of every Table on this model.

classmethod setup_parameters(params)

Inheritable hook for defining parameters for every actor on this model.

Called at site startup once for each actor using this model.

Toes not return anything. Receives a dict object params and is expected to update that dict, which will be used to fill the actor’s parameters.

See also get_simple_parameters().

classmethod get_simple_parameters()

Return or yield a list of names of simple parameter fields of every actor that uses this model.

When the list contains names for which no parameter field is defined, then Lino creates that parameter field as a copy of the database field of the same name.

This is also called by get_title_tags(), you don’t need to manually define title tags for simple parameters.

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”.

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 that asks to see the detail. If the action request’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 activity layout.

classmethod get_layout_aliases()

Yield a series of (ALIAS, repl) tuples that cause a name ALIAS in a layout based on this model to be replaced by its replacement repl.

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 is useful when designing reusable models.

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

lino.core.fields.choices_for_field(ar, holder, field)

Return the choices for the given field and the given HTTP request whose holder is either a Model, an Actor or an Action.