google.appengine.api.validation module

Summary

Validation tools for generic object structures.

This library is used for defining classes with constrained attributes. Attributes are defined on the class which contains them using validators. Although validators can be defined by any client of this library, a number of standard validators are provided here.

Validators can be any callable that takes a single parameter which checks the new value before it is assigned to the attribute. Validators are permitted to modify a received value so that it is appropriate for the attribute definition. For example, using int as a validator will cast a correctly formatted string to a number, or raise an exception if it can not. This is not recommended, however. the correct way to use a validator that ensure the correct type is to use the Type validator.

This validation library is mainly intended for use with the YAML object builder. See yaml_object.py.

Contents

google.appengine.api.validation.AsValidator(validator)source

Wrap various types as instances of a validator.

Used to allow shorthand for common validator types. It converts the following types to the following Validators.

strings -> Regex type -> Type collection -> Options Validator -> Its self!

Parameters

validator – Object to wrap in a validator.

Returns

Validator instance that wraps the given value.

Raises

AttributeDefinitionError – if validator is not one of the above described types.

exception google.appengine.api.validation.AttributeDefinitionErrorsource

Bases: google.appengine.api.validation.Error

An error occurred in the definition of class attributes.

class google.appengine.api.validation.Deprecated(preferred, validator, default=None)source

Bases: google.appengine.api.validation.Normalized

A deprecated field.

For use with Preferred. Only works as a field on Validated.

Both fields will work for value access. It’s an error to set both the deprecated and the corresponding preferred field.

Get(value, key, obj)source
GetWarnings(value, key, obj)source
ValidateEntirely(value, key, obj)source
exception google.appengine.api.validation.Errorsource

Bases: exceptions.Exception

Base class for all package errors.

class google.appengine.api.validation.Exec(default=None)source

Bases: google.appengine.api.validation.Type

Coerces the value to accommodate Docker CMD/ENTRYPOINT requirements.

Validates the value is a string, then tries to modify the string (if necessary) so that the command represented will become PID 1 inside the Docker container. See Docker documentation on “docker kill” for more info: https://docs.docker.com/engine/reference/commandline/kill/

