wuttaweb.forms.schema

Form schema types

class wuttaweb.forms.schema.EmailRecipients(encoding=None, allow_empty=False)[source]

Custom schema type for email setting recipient fields (To, Cc, Bcc).

Note that this inherits from colander.String and assumes the Python value is a “simple” string. Multiple recipients are represented as comma-delimited for instance; this is for use “as-is” with the raw config setting values.

The value is serialized as a “multiline” string with one recipient per line. The assumption being, the input widget would display as a <textarea> element.

widget_maker(**kwargs)[source]

Constructs a default widget for the field.

Returns:

Instance of EmailRecipientsWidget.

class wuttaweb.forms.schema.FileDownload(request, *args, **kwargs)[source]

Custom schema type for a file download field.

This field is only meant for readonly use, it does not handle file uploads.

It expects the incoming appstruct to be the path to a file on disk (or null).

Uses the FileDownloadWidget by default.

Parameters:
  • request – Current request object.

  • url – Optional URL for hyperlink. If not specified, file name/size is shown with no hyperlink.

class wuttaweb.forms.schema.ModelRef(model_class=None)[source]

Minimalist schema type for a model reference field.

This is the default type used for form fields which represent a mapped SQLAlchemy relationship property (e.g. User.person).

It is intentionally simplistic, meant to be usable “as-is” with no need for the request, app config etc. But you can subclass it to refine the logic for a particular model if needed.

This is in contrast to ObjectRef which does require the current request object to instantiate.

Nodes of this ModelRef type are created by default when applicable, for a form whose model has relationships. This is done instead of letting ColanderAlchemy do its magic, which would recursively crawl the relationship and may add many (sub)nodes.

Parameters:

model_class – Technically optional data model for the target side of relationship. See below for more info.

Note that the model_class is “technically” optional as a constructor param, but only because a subclass itself may define it. (The base class does not, however, which makes the param required when using the base class directly.)

model_class

Reference to the data model class which represents the “target” side of a relationship property. In the User.person example, this would be Person.

class wuttaweb.forms.schema.ObjectNode(*args, **kw)[source]

Custom schema node class which adds methods for compatibility with ColanderAlchemy. This is a direct subclass of colander.SchemaNode.

ColanderAlchemy will call certain methods on any node found in the schema. However these methods are not “standard” and only exist for ColanderAlchemy nodes.

So we must add nodes using this class, to ensure the node has all methods needed by ColanderAlchemy.

dictify(obj)[source]

This method is called by ColanderAlchemy when translating the in-app Python object to a value suitable for use in the form data dict.

The logic here will look for a dictify() method on the node’s “type” instance (self.typ; see also colander.SchemaNode) and invoke it if found.

For an example type which is supported in this way, see ObjectRef.

If the node’s type does not have a dictify() method, this will just convert the object to a string and return that.

objectify(value)[source]

This method is called by ColanderAlchemy when translating form data to the final Python representation.

The logic here will look for an objectify() method on the node’s “type” instance (self.typ; see also colander.SchemaNode) and invoke it if found.

For an example type which is supported in this way, see ObjectRef.

If the node’s type does not have an objectify() method, this will raise NotImplementeError.

class wuttaweb.forms.schema.ObjectRef(request, *args, **kwargs)[source]

Custom schema type for a model class reference field.

This expects the incoming appstruct to be either a model record instance, or None.

Serializes to the instance UUID as string, or colander.null; form data should be of the same nature.

This schema type is not useful directly, but various other types will subclass it. Each should define (at least) the model_class attribute or property.

Parameters:
  • request – Current request object.

  • empty_option –

    If a select widget is used, this determines whether an empty option is included for the dropdown. Set this to one of the following to add an empty option:

    • True to add the default empty option

    • label text for the empty option

    • tuple of (value, label) for the empty option

    Note that in the latter, value must be a string.

get_object_url(obj)[source]

Returns the “view” URL for the given object, if applicable.

This is used when rendering the field readonly. If this method returns a URL then the field text will be wrapped with a hyperlink, otherwise it will be shown as-is.

Default logic always returns None; subclass should override as needed.

get_query()[source]

Returns the main SQLAlchemy query responsible for locating the dropdown choices for the select widget.

This is called by widget_maker().

property model_class

Should be a reference to the model class to which this schema type applies (e.g. Person).

objectify(value)[source]

For the given UUID value, returns the object it represents (based on model_class).

If the value is empty, returns None.

If the value is not empty but object cannot be found, raises colander.Invalid.

serialize_object(obj)[source]

Serialize the given object to its primary key as string.

