+
−#!/usr/bin/env python
+
−#
+
−# Copyright 2007 Google Inc.
+
−#
+
−# 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
+
−#
+
−#     http://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.
+
−#
+
−
+
−"""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.
+
−"""
+
−
+
−
+
−
+
−
+
−
+
−import re
+
−
+
−import google
+
−import yaml
+
−
+
−
+
−class Error(Exception):
+
−  """Base class for all package errors."""
+
−
+
−
+
−class AttributeDefinitionError(Error):
+
−  """An error occurred in the definition of class attributes."""
+
−
+
−
+
−class ValidationError(Error):
+
−  """Base class for raising exceptions during validation."""
+
−
+
−  def __init__(self, message, cause=None):
+
−    """Initialize exception."""
+
−    if hasattr(cause, 'args') and cause.args:
+
−      Error.__init__(self, message, *cause.args)
+
−    else:
+
−      Error.__init__(self, message)
+
−    self.message = message
+
−    self.cause = cause
+
−
+
−  def __str__(self):
+
−    return str(self.message)
+
−
+
−
+
−class MissingAttribute(ValidationError):
+
−  """Raised when a required attribute is missing from object."""
+
−
+
−
+
−def AsValidator(validator):
+
−  """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!
+
−
+
−  Args:
+
−    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.
+
−  """
+
−  if isinstance(validator, (str, unicode)):
+
−    return Regex(validator, type(validator))
+
−  if isinstance(validator, type):
+
−    return Type(validator)
+
−  if isinstance(validator, (list, tuple, set)):
+
−    return Options(*tuple(validator))
+
−  if isinstance(validator, Validator):
+
−    return validator
+
−  else:
+
−    raise AttributeDefinitionError('%s is not a valid validator' %
+
−                                   str(validator))
+
−
+
−
+
−class Validated(object):
+
−  """Base class for other 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
+
−
+
−  def __init__(self, **attributes):
+
−    """Constructor for Validated classes.
+
−
+
−    This constructor can optionally assign values to the class via its
+
−    keyword arguments.
+
−
+
−    Raises:
+
−      AttributeDefinitionError when class instance is missing ATTRIBUTE
+
−      definition or when ATTRIBUTE is of the wrong type.
+
−    """
+
−    if not isinstance(self.ATTRIBUTES, dict):
+
−      raise AttributeDefinitionError(
+
−          'The class %s does not define an ATTRIBUTE variable.'
+
−          % self.__class__)
+
−
+
−    for key in self.ATTRIBUTES.keys():
+
−      object.__setattr__(self, key, self.GetAttribute(key).default)
+
−
+
−    self.Set(**attributes)
+
−
+
−  @classmethod
+
−  def GetAttribute(self, key):
+
−    """Safely get the underlying attribute definition as a Validator.
+
−
+
−    Args:
+
−      key: Name of attribute to get.
+
−
+
−    Returns:
+
−      Validator associated with key or attribute value wrapped in a
+
−      validator.
+
−    """
+
−    return AsValidator(self.ATTRIBUTES[key])
+
−
+
−  def Set(self, **attributes):
+
−    """Set multiple values on Validated instance.
+
−
+
−    This method can only be used to assign validated methods.
+
−
+
−    Args:
+
−      attributes: Attributes to set on object.
+
−
+
−    Raises:
+
−      ValidationError when no validated attribute exists on class.
+
−    """
+
−    for key, value in attributes.iteritems():
+
−      if key not in self.ATTRIBUTES:
+
−        raise ValidationError('Class \'%s\' does not have attribute \'%s\''
+
−                               % (self.__class__, key))
+
−      setattr(self, key, value)
+
−
+
−  def CheckInitialized(self):
+
−    """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.
+
−    """
+
−    for key in self.ATTRIBUTES.iterkeys():
+
−      try:
+
−        self.GetAttribute(key)(getattr(self, key))
+
−      except MissingAttribute, e:
+
−        e.message = "Missing required value '%s'." % key
+
−        raise e
+
−
+
−
+
−  def __setattr__(self, key, value):
+
−    """Set attribute.
+
−
+
−    Setting a value on an object of this type will only work for attributes
+
−    defined in ATTRIBUTES.  To make other assignments possible it is necessary
+
−    to override this method in subclasses.
+
−
+
−    It is important that assignment is restricted in this way because
+
−    this validation is used as validation for parsing.  Absent this restriction
+
−    it would be possible for method names to be overwritten.
+
−
+
−    Args:
+
−      key: Name of attribute to set.
+
−      value: Attributes new value.
+
−
+
−    Raises:
+
−      ValidationError when trying to assign to a value that does not exist.
+
−    """
+
−
+
−    if key in self.ATTRIBUTES:
+
−      value = self.GetAttribute(key)(value)
+
−      object.__setattr__(self, key, value)
+
−    else:
+
−      raise ValidationError('Class \'%s\' does not have attribute \'%s\''
+
−                            % (self.__class__, key))
+
−
+
−  def __str__(self):
+
−    """Formatted view of validated object and nested values."""
+
−    return repr(self)
+
−
+
−  def __repr__(self):
+
−    """Formatted view of validated object and nested values."""
+
−    values = [(attr, getattr(self, attr)) for attr in self.ATTRIBUTES]
+
−    dent = '    '
+
−    value_list = []
+
−    for attr, value in values:
+
−      value_list.append('\n%s%s=%s' % (dent, attr, value))
+
−
+
−    return "<%s %s\n%s>" % (self.__class__.__name__, ' '.join(value_list), dent)
+
−
+
−  def __eq__(self, other):
+
−    """Equality operator.
+
−
+
−    Comparison is done by comparing all attribute values to those in the other
+
−    instance.  Objects which are not of the same type are not equal.
+
−
+
−    Args:
+
−      other: Other object to compare against.
+
−
+
−    Returns:
+
−      True if validated objects are equal, else False.
+
−    """
+
−    if type(self) != type(other):
+
−      return False
+
−    for key in self.ATTRIBUTES.iterkeys():
+
−      if getattr(self, key) != getattr(other, key):
+
−        return False
+
−    return True
+
−
+
−  def __ne__(self, other):
+
−    """Inequality operator."""
+
−    return not self.__eq__(other)
+
−
+
−  def __hash__(self):
+
−    """Hash function for using Validated objects in sets and maps.
+
−
+
−    Hash is done by hashing all keys and values and xor'ing them together.
+
−
+
−    Returns:
+
−      Hash of validated object.
+
−    """
+
−    result = 0
+
−    for key in self.ATTRIBUTES.iterkeys():
+
−      value = getattr(self, key)
+
−      if isinstance(value, list):
+
−        value = tuple(value)
+
−      result = result ^ hash(key) ^ hash(value)
+
−    return result
+
−
+
−  @staticmethod
+
−  def _ToValue(validator, value):
+
−    """Convert any value to simplified collections and basic types.
+
−
+
−    Args:
+
−      validator: An instance of Validator that corresponds with 'value'.
+
−        May also be 'str' or 'int' if those were used instead of a full
+
−        Validator.
+
−      value: Value to convert to simplified collections.
+
−
+
−    Returns:
+
−      The value as a dictionary if it is a Validated object.
+
−      A list of items converted to simplified collections if value is a list
+
−        or a tuple.
+
−      Otherwise, just the value.
+
−    """
+
−    if isinstance(value, Validated):
+
−      return value.ToDict()
+
−    elif isinstance(value, (list, tuple)):
+
−      return [Validated._ToValue(validator, item) for item in value]
+
−    else:
+
−      if isinstance(validator, Validator):
+
−        return validator.ToValue(value)
+
−      return value
+
−
+
−  def ToDict(self):
+
−    """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.
+
−    """
+
−    result = {}
+
−    for name, validator in self.ATTRIBUTES.iteritems():
+
−      value = getattr(self, name)
+
−      if not(isinstance(validator, Validator) and value == validator.default):
+
−        result[name] = Validated._ToValue(validator, value)
+
−    return result
+
−
+
−  def ToYAML(self):
+
−    """Print validated object as simplified YAML.
+
−
+
−    Returns:
+
−      Object as a simplified YAML string compatible with parsing using the
+
−      SafeLoader.
+
−    """
+
−    return yaml.dump(self.ToDict(),
+
−                     default_flow_style=False,
+
−                     Dumper=yaml.SafeDumper)
+
−
+
−
+
−
+
−class Validator(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.
+
−  """
+
−
+
−  expected_type = object
+
−
+
−  def __init__(self, default=None):
+
−    """Constructor.
+
−
+
−    Args:
+
−      default: Default assignment is made during initialization and will
+
−        not pass through validation.
+
−    """
+
−    self.default = default
+
−
+
−  def __call__(self, value):
+
−    """Main interface to validator is call mechanism."""
+
−    return self.Validate(value)
+
−
+
−  def Validate(self, value):
+
−    """Override this method to customize sub-class behavior.
+
−
+
−    Args:
+
−      value: Value to validate.
+
−
+
−    Returns:
+
−      Value if value is valid, or a valid representation of value.
+
−    """
+
−    return value
+
−
+
−  def ToValue(self, value):
+
−    """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).
+
−
+
−    Args:
+
−      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.
+
−    """
+
−    return value
+
−
+
−
+
−class Type(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,
+
−                    }
+
−  """
+
−
+
−  def __init__(self, expected_type, convert=True, default=None):
+
−    """Initialize Type validator.
+
−
+
−    Args:
+
−      expected_type: Type that attribute should validate against.
+
−      convert: Cause conversion if value is not the right type.
+
−        Conversion is done by calling the constructor of the type
+
−        with the value as its first parameter.
+
−    """
+
−    super(Type, self).__init__(default)
+
−    self.expected_type = expected_type
+
−    self.convert = convert
+
−
+
−  def Validate(self, value):
+
−    """Validate that value is correct type.
+
−
+
−    Args:
+
−      value: Value to validate.
+
−
+
−    Returns:
+
−      None if value is None, value if value is of correct type, converted
+
−      value if the validator is configured to convert.
+
−
+
−    Raises:
+
−      ValidationError if value is not of the right type and validator
+
−      is not configured to convert.
+
−    """
+
−    if not isinstance(value, self.expected_type):
+
−      if value is not None and self.convert:
+
−        try:
+
−          return self.expected_type(value)
+
−        except ValueError, e:
+
−          raise ValidationError('Type conversion failed for value \'%s\'.'
+
−                                % value,
+
−                                e)
+
−        except TypeError, e:
+
−          raise ValidationError('Expected value of type %s, but got \'%s\'.'
+
−                                % (self.expected_type, value))
+
−      else:
+
−        raise MissingAttribute('Missing value is required.')
+
−    else:
+
−      return value
+
−
+
−
+
−TYPE_BOOL = Type(bool)
+
−TYPE_INT = Type(int)
+
−TYPE_LONG = Type(long)
+
−TYPE_STR = Type(str)
+
−TYPE_UNICODE = Type(unicode)
+
−TYPE_FLOAT = Type(float)
+
−
+
−
+
−class Options(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
+
−                        )
+
−  """
+
−
+
−  def __init__(self, *options, **kw):
+
−    """Initialize options.
+
−
+
−    Args:
+
−      options: List of allowed values.
+
−    """
+
−    if 'default' in kw:
+
−      default = kw['default']
+
−    else:
+
−      default = None
+
−
+
−    alias_map = {}
+
−    def AddAlias(alias, original):
+
−      """Set new alias on alias_map.
+
−
+
−      Raises:
+
−        AttributeDefinitionError when option already exists or if alias is
+
−        not of type str..
+
−      """
+
−      if not isinstance(alias, str):
+
−        raise AttributeDefinitionError(
+
−            'All option values must be of type str.')
+
−      elif alias in alias_map:
+
−        raise AttributeDefinitionError(
+
−            "Option '%s' already defined for options property." % alias)
+
−      alias_map[alias] = original
+
−
+
−    for option in options:
+
−      if isinstance(option, str):
+
−        AddAlias(option, option)
+
−
+
−      elif isinstance(option, (list, tuple)):
+
−        if len(option) != 2:
+
−          raise AttributeDefinitionError("Alias is defined as a list of tuple "
+
−                                         "with two items.  The first is the "
+
−                                         "original option, while the second "
+
−                                         "is a list or tuple of str aliases.\n"
+
−                                         "\n  Example:\n"
+
−                                         "      ('original', ('alias1', "
+
−                                         "'alias2'")
+
−        original, aliases = option
+
−        AddAlias(original, original)
+
−        if not isinstance(aliases, (list, tuple)):
+
−          raise AttributeDefinitionError('Alias lists must be a list or tuple')
+
−
+
−        for alias in aliases:
+
−          AddAlias(alias, original)
+
−
+
−      else:
+
−        raise AttributeDefinitionError("All options must be of type str "
+
−                                       "or of the form (str, [str...]).")
+
−    super(Options, self).__init__(default)
+
−    self.options = alias_map
+
−
+
−  def Validate(self, value):
+
−    """Validate options.
+
−
+
−    Returns:
+
−      Original value for provided alias.
+
−
+
−    Raises:
+
−      ValidationError when value is not one of predefined values.
+
−    """
+
−    if value is None:
+
−      raise ValidationError('Value for options field must not be None.')
+
−    value = str(value)
+
−    if value not in self.options:
+
−      raise ValidationError('Value \'%s\' not in %s.'
+
−                            % (value, self.options))
+
−    return self.options[value]
+
−
+
−
+
−class Optional(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.
+
−  """
+
−
+
−  def __init__(self, validator, default=None):
+
−    """Initializer.
+
−
+
−    This constructor will make a few guesses about the value passed in
+
−    as the validator:
+
−
+
−      - If the validator argument is a type, it automatically creates a Type
+
−        validator around it.
+
−
+
−      - If the validator argument is a list or tuple, it automatically
+
−        creates an Options validator around it.
+
−
+
−    Args:
+
−      validator: Optional validation condition.
+
−
+
−    Raises:
+
−      AttributeDefinitionError if validator is not callable.
+
−    """
+
−    self.validator = AsValidator(validator)
+
−    self.expected_type = self.validator.expected_type
+
−    self.default = default
+
−
+
−  def Validate(self, value):
+
−    """Optionally require a value.
+
−
+
−    Normal validators do not accept None.  This will accept none on
+
−    behalf of the contained validator.
+
−
+
−    Args:
+
−      value: Value to be validated as optional.
+
−
+
−    Returns:
+
−      None if value is None, else results of contained validation.
+
−    """
+
−    if value is None:
+
−      return None
+
−    return self.validator(value)
+
−
+
−
+
−class Regex(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)
+
−  """
+
−
+
−  def __init__(self, regex, string_type=unicode, default=None):
+
−    """Initialized regex validator.
+
−
+
−    Args:
+
−      regex: Regular expression string to use for comparison.
+
−
+
−    Raises:
+
−      AttributeDefinitionError if string_type is not a kind of string.
+
−    """
+
−    super(Regex, self).__init__(default)
+
−    if (not issubclass(string_type, basestring) or
+
−        string_type is basestring):
+
−      raise AttributeDefinitionError(
+
−          'Regex fields must be a string type not %s.' % str(string_type))
+
−    if isinstance(regex, basestring):
+
−      self.re = re.compile('^%s$' % regex)
+
−    else:
+
−      raise AttributeDefinitionError(
+
−          'Regular expression must be string.  Found %s.' % str(regex))
+
−
+
−    self.expected_type = string_type
+
−
+
−  def Validate(self, value):
+
−    """Does validation of a string against a regular expression.
+
−
+
−    Args:
+
−      value: String to match against regular expression.
+
−
+
−    Raises:
+
−      ValidationError when value does not match regular expression or
+
−      when value does not match provided string type.
+
−    """
+
−    if issubclass(self.expected_type, str):
+
−      cast_value = TYPE_STR(value)
+
−    else:
+
−      cast_value = TYPE_UNICODE(value)
+
−
+
−    if self.re.match(cast_value) is None:
+
−      raise ValidationError('Value \'%s\' does not match expression \'%s\''
+
−                            % (value, self.re.pattern))
+
−    return cast_value
+
−
+
−
+
−class _RegexStrValue(object):
+
−  """Simulates the regex object to support recomplation when necessary.
+
−
+
−  Used by the RegexStr class to dynamically build and recompile regular
+
−  expression attributes of a validated object.  This object replaces the normal
+
−  object returned from re.compile which is immutable.
+
−
+
−  When the value of this object is a string, that string is simply used as the
+
−  regular expression when recompilation is needed.  If the state of this object
+
−  is a list of strings, the strings are joined in to a single 'or' expression.
+
−  """
+
−
+
−  def __init__(self, attribute, value):
+
−    """Initialize recompilable regex value.
+
−
+
−    Args:
+
−      attribute: Attribute validator associated with this regex value.
+
−      value: Initial underlying python value for regex string.  Either a single
+
−        regex string or a list of regex strings.
+
−    """
+
−    self.__attribute = attribute
+
−    self.__value = value
+
−    self.__regex = None
+
−
+
−  def __AsString(self, value):
+
−    """Convert a value to appropriate string.
+
−
+
−    Returns:
+
−      String version of value with all carriage returns and line feeds removed.
+
−    """
+
−    if issubclass(self.__attribute.expected_type, str):
+
−      cast_value = TYPE_STR(value)
+
−    else:
+
−      cast_value = TYPE_UNICODE(value)
+
−
+
−    cast_value = cast_value.replace('\n', '')
+
−    cast_value = cast_value.replace('\r', '')
+
−    return cast_value
+
−
+
−  def __BuildRegex(self):
+
−    """Build regex string from state.
+
−
+
−    Returns:
+
−      String version of regular expression.  Sequence objects are constructed
+
−      as larger regular expression where each regex in the list is joined with
+
−      all the others as single 'or' expression.
+
−    """
+
−    if isinstance(self.__value, list):
+
−      value_list = self.__value
+
−      sequence = True
+
−    else:
+
−      value_list = [self.__value]
+
−      sequence = False
+
−
+
−    regex_list = []
+
−    for item in value_list:
+
−      regex_list.append(self.__AsString(item))
+
−
+
−    if sequence:
+
−      return '|'.join('(?:%s)' % item for item in regex_list)
+
−    else:
+
−      return regex_list[0]
+
−
+
−  def __Compile(self):
+
−    """Build regular expression object from state.
+
−
+
−    Returns:
+
−      Compiled regular expression based on internal value.
+
−    """
+
−    regex = self.__BuildRegex()
+
−    try:
+
−      return re.compile(regex)
+
−    except re.error, e:
+
−      raise ValidationError('Value \'%s\' does not compile: %s' % (regex, e), e)
+
−
+
−  @property
+
−  def regex(self):
+
−    """Compiled regular expression as described by underlying value."""
+
−    return self.__Compile()
+
−
+
−  def match(self, value):
+
−    """Match against internal regular expression.
+
−
+
−    Returns:
+
−      Regular expression object built from underlying value.
+
−    """
+
−    return re.match(self.__BuildRegex(), value)
+
−
+
−  def Validate(self):
+
−    """Ensure that regex string compiles."""
+
−    self.__Compile()
+
−
+
−  def __str__(self):
+
−    """Regular expression string as described by underlying value."""
+
−    return self.__BuildRegex()
+
−
+
−  def __eq__(self, other):
+
−    """Comparison against other regular expression string values."""
+
−    if isinstance(other, _RegexStrValue):
+
−      return self.__BuildRegex() == other.__BuildRegex()
+
−    return str(self) == other
+
−
+
−  def __ne__(self, other):
+
−    """Inequality operator for regular expression string value."""
+
−    return not self.__eq__(other)
+
−
+
−
+
−class RegexStr(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.
+
−  """
+
−
+
−  def __init__(self, string_type=unicode, default=None):
+
−    """Initialized regex validator.
+
−
+
−    Raises:
+
−      AttributeDefinitionError if string_type is not a kind of string.
+
−    """
+
−    if default is not None:
+
−      default = _RegexStrValue(self, default)
+
−      re.compile(str(default))
+
−    super(RegexStr, self).__init__(default)
+
−    if (not issubclass(string_type, basestring) or
+
−        string_type is basestring):
+
−      raise AttributeDefinitionError(
+
−          'RegexStr fields must be a string type not %s.' % str(string_type))
+
−
+
−    self.expected_type = string_type
+
−
+
−  def Validate(self, value):
+
−    """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.
+
−
+
−    Args:
+
−      value: String to compile as a regular expression.
+
−
+
−    Raises:
+
−      ValueError when value does not compile as a regular expression.  TypeError
+
−      when value does not match provided string type.
+
−    """
+
−    if isinstance(value, _RegexStrValue):
+
−      return value
+
−    value = _RegexStrValue(self, value)
+
−    value.Validate()
+
−    return value
+
−
+
−  def ToValue(self, value):
+
−    """Returns the RE pattern for this validator."""
+
−    return str(value)
+
−
+
−
+
−class Range(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).
+
−  """
+
−
+
−  def __init__(self, minimum, maximum, range_type=int, default=None):
+
−    """Initializer for range.
+
−
+
−    Args:
+
−      minimum: Minimum for attribute.
+
−      maximum: Maximum for attribute.
+
−      range_type: Type of field.  Defaults to int.
+
−    """
+
−    super(Range, self).__init__(default)
+
−    if not isinstance(minimum, range_type):
+
−      raise AttributeDefinitionError(
+
−          'Minimum value must be of type %s, instead it is %s (%s).' %
+
−          (str(range_type), str(type(minimum)), str(minimum)))
+
−    if not isinstance(maximum, range_type):
+
−      raise AttributeDefinitionError(
+
−          'Maximum value must be of type %s, instead it is %s (%s).' %
+
−          (str(range_type), str(type(maximum)), str(maximum)))
+
−
+
−    self.minimum = minimum
+
−    self.maximum = maximum
+
−    self.expected_type = range_type
+
−    self._type_validator = Type(range_type)
+
−
+
−  def Validate(self, value):
+
−    """Validate that value is within range.
+
−
+
−    Validates against range-type then checks the range.
+
−
+
−    Args:
+
−      value: Value to validate.
+
−
+
−    Raises:
+
−      ValidationError when value is out of range.  ValidationError when value
+
−      is notd of the same range type.
+
−    """
+
−    cast_value = self._type_validator.Validate(value)
+
−    if cast_value < self.minimum or cast_value > self.maximum:
+
−      raise ValidationError('Value \'%s\' is out of range %s - %s'
+
−                            % (str(value),
+
−                               str(self.minimum),
+
−                               str(self.maximum)))
+
−    return cast_value
+
−
+
−
+
−class Repeated(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.
+
−  """
+
−
+
−  def __init__(self, constructor, default=None):
+
−    """Initializer for repeated field.
+
−
+
−    Args:
+
−      constructor: Type used for verifying elements of sequence attribute.
+
−    """
+
−    super(Repeated, self).__init__(default)
+
−    self.constructor = constructor
+
−    self.expected_type = list
+
−
+
−  def Validate(self, value):
+
−    """Do validation of sequence.
+
−
+
−    Value must be a list and all elements must be of type 'constructor'.
+
−
+
−    Args:
+
−      value: Value to validate.
+
−
+
−    Raises:
+
−      ValidationError if value is None, not a list or one of its elements is the
+
−      wrong type.
+
−    """
+
−    if not isinstance(value, list):
+
−      raise ValidationError('Repeated fields must be sequence, '
+
−                            'but found \'%s\'.' % value)
+
−
+
−    for item in value:
+
−      if not isinstance(item, self.constructor):
+
−        raise ValidationError('Repeated items must be %s, but found \'%s\'.'
+
−                              % (str(self.constructor), str(item)))
+
−
+
−    return value