The Validator class implements the validator callable interface and adds conveniences for messaging, internationalization, and customization.
To use it, subclass Validator and implement validate().
from flatland.validation import Validator
class NoShouting(Validator):
"""Disallow ALL CAPS TEXT."""
has_shouting = "NO SHOUTING in %(label)s, please."
def validate(self, element, state):
if element.value.isupper():
self.note_error(element, state, 'has_shouting')
return False
return True
from flatland import String
schema = String.using(validators=[NoShouting()])
Above is a Validator version of the basic Customizing Validators example. In this version, the flatland.validation.Validator.note_error() method allows the messaging to be separated from the validation logic. note_error has some useful features, including templating and automatic I18N translation.
The base constructor of the Validator class has a twist that makes customizing existing Validators on the fly a breeze. The constructor can be passed keyword arguments matching any class attribute, and they will be overridden on the instance.
schema = String.using(validators=[NoShouting(has_shouting='shh.')])
Subclassing achieves the same effect.
class QuietPlease(NoShouting):
has_shouting = 'shh.'
schema = String.using(validators=[QuietPlease()])
The validators that ship with Flatland place all of their messaging and as much configurable behavior as possible in class attributes to support easy customization.
Messages prepared by Validator.note_error() and Validator.note_warning() may be templated using keywords in the sprintf-style Python string format syntax.
Possible keys are taken from multiple sources. In order of priority:
Flatland supports ngettext-style message pluralization. For this style, messages are specified as a 3-tuple of (singular message, plural message, n-key). n_key is any valid templating keyword, and its value n will be looked up using the same resolution rules. If the value n equals 1, the singular form will be used. Otherwise the plural.
from flatland.validation import Validator
class MinLength(Validator):
min_length = 2
too_short = (
"%(label)s must be at least one character long.",
"%(label)s must be at least %(min_length)s characters long.",
"min_length")
def validate(self, element, state):
if len(element.value) < self.min_length:
self.note_error(element, state, "too_short")
return False
return True
Conditional pluralization functions with or without I18N configured.
Messages can be translated using gettext-compatible functions. Translation works in conjunction with message templating features: the message itself is translated, and strings substituted into the message are also translated individually.
Translation uses ugettext and optionally ungettext functions that you provide. You may place these functions in the state, place them on the element or its schema, or place them in Python’s builtins.
An element’s ancestry will be searched for these functions. If you like, you may assign them solely to the top-most element or its schema and they will be used to translate all of its child elements.
If you opt to supply ugettext but not ungettext, Flatland’s built-in pluralization will kick in if a pluralized message is found. Flatland will choose the correct form internally, and the result will be fed through ugettext for translation.
Dynamic generated messages can also take advantage of the templating and internationalization features. There are two options for dynamic messages through Validator.note_error() and Validator.note_warning():
- Supply the message directly to note_error using message="..." instead of a message key.
- Messages looked up by key may also be callables. The callable will be invoked with element and state, and should return either a message string or a 3-tuple as described in pluralization.
Base class for fancy validators.
Construct a validator.
Parameters: | **kw – override any extant class attribute on this instance. |
---|
Validate an element returning True if valid.
Abstract.
Parameters: |
|
---|---|
Returns: | True if valid |
Record a validation error message on an element.
Parameters: |
|
---|---|
Returns: | False |
Either key or message is required. The message will have formatting expanded by expand_message() and be appended to element.errors.
Always returns False. This enables a convenient shorthand when writing validators:
from flatland.validation import Validator
class MyValidator(Validator):
my_message = 'Oh noes!'
def validate(self, element, state):
if not element.value:
return self.note_error(element, state, 'my_message')
else:
return True
Record a validation warning message on an element.
Parameters: |
|
---|---|
Returns: | False |
Either key or message is required. The message will have formatting expanded by expand_message() and be appended to element.warnings.
Always returns False.
Locate a message-transforming function, such as ugettext.
Returns None or a callable. The callable must return a message. The call signature of the callable is expected to match ugettext or ungettext:
Subclasses may override this method to provide advanced message transformation and translation functionality, on a per-element or per-message granularity if desired.
The default implementation uses the following logic to locate a transformer:
Apply formatting to a validation message.
Parameters: |
|
---|---|
Returns: | the formatted string |
See Message Templating, Message Pluralization and Message Internationalization for full information on how messages are expanded.