Default logic assumes the object has a UUID; subclass can override as needed.

Parameters:

obj – Object reference for the node.

Returns:

Object primary key as string.

sort_query(query)[source]

TODO

widget_maker(**kwargs)[source]

This method is responsible for producing the default widget for the schema node.

Deform calls this method automatically when constructing the default widget for a field.

Returns:

Instance of ObjectRefWidget.

class wuttaweb.forms.schema.Permissions(request, permissions, *args, **kwargs)[source]

Form schema type for the Role permissions association proxy field.

This is a subclass of WuttaSet. It uses a set of permission values for underlying data format.

Parameters:

permissions – Dict with all possible permissions. Should be in the same format as returned by get_available_permissions().

widget_maker(**kwargs)[source]

Constructs a default widget for the field.

Returns:

Instance of PermissionsWidget.

class wuttaweb.forms.schema.PersonRef(request, *args, **kwargs)[source]

Custom schema type for a Person reference field.

This is a subclass of ObjectRef.

class wuttaweb.forms.schema.RoleRef(request, *args, **kwargs)[source]

Custom schema type for a Role reference field.

This is a subclass of ObjectRef.

class wuttaweb.forms.schema.RoleRefs(request)[source]

Form schema type for the User roles association proxy field.

This is a subclass of WuttaSet. It uses a set of Role uuid values for underlying data format.

widget_maker(**kwargs)[source]

Constructs a default widget for the field.

Returns:

Instance of RoleRefsWidget.

class wuttaweb.forms.schema.UserRef(request, *args, **kwargs)[source]

Custom schema type for a User reference field.

This is a subclass of ObjectRef.

class wuttaweb.forms.schema.WuttaDateTime(default_tzinfo=datetime.timezone.utc, format=None)[source]

Custom schema type for datetime fields.

This should be used automatically for DateTime ORM columns unless you register another default.

This schema type exists for sake of convenience, when working with the Buefy datepicker + timepicker widgets.

It also follows the datetime handling “rules” as outlined in DateTime Behavior. On the Python side, values should be naive/UTC datetime objects. On the HTTP side, values will be ISO-format strings representing aware/local time.

class wuttaweb.forms.schema.WuttaDictEnum(request, enum_dct, *args, **kwargs)[source]

Schema type for “pseudo-enum” fields which reference a dict for known values instead of a true enum class.

This is primarily for use with “status” fields such as status_code.

This is a subclass of colander.String, but adds a default widget (SelectWidget) with enum choices.

Parameters:
  • request – Current request object.

  • enum_dct – Dict with possible enum values and labels.

class wuttaweb.forms.schema.WuttaEnum(request, *args, **kwargs)[source]

Custom schema type for enum fields.

This is a subclass of colander.Enum, but adds a default widget (SelectWidget) with enum choices.

Parameters:

request – Current request object.

class wuttaweb.forms.schema.WuttaList(request)[source]

Custom schema type for list fields; this is a subclass of colander.List.

Parameters:

request – Current request object.

As of now this merely provides a way (in fact, requires you) to pass the request in, so it can be leveraged as needed. Instances of this type will have the following attributes:

request

Reference to the current request.

config

Reference to the app config object.

app

Reference to the app handler instance.

class wuttaweb.forms.schema.WuttaMoney(request, *args, **kwargs)[source]

Custom schema type for “money” fields.

This is a subclass of colander:colander.Money, but uses the custom WuttaMoneyInputWidget by default.

Parameters:
  • request – Current request object.

  • scale – If this kwarg is specified, it will be passed along to the widget constructor.

class wuttaweb.forms.schema.WuttaQuantity(request, *args, **kwargs)[source]

Custom schema type for “quantity” fields.

This is a subclass of colander.Decimal, but uses the custom WuttaQuantityInputWidget by default.

Parameters:

request – Current request object.

class wuttaweb.forms.schema.WuttaSQLAlchemySchemaNode(*args, **kw)[source]

Custom schema node type based on ColanderAlchemy, but adding support for association proxy fields.

This class is used under the hood but you will not normally interact with it directly.

It’s a subclass of colanderalchemy.SQLAlchemySchemaNode.

class wuttaweb.forms.schema.WuttaSet(request)[source]

Custom schema type for set fields; this is a subclass of colander.Set.

Parameters:

request – Current request object.

As of now this merely provides a way (in fact, requires you) to pass the request in, so it can be leveraged as needed. Instances of this type will have the following attributes:

request

Reference to the current request.

config

Reference to the app config object.

app

Reference to the app handler instance.