cardinal_pythonlib.colander_utils

---

Original code copyright (C) 2009-2022 Rudolf Cardinal (rudolf@pobox.com).

This file is part of cardinal_pythonlib.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

---

Functions for working with colander.

Colander: https://docs.pylonsproject.org/projects/colander/en/latest/

class cardinal_pythonlib.colander_utils.AllowNoneType(type_: SchemaType)

Serializes None to '', and deserializes '' to None; otherwise defers to the parent type.

A type which accepts serializing None to '' and deserializing '' to None. When the value is not equal to None/'', it will use (de)serialization of the given type. This can be used to make nodes optional.

Example:

date = colander.SchemaNode(
    colander.NoneType(colander.DateTime()),
    default=None,
    missing=None,
)

NOTE ALSO that Colander nodes explicitly never validate a missing value; see colander/__init__.py, in _SchemaNode.deserialize(). We want them to do so, essentially so we can pass in None to a form but have the form refuse to validate if it’s still None at submission.

deserialize(node: SchemaNode, value: str | _null) → Any

Deserializes string representation to Python object.

serialize(node: SchemaNode, value: Any) → str | _null

Serializes Python object to string representation.

class cardinal_pythonlib.colander_utils.BooleanNode(*args, **kw)

Colander node representing a boolean value with a checkbox widget.

schema_type

alias of Boolean

class cardinal_pythonlib.colander_utils.DateSelectorNode(*args, **kw)

Colander node containing a date.

missing = None

schema_type

alias of Date

class cardinal_pythonlib.colander_utils.DateTimeSelectorNode(*args, **kw)

Colander node containing a date/time.

missing = None

schema_type

alias of DateTime

class cardinal_pythonlib.colander_utils.EmailValidatorWithLengthConstraint(*args, min_length: int = 0, **kwargs)

The Colander Email validator doesn’t check length. This does.

class cardinal_pythonlib.colander_utils.HiddenIntegerNode(*args, **kw)

Colander node containing an integer, that is hidden to the user.

class cardinal_pythonlib.colander_utils.HiddenStringNode(*args, **kw)

Colander node containing an optional string, that is hidden to the user.

class cardinal_pythonlib.colander_utils.MandatoryEmailNode(*args, **kw)

Colander string node, requiring something that looks like a valid e-mail address.

class cardinal_pythonlib.colander_utils.MandatoryStringNode(*args, **kw)

Colander string node, where the string is obligatory.

CAVEAT: WHEN YOU PASS DATA INTO THE FORM, YOU MUST USE

appstruct = {
    somekey: somevalue or "",
    #                  ^^^^^
    #                  without this, None is converted to "None"
}

class cardinal_pythonlib.colander_utils.OptionalEmailNode(*args, **kw)

Colander string node, where the string can be blank but if not then it must look like a valid e-mail address.

class cardinal_pythonlib.colander_utils.OptionalIntNode(*args, **kw)

Colander node accepting integers but also blank values (i.e. it’s optional).

default = None

missing = None

cardinal_pythonlib.colander_utils.OptionalPendulumNode

alias of OptionalPendulumNodeLocalTZ

class cardinal_pythonlib.colander_utils.OptionalPendulumNodeLocalTZ(*args, **kw)

Colander node containing an optional Pendulum date/time, in which the date/time is assumed to be in the local timezone.

default = None

missing = None

class cardinal_pythonlib.colander_utils.OptionalPendulumNodeUTC(*args, **kw)

Colander node containing an optional Pendulum date/time, in which the date/time is assumed to be UTC.

default = None

missing = None

class cardinal_pythonlib.colander_utils.OptionalStringNode(*args, **kw)

Colander node accepting strings but allowing them to be blank (optional).

Coerces None to "" when serializing; otherwise it is coerced to "None", i.e. a string literal containing the word “None”, which is much more wrong.

class cardinal_pythonlib.colander_utils.PendulumType(use_local_tz: bool = True)

Colander SchemaType for Pendulum date/time objects.

deserialize(node: SchemaNode, cstruct: str | _null) → DateTime | None

Deserializes string representation to Python object.

serialize(node: SchemaNode, appstruct: None | datetime | date | DateTime | str | Arrow | _null) → str | _null

Serializes Python object to string representation.

class cardinal_pythonlib.colander_utils.ValidateDangerousOperationNode(*args, **kw)

Colander node that can be added to forms allowing dangerous operations (e.g. deletion of data). The node shows the user a code and requires the user to type that code in, before it will permit the form to proceed.

For this to work, the containing form must inherit from DynamicDescriptionsForm with dynamic_descriptions=True.

Usage is simple, like this:

class AddSpecialNoteSchema(CSRFSchema):
    table_name = HiddenStringNode()
    server_pk = HiddenIntegerNode()
    note = MandatoryStringNode(widget=TextAreaWidget(rows=20, cols=80))
    danger = ValidateDangerousOperationNode()

Parameters:

• length – code length required from the user

• allowed_chars – string containing the permitted characters (by default, digits)

cardinal_pythonlib.colander_utils.get_child_node(parent: _SchemaNode, child_name: str) → _SchemaNode

Returns a child node from an instantiated colander.SchemaNode object. Such nodes are not accessible via self.mychild but must be accessed via self.children, which is a list of child nodes.

Parameters:

• parent – the parent node object

• child_name – the name of the child node

Returns:

the child node

Raises:

StopIteration –

cardinal_pythonlib.colander_utils.get_values_and_permissible(values: Iterable[Tuple[Any, str]], add_none: bool = False, none_description: str = '[None]') → Tuple[List[Tuple[Any, str]], List[Any]]

Used when building Colander nodes.

Parameters:

• values – an iterable of tuples like (value, description) used in HTML forms

• add_none – add a tuple (None, none_description) at the start of values in the result?

• none_description – the description used for None if add_none is set

Returns:

a tuple (values, permissible_values), where

• values is what was passed in (perhaps with the addition of the “None” tuple at the start)

• permissible_values is a list of all the value elements of the original values