If the command already starts with exec or appears to be in “exec form” (starts with [), no further action is needed. Otherwise, prepend the command with exec so that it will become PID 1 on execution.

Validate(value, key)source

Validate according to parent behavior and coerce to start with exec.

class google.appengine.api.validation.ItemDumper(stream, default_style=None, default_flow_style=None, canonical=None, indent=None, width=None, allow_unicode=None, line_break=None, encoding=None, explicit_start=None, explicit_end=None, version=None, tags=None, block_seq_indent=None, top_level_colon_align=None, prefix_colon=None)source

Bases: google.appengine._internal.ruamel.yaml.dumper.SafeDumper

For dumping validation.Items. Respects SortedDict key ordering.

represent_mapping(tag, mapping, flow_style=None)source
yaml_representers = {<type 'float'>: <unbound method SafeRepresenter.represent_float>, <class 'collections.OrderedDict'>: <unbound method SafeRepresenter.represent_ordereddict>, <type 'set'>: <unbound method SafeRepresenter.represent_set>, <type 'str'>: <unbound method SafeRepresenter.represent_str>, None: <unbound method SafeRepresenter.represent_undefined>, <type 'long'>: <unbound method SafeRepresenter.represent_long>, <class 'google.appengine._internal.ruamel.yaml.compat.ordereddict'>: <unbound method SafeRepresenter.represent_ordereddict>, <type 'datetime.date'>: <unbound method SafeRepresenter.represent_date>, <type 'bool'>: <unbound method SafeRepresenter.represent_bool>, <type 'tuple'>: <unbound method SafeRepresenter.represent_list>, <type 'NoneType'>: <unbound method SafeRepresenter.represent_none>, <type 'unicode'>: <unbound method SafeRepresenter.represent_unicode>, <type 'dict'>: <unbound method SafeRepresenter.represent_dict>, <type 'int'>: <unbound method SafeRepresenter.represent_int>, <type 'datetime.datetime'>: <unbound method SafeRepresenter.represent_datetime>, <class 'google.appengine.api.validation.SortedDict'>: <unbound method ItemDumper.represent_dict>, <type 'list'>: <unbound method SafeRepresenter.represent_list>}
exception google.appengine.api.validation.MissingAttribute(message, cause=None)source

Bases: google.appengine.api.validation.ValidationError

Raised when a required attribute is missing from object.

class google.appengine.api.validation.Normalized(default=None)source

Bases: google.appengine.api.validation.Validator

Normalizes a field on lookup, but serializes with the original value.

Only works with fields on Validated.

Get(value, key, obj)source

Returns the normalized value. Subclasses must override.

class google.appengine.api.validation.Optional(validator, default=None)source

Bases: google.appengine.api.validation.Validator

Definition of optional attributes.

Optional values are attributes which can be set to None or left unset. All values in a basic Validated class are set to None at initialization. Failure to assign to non-optional values will result in a validation error when calling CheckInitialized.

ToValue(value)source

Convert ‘value’ to a simplified collection or basic type.

Validate(value, key)source

Optionally require a value.

Normal validators do not accept None. This will accept none on behalf of the contained validator.

Parameters

  • value – Value to be validated as optional.

  • key – Name of the field being validated.

Returns

None if value is None, else results of contained validation.

class google.appengine.api.validation.Options(*options, **kw)source

Bases: google.appengine.api.validation.Validator

Limit field based on pre-determined values.

Options are used to make sure an enumerated set of values are the only one permitted for assignment. It is possible to define aliases which map multiple string values to a single original. An example of usage:

class ZooAnimal(validated.Class):
ATTRIBUTES = {

‘name’: str, ‘kind’: Options(‘platypus’, # No aliases

(‘rhinoceros’, [‘rhino’]), # One alias (‘canine’, (‘dog’, ‘puppy’)), # Two aliases )

Validate(value, key)source

Validate options.

Returns

Original value for provided alias.

Raises

ValidationError – when value is not one of predefined values.

class google.appengine.api.validation.Preferred(deprecated, validator, default=None)source

Bases: google.appengine.api.validation.Normalized

A non-deprecated field when there’s a deprecated one.

For use with Deprecated. Only works as a field on Validated.

Both fields will work for value access. It’s an error to set both the deprecated and the corresponding preferred field.

Get(value, key, obj)source
ValidateEntirely(value, key, obj)source
class google.appengine.api.validation.Range(minimum, maximum, range_type=int, default=None)source

Bases: google.appengine.api.validation.Validator

Validates that numbers fall within the correct range.

In theory this class can be emulated using Options, however error messages generated from that class will not be very intelligible. This class essentially does the same thing, but knows the intended integer range.

Also, this range class supports floats and other types that implement ordinality.

The range is inclusive, meaning 3 is considered in the range in Range(1,3).

Validate(value, key)source

Validate that value is within range.

Validates against range-type then checks the range.

Parameters

  • value – Value to validate.

  • key – Name of the field being validated.

Raises

  • ValidationError – when value is out of range. ValidationError when value

  • is not of the same range type.

class google.appengine.api.validation.Regex(regex, string_type=unicode, default=None)source

Bases: google.appengine.api.validation.Validator

Regular expression validator.

Regular expression validator always converts value to string. Note that matches must be exact. Partial matches will not validate. For example:

class ClassDescr(Validated):
ATTRIBUTES = { ‘name’: Regex(r’[a-zA-Z_][a-zA-Z_0-9]*’),

‘parent’: Type(type), }

Alternatively, any attribute that is defined as a string is automatically interpreted to be of type Regex. It is possible to specify unicode regex strings as well. This approach is slightly less efficient, but usually is not significant unless parsing large amounts of data:

class ClassDescr(Validated):
ATTRIBUTES = { ‘name’: r’[a-zA-Z_][a-zA-Z_0-9]*’,

‘parent’: Type(type), }

# This will raise a ValidationError exception. my_class(name=’AName with space’, parent=AnotherClass)

Validate(value, key)source

Does validation of a string against a regular expression.

Parameters

  • value – String to match against regular expression.

  • key – Name of the field being validated.

Raises

ValidationError – when value does not match regular expression or when value does not match provided string type.

class google.appengine.api.validation.RegexStr(string_type=unicode, default=None)source

Bases: google.appengine.api.validation.Validator

Validates that a string can compile as a regex without errors.

Use this validator when the value of a field should be a regex. That means that the value must be a string that can be compiled by re.compile(). The attribute will then be a compiled re object.

ToValue(value)source

Returns the RE pattern for this validator.

Validate(value, key)source

Validates that the string compiles as a regular expression.

Because the regular expression might have been expressed as a multiline string, this function also strips newlines out of value.

Parameters

  • value – String to compile as a regular expression.

  • key – Name of the field being validated.

Raises

  • ValueError when value does not compile as a regular expression. TypeError

  • when value does not match provided string type.

class google.appengine.api.validation.Repeated(constructor, default=None)source

Bases: google.appengine.api.validation.Validator

Repeated field validator.

Indicates that attribute is expected to be a repeated value, ie, a sequence. This adds additional validation over just Type(list) in that it retains information about what can be stored in the list by use of its constructor field.

Validate(value, key)source

Do validation of sequence.

Value must be a list and all elements must be of type ‘constructor’.

Parameters

  • value – Value to validate.

  • key – Name of the field being validated.

Raises

ValidationError – if value is None, not a list or one of its elements is the wrong type.

class google.appengine.api.validation.SortedDict(keys, data)source

Bases: dict

Represents a dict with a particular key order for yaml representing.

ordered_items()source
class google.appengine.api.validation.StringValidator(default=None)source

Bases: google.appengine.api.validation.Validator

Verifies property is a valid text string.

In python 2: inherits from basestring In python 3: inherits from str

Validate(value, key='???')source
class google.appengine.api.validation.TimeValuesource

Bases: google.appengine.api.validation.Validator

Validates time values with units, such as 1h or 3.5d.

Validate(value, key)source

Validate a time value.

Parameters

  • value – Value to validate.

  • key – Name of the field being validated.

Raises

ValidationError – if value is not a time value with the expected format.

class google.appengine.api.validation.Type(expected_type, convert=True, default=None)source

Bases: google.appengine.api.validation.Validator

Verifies property is of expected type.

Can optionally convert value if it is not of the expected type.

It is possible to specify a required field of a specific type in shorthand by merely providing the type. This method is slightly less efficient than providing an explicit type but is not significant unless parsing a large amount of information:

class Person(Validated):
ATTRIBUTES = {‘name’: unicode,

‘age’: int, }

However, in most instances it is best to use the type constants:

class Person(Validated):
ATTRIBUTES = {‘name’: TypeUnicode,

‘age’: TypeInt, }

GetWarnings(value, key, obj)source
Validate(value, key)source

Validate that value has the correct type.

Parameters

  • value – Value to validate.

  • key – Name of the field being validated.

Returns

value if value is of the correct type. value is coverted to the correct type if the Validator is configured to do so.

Raises

  • MissingAttribute – if value is None and the expected type is not NoneType.

  • ValidationError – if value is not of the right type and the validator is either configured not to convert or cannot convert.

class google.appengine.api.validation.Validated(**attributes)source

Bases: google.appengine.api.validation.ValidatedBase

Base class for classes that require validation.

A class which intends to use validated fields should sub-class itself from this class. Each class should define an ‘ATTRIBUTES’ class variable which should be a map from attribute name to its validator. For example:

class Story(Validated):
ATTRIBUTES = {‘title’: Type(str),

‘authors’: Repeated(Type(str)), ‘isbn’: Optional(Type(str)), ‘pages’: Type(int), }

Attributes that are not listed under ATTRIBUTES work like normal and are not validated upon assignment.

ATTRIBUTES = None
CheckInitialized()source

Checks that all required fields are initialized.

Since an instance of Validated starts off in an uninitialized state, it is sometimes necessary to check that it has been fully initialized. The main problem this solves is how to validate that an instance has all of its required fields set. By default, Validator classes do not allow None, but all attributes are initialized to None when instantiated.

Raises

  • Exception relevant to the kind of validation. The type of the exception

  • is determined by the validator. Typically this will be ValueError or

  • TypeError.

Get(key)source

Get a single value on Validated instance.

This method can only be used to retrieve validated attributes.

Parameters

key – The name of the attributes

Raises

ValidationError when no validated attribute exists on class.

GetUnnormalized(key)source

Get a single value on the Validated instance, without normalizing.

classmethod GetValidator(key)source

Safely get the underlying attribute definition as a Validator.

Parameters

key – Name of attribute to get.

Returns

Validator associated with key or attribute value wrapped in a validator.

Raises

ValidationError – if no such attribute exists.

GetWarnings()source
Set(key, value)source

Set a single value on Validated instance.

This method can only be used to assign validated attributes.

Parameters

  • key – The name of the attributes

  • value – The value to set

Raises

ValidationError when no validated attribute exists on class.

ToDict()source

Convert Validated object to a dictionary.

Recursively traverses all of its elements and converts everything to simplified collections.

Returns

A dict of all attributes defined in this classes ATTRIBUTES mapped to its value. This structure is recursive in that Validated objects that are referenced by this object and in lists are also converted to dicts.

class google.appengine.api.validation.ValidatedBasesource

Bases: object

Base class for all validated objects.

CheckInitialized()source

Checks that all required fields are initialized.

This function is called after all attributes have been checked to verify any higher level constraints, for example ensuring all required attributes are present.

Subclasses should override this function and raise an exception for any errors.

classmethod GetValidator(key)source

Safely get the Validator corresponding to the given key.

This function should be overridden by subclasses

Parameters

key – The attribute or item to get a validator for.

Returns

Validator associated with key or attribute.

Raises

ValidationError – if the requested key is illegal.

GetWarnings()source

Return all the warnings we’ve got, along with their associated fields.

Returns

A list of tuples of (dotted_field, warning), both strings.

Set(key, value)source

Set a single value on Validated instance.

This method should be overridded by sub-classes.

This method can only be used to assign validated attributes/items.

Parameters

  • key – The name of the attributes

  • value – The value to set

Raises

ValidationError – when no validated attribute exists on class.

SetMultiple(attributes)source

Set multiple values on Validated instance.

All attributes will be validated before being set.

Parameters

attributes – A dict of attributes/items to set.

Raises

ValidationError – when no validated attribute exists on class.

ToDict()source

Convert ValidatedBase object to a dictionary.

Recursively traverses all of its elements and converts everything to simplified collections.

Subclasses should override this method.

Returns

A dictionary mapping all attributes to simple values or collections.

ToYAML()source

Print validated object as simplified YAML.

Returns

Object as a simplified YAML string compatible with parsing using the SafeLoader.

class google.appengine.api.validation.ValidatedDict(**kwds)source

Bases: google.appengine.api.validation.ValidatedBase, dict

Base class for validated dictionaries.

You can control the keys and values that are allowed in the dictionary by setting KEY_VALIDATOR and VALUE_VALIDATOR to subclasses of Validator (or things that can be interpreted as validators, see AsValidator).

For example if you wanted only capitalized keys that map to integers you could do:

class CapitalizedIntegerDict(ValidatedDict):

KEY_VALIDATOR = Regex(‘[A-Z].*’) VALUE_VALIDATOR = int # this gets interpreted to Type(int)

The following code would result in an error:

my_dict = CapitalizedIntegerDict() my_dict[‘lowercase’] = 5 # Throws a validation exception

You can freely nest Validated and ValidatedDict inside each other so:

class MasterObject(Validated):

ATTRIBUTES = {‘paramdict’: CapitalizedIntegerDict}

Could be used to parse the following yaml:
paramdict:

ArbitraryKey: 323 AnotherArbitraryKey: 9931

classmethod GetValidator(key)source

Check the key for validity and return a corresponding value validator.

Parameters

key – The key that will correspond to the validator we are returning.

GetWarnings()source
KEY_VALIDATOR = None
Set(key, value)source

Set a single value on Validated instance.

This method checks that a given key and value are valid and if so puts the item into this dictionary.

Parameters

  • key – The name of the attributes

  • value – The value to set

Raises

ValidationError – when no validated attribute exists on class.

ToDict()source

Convert ValidatedBase object to a dictionary.

Recursively traverses all of its elements and converts everything to simplified collections.

Subclasses should override this method.

Returns

A dictionary mapping all attributes to simple values or collections.

VALUE_VALIDATOR = None
setdefault(key, value=None)source

Trap setdefaultss to ensure all key/value pairs are valid.

See the documentation for setdefault on dict for usage details.

Raises

  • ValidationError – if the specified key is illegal or the

  • value invalid.

update(other, **kwds)source

Trap updates to ensure all key/value pairs are valid.

See the documentation for update on dict for usage details.

Raises

ValidationError – if any of the specified keys are illegal or values invalid.

exception google.appengine.api.validation.ValidationError(message, cause=None)source

Bases: google.appengine.api.validation.Error

Base class for raising exceptions during validation.

class google.appengine.api.validation.Validator(default=None)source

Bases: object

Validator base class.

Though any callable can be used as a validator, this class encapsulates the case when a specific validator needs to hold a particular state or configuration.

To implement Validator sub-class, override the validate method.

This class is permitted to change the ultimate value that is set to the attribute if there is a reasonable way to perform the conversion.

GetWarnings(value, key, obj)source

Return any warnings on this attribute.

Validates the value with an eye towards things that aren’t fatal problems.

Parameters

  • value – Value to validate.

  • key – Name of the field being validated.

  • obj – The object to validate against.

Returns

A list of tuples (context, warning) where

  • context is the field (or dotted field path, if a sub-field)

  • warning is the string warning text

ToValue(value)source

Convert ‘value’ to a simplified collection or basic type.

Subclasses of Validator should override this method when the dumped representation of ‘value’ is not simply <type>(value) (e.g. a regex).

Parameters

value – An object of the same type that was returned from Validate().

Returns

An instance of a builtin type (e.g. int, str, dict, etc). By default it returns ‘value’ unmodified.

Validate(value, key='???')source

Validate this field. Override to customize subclass behavior.

Parameters

  • value – Value to validate.

  • key – Name of the field being validated.

Returns

Value if value is valid, or a valid representation of value.

ValidateEntirely(value, key, obj)source

Validate this field against others. Override to customize in subclasses.

By default, calls Validate(value, key). Since ValidateEntirely uses the entire object the relevant field is defined on, validators that use ValidateEntirely may only work on particular subclasses of ValidatedBase, like Validated or ValidatedDict.

Parameters

  • value – Value to validate.

  • key – Name of the field being validated.

  • obj – The object to validate against.

Returns

Value if value is valid, or a valid representation of value.

expected_type

alias of object