#!/usr/bin/env python
#
# Copyright 2014 Docalytics Inc, Copyright 2010 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.
#

"""Stand-alone implementation of in memory protocol messages.

Public Classes:
  Enum: Represents an enumerated type.
  Variant: Hint for wire format to determine how to serialize.
  Message: Base class for user defined messages.
  IntegerField: Field for integer values.
  FloatField: Field for float values.
  BooleanField: Field for boolean values.
  BytesField: Field for binary string values.
  StringField: Field for UTF-8 string values.
  MessageField: Field for other message type values.
  EnumField: Field for enumerated type values.

Public Exceptions (indentation indications class hierarchy):
  EnumDefinitionError: Raised when enumeration is incorrectly defined.
  FieldDefinitionError: Raised when field is incorrectly defined.
    InvalidVariantError: Raised when variant is not compatible with field type.
    InvalidDefaultError: Raised when default is not compatiable with field.
    InvalidNumberError: Raised when field number is out of range or reserved.
  MessageDefinitionError: Raised when message is incorrectly defined.
    DuplicateNumberError: Raised when field has duplicate number with another.
  ValidationError: Raised when a message or field is not valid.
  DefinitionNotFoundError: Raised when definition not found.
"""

__author__ = 'rafek@google.com (Rafe Kaplan)'

import inspect
import os
import sys
import traceback
import types
import weakref
import datetime

try:
    import iso8601
except ImportError:
    import _local_iso8601 as iso8601

from . import util

__all__ = ['MAX_ENUM_VALUE',

           'Enum',
           'Field',
           'FieldList',
           'Variant',
           'Message',
           'IntegerField',
           'FloatField',
           'BooleanField',
           'BytesField',
           'StringField',
           'MessageField',
           'EnumField',
           'DictField',
           'UntypedField',
           'DateTimeISO8601Field',
           'DateTimeMsIntegerField',
           'find_definition',

           'Error',
           'DecodeError',
           'EncodeError',
           'EnumDefinitionError',
           'FieldDefinitionError',
           'InvalidVariantError',
           'InvalidDefaultError',
           'InvalidNumberError',
           'MessageDefinitionError',
           'DuplicateNumberError',
           'ValidationError',
           'DefinitionNotFoundError',
]


# TODO(rafek): Add extended module test to ensure all exceptions
# in services extends Error.
Error = util.Error


class EnumDefinitionError(Error):
    """Enumeration definition error."""


class FieldDefinitionError(Error):
    """Field definition error."""


class InvalidVariantError(FieldDefinitionError):
    """Invalid variant provided to field."""


class InvalidDefaultError(FieldDefinitionError):
    """Invalid default provided to field."""


class InvalidNumberError(FieldDefinitionError):
    """Invalid number provided to field."""


class MessageDefinitionError(Error):
    """Message definition error."""


class DuplicateNumberError(Error):
    """Duplicate number assigned to field."""


class DefinitionNotFoundError(Error):
    """Raised when definition is not found."""


class DecodeError(Error):
    """Error found decoding message from encoded form."""


class EncodeError(Error):
    """Error found when encoding message."""


class ValidationError(Error):
    """Invalid value for message error."""

    def __str__(self):
        """Prints string with field name if present on exception."""
        message = Error.__str__(self)
        try:
            field_name = self.field_name
        except AttributeError:
            return message
        else:
            return message


# Attributes that are reserved by a class definition that
# may not be used by either Enum or Message class definitions.
_RESERVED_ATTRIBUTE_NAMES = frozenset(
    ['__module__', '__doc__'])

_POST_INIT_FIELD_ATTRIBUTE_NAMES = frozenset(
    ['name',
     'alias',
     '_message_definition',
     '_MessageField__type',
     '_EnumField__type',
     '_EnumField__resolved_default'])

_POST_INIT_ATTRIBUTE_NAMES = frozenset(
    ['_message_definition'])

# Maximum enumeration value as defined by the protocol buffers standard.
# All enum values must be less than or equal to this value.
MAX_ENUM_VALUE = (2 ** 29) - 1


class _DefinitionClass(type):
    """Base meta-class used for definition meta-classes.

    The Enum and Message definition classes share some basic functionality.
    Both of these classes may be contained by a Message definition.  After
    initialization, neither class may have attributes changed
    except for the protected _message_definition attribute, and that attribute
    may change only once.
    """

    __initialized = False

    def __init__(cls, name, bases, dct):
        """Constructor."""
        type.__init__(cls, name, bases, dct)
        # Base classes may never be initialized.
        if cls.__bases__ != (object,):
            cls.__initialized = True

    def message_definition(cls):
        """Get outer Message definition that contains this definition.

        Returns:
          Containing Message definition if definition is contained within one,
          else None.
        """
        try:
            return cls._message_definition()
        except AttributeError:
            return None

    def __setattr__(cls, name, value):
        """Overridden so that cannot set variables on definition classes after init.

        Setting attributes on a class must work during the period of initialization
        to set the enumation value class variables and build the name/number maps.
        Once __init__ has set the __initialized flag to True prohibits setting any
        more values on the class.  The class is in effect frozen.

        Args:
          name: Name of value to set.
          value: Value to set.
        """
        if cls.__initialized and name not in _POST_INIT_ATTRIBUTE_NAMES:
            raise AttributeError('May not change values: %s' % name)
        else:
            type.__setattr__(cls, name, value)

    def __delattr__(cls, name):
        """Overridden so that cannot delete varaibles on definition classes."""
        raise TypeError('May not delete attributes on definition class')

    def definition_name(cls):
        """Helper method for creating definition name.

        Names will be generated to include the classes package name, scope (if the
        class is nested in another definition) and class name.

        By default, the package name for a definition is derived from its module
        name.  However, this value can be overriden by placing a 'package' attribute
        in the module that contains the definition class.  For example:

          package = 'some.alternate.package'

          class MyMessage(Message):
            ...

          >>> MyMessage.definition_name()
          some.alternate.package.MyMessage

        Returns:
          Dot-separated fully qualified name of definition.
        """
        outer_definition_name = cls.outer_definition_name()
        if outer_definition_name is None:
            return unicode(cls.__name__)
        else:
            return u'%s.%s' % (outer_definition_name, cls.__name__)

    def outer_definition_name(cls):
        """Helper method for creating outer definition name.

        Returns:
          If definition is nested, will return the outer definitions name, else the
          package name.
        """
        outer_definition = cls.message_definition()
        if not outer_definition:
            return util.get_package_for_module(cls.__module__)
        else:
            return outer_definition.definition_name()

    def definition_package(cls):
        """Helper method for creating creating the package of a definition.

        Returns:
          Name of package that definition belongs to.
        """
        outer_definition = cls.message_definition()
        if not outer_definition:
            return util.get_package_for_module(cls.__module__)
        else:
            return outer_definition.definition_package()


class _EnumClass(_DefinitionClass):
    """Meta-class used for defining the Enum base class.

    Meta-class enables very specific behavior for any defined Enum
    class.  All attributes defined on an Enum sub-class must be integers.
    Each attribute defined on an Enum sub-class is translated
    into an instance of that sub-class, with the name of the attribute
    as its name, and the number provided as its value.  It also ensures
    that only one level of Enum class hierarchy is possible.  In other
    words it is not possible to delcare sub-classes of sub-classes of
    Enum.

    This class also defines some functions in order to restrict the
    behavior of the Enum class and its sub-classes.  It is not possible
    to change the behavior of the Enum class in later classes since
    any new classes may be defined with only integer values, and no methods.
    """

    def __init__(cls, name, bases, dct):
        # Can only define one level of sub-classes below Enum.
        if not (bases == (object,) or bases == (Enum,)):
            raise EnumDefinitionError('Enum type %s may only inherit from Enum' %
                                      (name,))

        cls.__by_number = {}
        cls.__by_name = {}

        # Enum base class does not need to be initialized or locked.
        if bases != (object,):
            # Replace integer with number.
            for attribute, value in dct.iteritems():

                # Module will be in every enum class.
                if attribute in _RESERVED_ATTRIBUTE_NAMES:
                    continue

                # Reject anything that is not an int.
                if not isinstance(value, (int, long)):
                    raise EnumDefinitionError(
                        'May only use integers in Enum definitions.  Found: %s = %s' %
                        (attribute, value))

                # Protocol buffer standard recommends non-negative values.
                # Reject negative values.
                if value < 0:
                    raise EnumDefinitionError(
                        'Must use non-negative enum values.  Found: %s = %d' %
                        (attribute, value))

                if value > MAX_ENUM_VALUE:
                    raise EnumDefinitionError(
                        'Must use enum values less than or equal %d.  Found: %s = %d' %
                        (MAX_ENUM_VALUE, attribute, value))

                if value in cls.__by_number:
                    raise EnumDefinitionError(
                        'Value for %s = %d is already defined: %s' %
                        (attribute, value, cls.__by_number[value].name))

                # Create enum instance and list in new Enum type.
                instance = object.__new__(cls)
                cls.__init__(instance, attribute, value)
                cls.__by_name[instance.name] = instance
                cls.__by_number[instance.number] = instance
                setattr(cls, attribute, instance)

        _DefinitionClass.__init__(cls, name, bases, dct)

    def __iter__(cls):
        """Iterate over all values of enum.

        Yields:
          Enumeration instances of the Enum class in arbitrary order.
        """
        return cls.__by_number.itervalues()

    def names(cls):
        """Get all names for Enum.

        Returns:
          An iterator for names of the enumeration in arbitrary order.
        """
        return cls.__by_name.iterkeys()

    def numbers(cls):
        """Get all numbers for Enum.

        Returns:
          An iterator for all numbers of the enumeration in arbitrary order.
        """
        return cls.__by_number.iterkeys()

    def lookup_by_name(cls, name):
        """Look up Enum by name.

        Args:
          name: Name of enum to find.

        Returns:
          Enum sub-class instance of that value.
        """
        return cls.__by_name[name]

    def lookup_by_number(cls, number):
        """Look up Enum by number.

        Args:
          number: Number of enum to find.

        Returns:
          Enum sub-class instance of that value.
        """
        return cls.__by_number[number]

    def __len__(cls):
        return len(cls.__by_name)


class Enum(object):
    """Base class for all enumerated types."""

    __metaclass__ = _EnumClass

    __slots__ = set(('name', 'number'))

    def __new__(cls, index):
        """Acts as look-up routine after class is initialized.

        The purpose of overriding __new__ is to provide a way to treat
        Enum subclasses as casting types, similar to how the int type
        functions.  A program can pass a string or an integer and this
        method with "convert" that value in to an appropriate Enum instance.

        Args:
          index: Name or number to look up.  During initialization
            this is always the name of the new enum value.

        Raises:
          TypeError: When an inappropriate index value is passed provided.
        """
        # If is enum type of this class, return it.
        if isinstance(index, cls):
            return index

        # If number, look up by number.
        if isinstance(index, (int, long)):
            try:
                return cls.lookup_by_number(index)
            except KeyError:
                pass

        # If name, look up by name.
        if isinstance(index, basestring):
            try:
                return cls.lookup_by_name(index)
            except KeyError:
                pass

        raise TypeError('No such value for %s in Enum %s' %
                        (index, cls.__name__))

    def __init__(self, name, number=None):
        """Initialize new Enum instance.

        Since this should only be called during class initialization any
        calls that happen after the class is frozen raises an exception.
        """
        # Immediately return if __init__ was called after _Enum.__init__().
        # It means that casting operator version of the class constructor
        # is being used.
        if getattr(type(self), '_DefinitionClass__initialized'):
            return
        object.__setattr__(self, 'name', name)
        object.__setattr__(self, 'number', number)

    def __setattr__(self, name, value):
        raise TypeError('May not change enum values')

    def __str__(self):
        return self.name

    def __int__(self):
        return self.number

    def __repr__(self):
        return '%s(%s, %d)' % (type(self).__name__, self.name, self.number)

    def __cmp__(self, other):
        """Order is by number."""
        if isinstance(other, type(self)):
            return cmp(self.number, other.number)
        return NotImplemented

    @classmethod
    def to_dict(cls):
        """Make dictionary version of enumerated class.

        Dictionary created this way can be used with def_num.

        Returns:
          A dict (name) -> number
        """
        return dict((item.name, item.number) for item in iter(cls))

    @staticmethod
    def def_enum(dct, name):
        """Define enum class from dictionary.

        Args:
          dct: Dictionary of enumerated values for type.
          name: Name of enum.
        """
        return type(name, (Enum,), dct)


# TODO(rafek): Determine to what degree this enumeration should be compatible
# with FieldDescriptor.Type in:
#
# http://code.google.com/p/protobuf/source/browse/trunk/src/google/protobuf/descriptor.proto
class Variant(Enum):
    """Wire format variant.

    Used by the 'protobuf' wire format to determine how to transmit
    a single piece of data.  May be used by other formats.

    See: http://code.google.com/apis/protocolbuffers/docs/encoding.html

    Values:
      DOUBLE: 64-bit floating point number.
      FLOAT: 32-bit floating point number.
      INT64: 64-bit signed integer.
      UINT64: 64-bit unsigned integer.
      INT32: 32-bit signed integer.
      BOOL: Boolean value (True or False).
      STRING: String of UTF-8 encoded text.
      MESSAGE: Embedded message as byte string.
      BYTES: String of 8-bit bytes.
      UINT32: 32-bit unsigned integer.
      ENUM: Enum value as integer.
      SINT32: 32-bit signed integer.  Uses "zig-zag" encoding.
      SINT64: 64-bit signed integer.  Uses "zig-zag" encoding.
    """
    DOUBLE = 1
    FLOAT = 2
    INT64 = 3
    UINT64 = 4
    INT32 = 5
    BOOL = 8
    STRING = 9
    MESSAGE = 11
    BYTES = 12
    UINT32 = 13
    ENUM = 14
    SINT32 = 17
    SINT64 = 18


class _MessageClass(_DefinitionClass):
    """Meta-class used for defining the Message base class.

    For more details about Message classes, see the Message class docstring.
    Information contained there may help understanding this class.

    Meta-class enables very specific behavior for any defined Message
    class.  All attributes defined on an Message sub-class must be field
    instances, Enum class definitions or other Message class definitions.  Each
    field attribute defined on an Message sub-class is added to the set of
    field definitions and the attribute is translated in to a slot.  It also
    ensures that only one level of Message class hierarchy is possible.  In other
    words it is not possible to declare sub-classes of sub-classes of
    Message.

    This class also defines some functions in order to restrict the
    behavior of the Message class and its sub-classes.  It is not possible
    to change the behavior of the Message class in later classes since
    any new classes may be defined with only field, Enums and Messages, and
    no methods.
    """

    def __new__(cls, name, bases, dct):
        """Create new Message class instance.

        The __new__ method of the _MessageClass type is overridden so as to
        allow the translation of Field instances to slots.
        """
        by_name = {}
        by_alias = {}

        variant_map = {}

        if bases != (object,):
            # Can only define one level of sub-classes below Message.
            if bases != (Message,):
                raise MessageDefinitionError(
                    'Message types may only inherit from Message')

            enums = []
            messages = []
            # Must not use iteritems because this loop will change the state of dct.
            for key, field in dct.items():

                if key in _RESERVED_ATTRIBUTE_NAMES:
                    continue

                if isinstance(field, type) and issubclass(field, Enum):
                    enums.append(key)
                    continue

                if (isinstance(field, type) and
                        issubclass(field, Message) and
                            field is not Message):
                    messages.append(key)
                    continue

                # Reject anything that is not a field.
                if type(field) is Field or not isinstance(field, Field):
                    raise MessageDefinitionError(
                        'May only use fields in message definitions.  Found: %s = %s' %
                        (key, field))

                # Set the name for the field as the variable name, unless it is explicitly named
                if not hasattr(field, 'name') or not field.name:
                    field.name = key

                if field.name in by_name:
                    raise DuplicateNumberError(
                        'Field with name %d declared more than once in %s' %
                        (field.name, name))

                # Record the name used in code
                field.alias = key

                # Place in name map
                by_name[field.name] = field
                by_alias[field.alias] = field

            # Add enums if any exist.
            if enums:
                dct['__enums__'] = sorted(enums)

            # Add messages if any exist.
            if messages:
                dct['__messages__'] = sorted(messages)

        dct['_Message__by_name'] = by_name
        dct['_Message__by_alias'] = by_alias

        return _DefinitionClass.__new__(cls, name, bases, dct)

    def __init__(cls, name, bases, dct):
        """Initializer required to assign references to new class."""
        if bases != (object,):
            for value in dct.itervalues():
                if isinstance(value, _DefinitionClass) and not value is Message:
                    value._message_definition = weakref.ref(cls)

            for field in cls.all_fields():
                field._message_definition = weakref.ref(cls)

        _DefinitionClass.__init__(cls, name, bases, dct)


class Message(object):
    """Base class for user defined message objects.

    Used to define messages for efficient transmission across network or
    process space.  Messages are defined using the field classes (IntegerField,
    FloatField, EnumField, etc.).

    Messages are more restricted than normal classes in that they may only
    contain field attributes and other Message and Enum definitions.  These
    restrictions are in place because the structure of the Message class is
    intentended to itself be transmitted across network or process space and
    used directly by clients or even other servers.  As such methods and
    non-field attributes could not be transmitted with the structural information
    causing discrepancies between different languages and implementations.

    Initialization and validation:

      A Message object is considered to be initialized if it has all required
      fields and any nested messages are also initialized.

      Calling 'check_initialized' will raise a ValidationException if it is not
      initialized; 'is_initialized' returns a boolean value indicating if it is
      valid.

      Validation automatically occurs when Message objects are created
      and populated.  Validation that a given value will be compatible with
      a field that it is assigned to can be done through the Field instances
      validate() method.  The validate method used on a message will check that
      all values of a message and its sub-messages are valid.  Assingning an
      invalid value to a field will raise a ValidationException.

    Example:

      # Trade type.
      class TradeType(Enum):
        BUY = 1
        SELL = 2
        SHORT = 3
        CALL = 4

      class Lot(Message):
        price = IntegerField(required=True)
        quantity = IntegerField(required=True)

      class Order(Message):
        symbol = StringField(required=True)
        total_quantity = IntegerField(required=True)
        trade_type = EnumField(TradeType, required=True)
        lots = MessageField(Lot, repeated=True)
        limit = IntegerField(5)

      order = Order(symbol='GOOG',
                    total_quantity=10,
                    trade_type=TradeType.BUY)

      lot1 = Lot(price=304,
                 quantity=7)

      lot2 = Lot(price = 305,
                 quantity=3)

      order.lots = [lot1, lot2]

      # Now object is initialized!
      order.check_initialized()
    """

    __metaclass__ = _MessageClass

    # Mapping of names (actual value that's used for encoding) to fields
    __by_name = {}

    # Mapping of aliases (the name that used in python code) to fields
    __by_alias = {}

    def __init__(self, **kwargs):
        """Initialize internal messages state.

        Args:
          A message can be initialized via the constructor by passing in keyword
          arguments corresponding to fields.  For example:

            class Date(Message):
              day = IntegerField(1)
              month = IntegerField(2)
              year = IntegerField(3)

          Invoking:

            date = Date(day=6, month=6, year=1911)

          is the same as doing:

            date = Date()
            date.day = 6
            date.month = 6
            date.year = 1911
        """
        # A name -> value mapping of field names to their values. Repeated values will be present in this map even if they have not been explicitly set
        self.__field_values = {}

        # A set of field names that have been explicitly set
        self.__set_fields = set()

        # Fields that have been set for which we do not recognize from our data definition
        self.__unrecognized_fields = {}

        assigned = set()
        for name, value in kwargs.iteritems():
            setattr(self, name, value)
            assigned.add(name)

        set_fields = set(self.__set_fields)

        # initialize repeated fields.
        for field in self.all_fields():
            if field.repeated and field.alias not in assigned:
                setattr(self, field.alias, [])

        # Don't let the initialization of repeated fields affect which fields are set
        self.__set_fields = set_fields

    def check_initialized(self):
        """Check class for initialization status.

        Check that all required fields are initialized

        Raises:
          ValidationError: If message is not initialized.
        """
        for name, field in self.__by_name.iteritems():
            value = getattr(self, field.alias)
            if value is None:
                if field.required:
                    raise ValidationError("Message %s is missing required field %s" %
                                          (type(self).__name__, field.alias))
            else:
                try:
                    if (isinstance(field, MessageField) and
                            issubclass(field.message_type, Message)):
                        if field.repeated:
                            for item in value:
                                item_message_value = field.value_to_message(item)
                                item_message_value.check_initialized()
                        else:
                            message_value = field.value_to_message(value)
                            message_value.check_initialized()
                except ValidationError, err:
                    if not hasattr(err, 'message_name'):
                        err.message_name = type(self).__name__
                    raise

    def is_initialized(self):
        """Get initialization status.

        Returns:
          True if message is valid, else False.
        """
        try:
            self.check_initialized()
        except ValidationError:
            return False
        else:
            return True

    @classmethod
    def all_fields(cls):
        """Get all field definition objects.

        Ordering is arbitrary.

        Returns:
          Iterator over all values in arbitrary order.
        """
        return cls.__by_name.itervalues()

    @classmethod
    def field_by_name(cls, name):
        """Get field by name.

        Returns:
          Field object associated with name.

        Raises:
          KeyError if no field found by that name.
        """
        return cls.__by_name[name]

    def get_field_value(self, name):
        """
        Gets the value of the field specified by name, or returns the default value if no value is set.

        :param name: the name of the field to get the value for

        :return: The value or the default
        """
        message_type = type(self)
        try:
            field = message_type.field_by_name(name)

            if name in self.__field_values:
                return self.__field_values[name]
            else:
                return field.default
        except KeyError:
            raise AttributeError('Message %s has no field %s' % (message_type.__name__, name))

    def get_assigned_value(self, name):
        """Get the assigned value of an attribute.

        Get the underlying value of an attribute.  If value has not been set, will
        not return the default for the field. Name can be either a recognized or unrecognized field.

        :param name: Name of attribute to get.

        :returns: Value of attribute, None if it has not been set.

        :raises: KeyError if the name is not set
        """
        if not name:
            raise ValueError("name must be specified")

        if name in self.__set_fields:
            if name in self.__field_values:
                return self.__field_values.get(name)
            elif name in self.__unrecognized_fields:
                return self.__unrecognized_fields.get(name)
        else:
            raise KeyError("No value is set for '%s" % name)

    def has_value_assigned(self, name):
        """
        Checks if specified name has a value assigned. Can either be a recognized or unrecognized field.

        :param name: the name of the field to check

        :return: True if set, False otherwise.
        """
        return name in self.__set_fields

    def unset(self, name):
        """
        Mark a field as not set.

        This will make has_value_assigned return False, and getting the value for a known field return the default value.

        :param name: Name of field to reset.
        """
        if name in self.__field_values:
            del self.__field_values[name]

        if name in self.__unrecognized_fields:
            del self.__unrecognized_fields[name]

        try:
            self.__set_fields.remove(name)
        except KeyError:
            pass

    def all_unrecognized_fields(self):
        """
        Get the names of all unrecognized fields in this message.
        """
        return self.__unrecognized_fields.keys()

    def strip_unrecognized_fields(self):
        """
        Unset all unrecognized fields in this message.
        """
        for name in self.all_unrecognized_fields():
            self.unset(name)

    def get_unrecognized_field_info(self, key, value_default=None, variant_default=None):
        """Get the value and variant of an unknown field in this message.

        Args:
          key: The name or number of the field to retrieve.
          value_default: Value to be returned if the key isn't found.
          variant_default: Value to be returned as variant if the key isn't
            found.

        Returns:
          (value, variant), where value and variant are whatever was passed
          to set_unrecognized_field.
        """
        value, variant = self.__unrecognized_fields.get(key, (value_default, variant_default))

        return value, variant

    def set_unrecognized_field(self, key, value, variant):
        """Set an unrecognized field, used when decoding a message.

        Args:
          key: The name or number used to refer to this unknown value.
          value: The value of the field.
          variant: Type information needed to interpret the value or re-encode it.

        Raises:
          TypeError: If the variant is not an instance of messages.Variant.
        """
        if not isinstance(variant, Variant):
            raise TypeError('Variant type %s is not valid.' % variant)
        self.__unrecognized_fields[key] = value, variant

    def __setattr__(self, alias, value):
        """Change set behavior for messages.

        Messages may only be assigned values that are fields.

        Does not try to validate field when set.

        Args:
          alias: Name of field to assign to.
          value: Value to assign to field.

        Raises:
          AttributeError when trying to assign value that is not a field.
        """
        if alias in self.__by_alias or alias.startswith('_Message__'):
            object.__setattr__(self, alias, value)
        else:
            raise AttributeError("May not assign arbitrary value '%s' "
                                 "to message '%s'" % (alias, type(self).__name__))

    def __repr__(self):
        """Make string representation of message.

        Example:

          class MyMessage(messages.Message):
            integer_value = messages.IntegerField(1)
            string_value = messages.StringField(2)

          my_message = MyMessage()
          my_message.integer_value = 42
          my_message.string_value = u'A string'

          print my_message
          >>> <MyMessage
          ...  integer_value: 42
          ...  string_value: u'A string'>

        Returns:
          String representation of message, including the values
          of all fields and repr of all sub-messages.
        """
        body = ['<', type(self).__name__]
        for field in sorted(self.all_fields(),
                            key=lambda f: f.name):
            attribute = field.name

            if self.has_value_assigned(field.name):
                body.append('\n %s: %s' % (attribute, repr(self.get_field_value(field.name))))

        body.append('>')
        return ''.join(body)

    def __eq__(self, other):
        """Equality operator.

        Does field by field comparison with other message.  For
        equality, must be same type and values of all fields must be
        equal.

        Messages not required to be initialized for comparison.

        Does not attempt to determine equality for values that have
        default values that are not set.  In other words:

          class HasDefault(Message):

            attr1 = StringField(1, default='default value')

          message1 = HasDefault()
          message2 = HasDefault()
          message2.attr1 = 'default value'

          message1 != message2

        Does not compare unknown values.

        Args:
          other: Other message to compare with.
        """
        # TODO(rafek): Implement "equivalent" which does comparisons
        # taking default values in to consideration.
        if self is other:
            return True

        if type(self) is not type(other):
            return False

        return self.__set_fields == other.__set_fields and self.__field_values == other.__field_values

    def __ne__(self, other):
        """Not equals operator.

        Does field by field comparison with other message.  For
        non-equality, must be different type or any value of a field must be
        non-equal to the same field in the other instance.

        Messages not required to be initialized for comparison.

        Args:
          other: Other message to compare with.
        """
        return not self.__eq__(other)


class FieldList(list):
    """List implementation that validates field values.

    This list implementation overrides all methods that add values in to a list
    in order to validate those new elements.  Attempting to add or set list
    values that are not of the correct type will raise ValidationError.
    """

    def __init__(self, message_instance, field_instance, sequence):
        """Constructor.

        Args:
          field_instance: Instance of field that validates the list.
          sequence: List or tuple to construct list from.
        """
        if not field_instance.repeated:
            raise FieldDefinitionError('FieldList may only accept repeated fields')

        self.__message = message_instance
        self.__field = field_instance
        self.__field.validate(sequence)
        list.__init__(self, sequence)

    @property
    def field(self):
        """Field that validates list."""
        return self.__field

    @property
    def message(self):
        """Message this value belongs to"""
        return self.__message

    def __notify_message_of_value_change(self):
        """Notify the message that our value has changed to ensure that the value is marked as set"""
        if self.__message and self.__field:
            setattr(self.__message, self.__field.alias, self)

    def __setslice__(self, i, j, sequence):
        """Validate slice assignment to list."""
        self.__field.validate(sequence)
        list.__setslice__(self, i, j, sequence)
        self.__notify_message_of_value_change()

    def __setitem__(self, index, value):
        """Validate item assignment to list."""
        self.__field.validate_element(value)
        list.__setitem__(self, index, value)
        self.__notify_message_of_value_change()

    def append(self, value):
        """Validate item appending to list."""
        self.__field.validate_element(value)
        ret_val = list.append(self, value)
        self.__notify_message_of_value_change()
        return ret_val


    def extend(self, sequence):
        """Validate extension of list."""
        self.__field.validate(sequence)
        ret_val = list.extend(self, sequence)
        self.__notify_message_of_value_change()
        return ret_val

    def insert(self, index, value):
        """Validate item insertion to list."""
        self.__field.validate_element(value)
        ret_val = list.insert(self, index, value)
        self.__notify_message_of_value_change()
        return ret_val

# TODO(rafek): Prevent additional field subclasses.
class Field(object):
    __variant_to_type = {}

    class __metaclass__(type):

        def __init__(cls, name, bases, dct):
            getattr(cls, '_Field__variant_to_type').update(
                (variant, cls) for variant in dct.get('VARIANTS', []))
            type.__init__(cls, name, bases, dct)

    __initialized = False

    @util.positional(1)
    def __init__(self,
                 name=None,
                 required=False,
                 repeated=False,
                 variant=None,
                 default=None):
        """Constructor.

        The required and repeated parameters are mutually exclusive.  Setting both
        to True will raise a FieldDefinitionError.

        Sub-class Attributes:
          Each sub-class of Field must define the following:
            VARIANTS: Set of variant types accepted by that field.
            DEFAULT_VARIANT: Default variant type if not specified in constructor.

        Args:
          number: Number of field.  Must be unique per message class.
          required: Whether or not field is required.  Mutually exclusive with
            'repeated'.
          repeated: Whether or not field is repeated.  Mutually exclusive with
            'required'.
          variant: Wire-format variant hint.
          default: Default value for field if not found in stream.

        Raises:
          InvalidVariantError when invalid variant for field is provided.
          InvalidDefaultError when invalid default for field is provided.
          FieldDefinitionError when invalid number provided or mutually exclusive
            fields are used.
          InvalidNumberError when the field number is out of range or reserved.
        """
        if repeated and required:
            raise FieldDefinitionError('Cannot set both repeated and required')

        if variant is None:
            variant = self.DEFAULT_VARIANT

        if repeated and default is not None:
            raise FieldDefinitionError('Repeated fields may not have defaults')

        if variant not in self.VARIANTS:
            raise InvalidVariantError(
                'Invalid variant: %s\nValid variants for %s are %r' %
                (variant, type(self).__name__, sorted(self.VARIANTS)))

        # The name used in encoding
        if name:
            self.name = name

        # The name used in code
        self.alias = None

        self.required = required
        self.repeated = repeated
        self.variant = variant

        if default is not None:
            try:
                self.validate_default(default)
            except ValidationError, err:
                try:
                    err_name = name or self.name
                except AttributeError:
                    # For when raising error before name initialization.
                    raise InvalidDefaultError('Invalid default value for %s: %s: %s' %
                                              (self.__class__.__name__, default, err))
                else:
                    raise InvalidDefaultError('Invalid default value for field %s: '
                                              '%s: %s' % (err_name, default, err))

        self.__default = default
        self.__initialized = True

    def __setattr__(self, name, value):
        """Setter overidden to prevent assignment to fields after creation.

        Args:
          name: Name of attribute to set.
          value: Value to assign.
        """
        # Special case post-init names.  They need to be set after constructor.
        if name in _POST_INIT_FIELD_ATTRIBUTE_NAMES:
            object.__setattr__(self, name, value)
            return

        # All other attributes must be set before __initialized.
        if not self.__initialized:
            # Not initialized yet, allow assignment.
            object.__setattr__(self, name, value)
        else:
            raise AttributeError('Field objects are read-only')

    def __set__(self, message_instance, value):
        """Set value on message.

        Args:
          message_instance: Message instance to set value on.
          value: Value to set on message.
        """
        # Reaches in to message instance directly to assign to private tags.
        if value is None and self.repeated:
                raise ValidationError(
                    'May not assign None to repeated field %s' % self.name)

        if self.repeated:
            value = FieldList(message_instance=message_instance,
                              field_instance=self,
                              sequence=value)
        else:
            self.validate(value)

        message_instance._Message__field_values[self.name] = value
        message_instance._Message__set_fields.add(self.name)

    def __get__(self, message_instance, message_class):
        if message_instance is None:
            return self

        result = message_instance._Message__field_values.get(self.name)
        if result is None:
            return self.default
        else:
            return result

    def validate_element(self, value):
        """Validate single element of field.

        This is different from validate in that it is used on individual
        values of repeated fields.

        Args:
          value: Value to validate.

        Raises:
          ValidationError if value is not expected type.
        """
        if not isinstance(value, self.type):
            if value is None:
                if self.required:
                    raise ValidationError('Required field is missing')
            else:
                try:
                    name = self.name
                except AttributeError:
                    raise ValidationError('Expected type %s for %s, '
                                          'found %s (type %s)' %
                                          (self.type, self.__class__.__name__,
                                           value, type(value)))
                else:
                    raise ValidationError('Expected type %s for field %s, '
                                          'found %s (type %s)' %
                                          (self.type, name, value, type(value)))

    def __validate(self, value, validate_element):
        """Internal validation function.

        Validate an internal value using a function to validate individual elements.

        Args:
          value: Value to validate.
          validate_element: Function to use to validate individual elements.

        Raises:
          ValidationError if value is not expected type.
        """
        if not self.repeated:
            validate_element(value)
        else:
            # Must be a list or tuple, may not be a string.
            if isinstance(value, (list, tuple)):
                for element in value:
                    if element is None:
                        try:
                            name = self.name
                        except AttributeError:
                            raise ValidationError('Repeated values for %s '
                                                  'may not be None' % self.__class__.__name__)
                        else:
                            raise ValidationError('Repeated values for field %s '
                                                  'may not be None' % name)
                    validate_element(element)
            elif value is not None:
                try:
                    name = self.name
                except AttributeError:
                    raise ValidationError('%s is repeated. Found: %s' % (
                        self.__class__.__name__, value))
                else:
                    raise ValidationError('Field %s is repeated. Found: %s' % (name,
                                                                               value))

    def coerce(self, value):
        """
        Attempt to coerce the specified value into the type needed for this field.

        :param value: the value to coerce

        :raises: ValueError if the value cannot be coerced

        :return: the value coerced to the type for this field
        """
        if value is None:
            return None

        our_type = self.__class__.type
        types = our_type if isinstance(our_type, tuple) else (our_type,)

        for tp in types:
            try:
                return tp(value)
            except ValueError:
                pass
            except TypeError:
                pass


        raise ValueError("Cannot convert value '%s' to type(s) %s for field %s" % (value, our_type, self.name))

    def validate(self, value):
        """Validate value assigned to field.

        Args:
          value: Value to validate.

        Raises:
          ValidationError if value is not expected type.
        """
        self.__validate(value, self.validate_element)

    def validate_default_element(self, value):
        """Validate value as assigned to field default field.

        Some fields may allow for delayed resolution of default types necessary
        in the case of circular definition references.  In this case, the default
        value might be a place holder that is resolved when needed after all the
        message classes are defined.

        Args:
          value: Default value to validate.

        Raises:
          ValidationError if value is not expected type.
        """
        self.validate_element(value)

    def validate_default(self, value):
        """Validate default value assigned to field.

        Args:
          value: Value to validate.

        Raises:
          ValidationError if value is not expected type.
        """
        self.__validate(value, self.validate_default_element)

    def message_definition(self):
        """Get Message definition that contains this Field definition.

        Returns:
          Containing Message definition for Field.  Will return None if for
          some reason Field is defined outside of a Message class.
        """
        try:
            return self._message_definition()
        except AttributeError:
            return None

    @property
    def default(self):
        """Get default value for field."""
        return self.__default

    @classmethod
    def lookup_field_type_by_variant(cls, variant):
        return cls.__variant_to_type[variant]

    def is_set(self, message):
        """
        Checks if the value for this field is set on the specified message.

        :param message: the message to check if the field is set for

        :return: True if the field is set, False otherwise
        """
        return message.has_value_assigned(self.name)


class UntypedField(Field):
    """Field that does not care what type is given to it"""
    VARIANTS = frozenset([Variant.INT32,
                          Variant.INT64,
                          Variant.UINT32,
                          Variant.UINT64,
                          Variant.SINT32,
                          Variant.SINT64,
                          Variant.FLOAT,
                          Variant.DOUBLE,
                          Variant.BOOL,
                          Variant.BYTES,
                          Variant.STRING,
                          Variant.MESSAGE
    ])

    DEFAULT_VARIANT = Variant.STRING

    type = (int, long, float, bool, str, unicode, dict, list)


class IntegerField(Field):
    """Field definition for integer values."""

    VARIANTS = frozenset([Variant.INT32,
                          Variant.INT64,
                          Variant.UINT32,
                          Variant.UINT64,
                          Variant.SINT32,
                          Variant.SINT64,
    ])

    DEFAULT_VARIANT = Variant.INT64

    type = (int, long)


class FloatField(Field):
    """Field definition for float values."""

    VARIANTS = frozenset([Variant.FLOAT,
                          Variant.DOUBLE,
    ])

    DEFAULT_VARIANT = Variant.DOUBLE

    type = float


class BooleanField(Field):
    """Field definition for boolean values."""

    VARIANTS = frozenset([Variant.BOOL])

    DEFAULT_VARIANT = Variant.BOOL

    type = bool


class DateTimeISO8601Field(Field):
    """
    Field definition for date fields encoded as ISO8601 string values.

    Encoding is done for JSON and URLs, dicts are left as native Python datetimes
    """

    VARIANTS = frozenset([Variant.STRING])

    DEFAULT_VARIANT = Variant.STRING

    type = datetime.datetime


class DateTimeMsIntegerField(Field):
    """
    Field definition for date fields encoded as milliseconds since the epoch integer values.

    Encoding is done for JSON and URLs, dicts are left as native Python datetimes
    """

    VARIANTS = frozenset([Variant.INT32, Variant.INT64, Variant.UINT32, Variant.UINT64])

    DEFAULT_VARIANT = Variant.INT32

    type = datetime.datetime


class BytesField(Field):
    """Field definition for byte string values."""

    VARIANTS = frozenset([Variant.BYTES])

    DEFAULT_VARIANT = Variant.BYTES

    type = str


class StringField(Field):
    """Field definition for unicode string values."""

    VARIANTS = frozenset([Variant.STRING])

    DEFAULT_VARIANT = Variant.STRING

    type = unicode

    def validate_element(self, value):
        """Validate StringField allowing for str and unicode.

        Raises:
          ValidationError if a str value is not 7-bit ascii.
        """
        # If value is str is it considered valid.  Satisfies "required=True".
        if isinstance(value, str):
            try:
                unicode(value)
            except UnicodeDecodeError, err:
                try:
                    name = self.name
                except AttributeError:
                    validation_error = ValidationError(
                        'Field encountered non-ASCII string %s: %s' % (value,
                                                                       err))
                else:
                    validation_error = ValidationError(
                        'Field %s encountered non-ASCII string %s: %s' % (self.name,
                                                                          value,
                                                                          err))
                    validation_error.field_name = self.name
                raise validation_error
        else:
            super(StringField, self).validate_element(value)


class DictField(Field):
    """
    Field definition for dict values. This is to allow unstructured data into a message.
    """

    VARIANTS = frozenset([Variant.MESSAGE])

    DEFAULT_VARIANT = Variant.MESSAGE

    type = dict


class MessageField(Field):
    """Field definition for sub-message values.

    Message fields contain instance of other messages.  Instances stored
    on messages stored on message fields  are considered to be owned by
    the containing message instance and should not be shared between
    owning instances.

    Message fields must be defined to reference a single type of message.
    Normally message field are defined by passing the referenced message
    class in to the constructor.

    It is possible to define a message field for a type that does not yet
    exist by passing the name of the message in to the constructor instead
    of a message class.  Resolution of the actual type of the message is
    deferred until it is needed, for example, during message verification.
    Names provided to the constructor must refer to a class within the same
    python module as the class that is using it.  Names refer to messages
    relative to the containing messages scope.  For example, the two fields
    of OuterMessage refer to the same message type:

      class Outer(Message):

        inner_relative = MessageField('Inner', 1)
        inner_absolute = MessageField('Outer.Inner', 2)

        class Inner(Message):
          ...

    When resolving an actual type, MessageField will traverse the entire
    scope of nested messages to match a message name.  This makes it easy
    for siblings to reference siblings:

      class Outer(Message):

        class Inner(Message):

          sibling = MessageField('Sibling', 1)

        class Sibling(Message):
          ...
    """

    VARIANTS = frozenset([Variant.MESSAGE])

    DEFAULT_VARIANT = Variant.MESSAGE

    @util.positional(2)
    def __init__(self,
                 message_type,
                 name=None,
                 required=False,
                 repeated=False,
                 variant=None):
        """Constructor.

        Args:
          message_type: Message type for field.  Must be subclass of Message.
          number: Number of field.  Must be unique per message class.
          required: Whether or not field is required.  Mutually exclusive to
            'repeated'.
          repeated: Whether or not field is repeated.  Mutually exclusive to
            'required'.
          variant: Wire-format variant hint.

        Raises:
          FieldDefinitionError when invalid message_type is provided.
        """
        valid_type = (isinstance(message_type, basestring) or
                      (message_type is not Message and
                       isinstance(message_type, type) and
                       issubclass(message_type, Message)))

        if not valid_type:
            raise FieldDefinitionError('Invalid message class: %s' % message_type)

        if isinstance(message_type, basestring):
            self.__type_name = message_type
            self.__type = None
        else:
            self.__type = message_type

        super(MessageField, self).__init__(name=name,
                                           required=required,
                                           repeated=repeated,
                                           variant=variant)

    def __set__(self, message_instance, value):
        """Set value on message.

        Args:
          message_instance: Message instance to set value on.
          value: Value to set on message.
        """
        message_type = self.type
        if isinstance(message_type, type) and issubclass(message_type, Message):
            if self.repeated:
                if value and isinstance(value, (list, tuple)):
                    value = [(message_type(**v) if isinstance(v, dict) else v)
                             for v in value]
            elif isinstance(value, dict):
                value = message_type(**value)
        super(MessageField, self).__set__(message_instance, value)

    @property
    def type(self):
        """Message type used for field."""
        if self.__type is None:
            message_type = find_definition(self.__type_name, self.message_definition())
            if not (message_type is not Message and
                        isinstance(message_type, type) and
                        issubclass(message_type, Message)):
                raise FieldDefinitionError('Invalid message class: %s' % message_type)
            self.__type = message_type
        return self.__type

    @property
    def message_type(self):
        """Underlying message type used for serialization.

        Will always be a sub-class of Message.  This is different from type
        which represents the python value that message_type is mapped to for
        use by the user.
        """
        return self.type

    def value_from_message(self, message):
        """Convert a message to a value instance.

        Used by deserializers to convert from underlying messages to
        value of expected user type.

        Args:
          message: A message instance of type self.message_type.

        Returns:
          Value of self.message_type.
        """
        if not isinstance(message, self.message_type):
            raise DecodeError('Expected type %s, got %s: %r' %
                              (self.message_type.__name__,
                               type(message).__name__,
                               message))
        return message

    def value_to_message(self, value):
        """Convert a value instance to a message.

        Used by serializers to convert Python user types to underlying
        messages for transmission.

        Args:
          value: A value of type self.type.

        Returns:
          An instance of type self.message_type.
        """
        if not isinstance(value, self.type):
            raise EncodeError('Expected type %s, got %s: %r' %
                              (self.type.__name__,
                               type(value).__name__,
                               value))
        return value


class EnumField(Field):
    """Field definition for enum values.

    Enum fields may have default values that are delayed until the associated enum
    type is resolved.  This is necessary to support certain circular references.

    For example:

      class Message1(Message):

        class Color(Enum):

          RED = 1
          GREEN = 2
          BLUE = 3

        # This field default value  will be validated when default is accessed.
        animal = EnumField('Message2.Animal', 1, default='HORSE')

      class Message2(Message):

        class Animal(Enum):

          DOG = 1
          CAT = 2
          HORSE = 3

        # This fields default value will be validated right away since Color is
        # already fully resolved.
        color = EnumField(Message1.Color, 1, default='RED')
    """

    VARIANTS = frozenset([Variant.ENUM])

    DEFAULT_VARIANT = Variant.ENUM

    def __init__(self, enum_type, **kwargs):
        """Constructor.

        Args:
          enum_type: Enum type for field.  Must be subclass of Enum.
          number: Number of field.  Must be unique per message class.
          required: Whether or not field is required.  Mutually exclusive to
            'repeated'.
          repeated: Whether or not field is repeated.  Mutually exclusive to
            'required'.
          variant: Wire-format variant hint.
          default: Default value for field if not found in stream.

        Raises:
          FieldDefinitionError when invalid enum_type is provided.
        """
        valid_type = (isinstance(enum_type, basestring) or
                      (enum_type is not Enum and
                       isinstance(enum_type, type) and
                       issubclass(enum_type, Enum)))

        if not valid_type:
            raise FieldDefinitionError('Invalid enum type: %s' % enum_type)

        if isinstance(enum_type, basestring):
            self.__type_name = enum_type
            self.__type = None
        else:
            self.__type = enum_type

        super(EnumField, self).__init__(**kwargs)

    def validate_default_element(self, value):
        """Validate default element of Enum field.

        Enum fields allow for delayed resolution of default values when the type
        of the field has not been resolved.  The default value of a field may be
        a string or an integer.  If the Enum type of the field has been resolved,
        the default value is validated against that type.

        Args:
          value: Value to validate.

        Raises:
          ValidationError if value is not expected message type.
        """
        if isinstance(value, (basestring, int, long)):
            # Validation of the value does not happen for delayed resolution
            # enumerated types.  Ignore if type is not yet resolved.
            if self.__type:
                self.__type(value)
            return

        super(EnumField, self).validate_default_element(value)

    @property
    def type(self):
        """Enum type used for field."""
        if self.__type is None:
            found_type = find_definition(self.__type_name, self.message_definition())
            if not (found_type is not Enum and
                        isinstance(found_type, type) and
                        issubclass(found_type, Enum)):
                raise FieldDefinitionError('Invalid enum type: %s' % found_type)

            self.__type = found_type
        return self.__type

    @property
    def default(self):
        """Default for enum field.

        Will cause resolution of Enum type and unresolved default value.
        """
        try:
            return self.__resolved_default
        except AttributeError:
            resolved_default = super(EnumField, self).default
            if isinstance(resolved_default, (basestring, int, long)):
                resolved_default = self.type(resolved_default)
            self.__resolved_default = resolved_default
            return self.__resolved_default


@util.positional(2)
def find_definition(name, relative_to=None, importer=__import__):
    """Find definition by name in module-space.

    The find algorthm will look for definitions by name relative to a message
    definition or by fully qualfied name.  If no definition is found relative
    to the relative_to parameter it will do the same search against the container
    of relative_to.  If relative_to is a nested Message, it will search its
    message_definition().  If that message has no message_definition() it will
    search its module.  If relative_to is a module, it will attempt to look for
    the containing module and search relative to it.  If the module is a top-level
    module, it will look for the a message using a fully qualified name.  If
    no message is found then, the search fails and DefinitionNotFoundError is
    raised.

    For example, when looking for any definition 'foo.bar.ADefinition' relative to
    an actual message definition abc.xyz.SomeMessage:

      find_definition('foo.bar.ADefinition', SomeMessage)

    It is like looking for the following fully qualified names:

      abc.xyz.SomeMessage. foo.bar.ADefinition
      abc.xyz. foo.bar.ADefinition
      abc. foo.bar.ADefinition
      foo.bar.ADefinition

    When resolving the name relative to Message definitions and modules, the
    algorithm searches any Messages or sub-modules found in its path.
    Non-Message values are not searched.

    A name that begins with '.' is considered to be a fully qualified name.  The
    name is always searched for from the topmost package.  For example, assume
    two message types:

      abc.xyz.SomeMessage
      xyz.SomeMessage

    Searching for '.xyz.SomeMessage' relative to 'abc' will resolve to
    'xyz.SomeMessage' and not 'abc.xyz.SomeMessage'.  For this kind of name,
    the relative_to parameter is effectively ignored and always set to None.

    For more information about package name resolution, please see:

      http://code.google.com/apis/protocolbuffers/docs/proto.html#packages

    Args:
      name: Name of definition to find.  May be fully qualified or relative name.
      relative_to: Search for definition relative to message definition or module.
        None will cause a fully qualified name search.
      importer: Import function to use for resolving modules.

    Returns:
      Enum or Message class definition associated with name.

    Raises:
      DefinitionNotFoundError if no definition is found in any search path.
    """
    # Check parameters.
    if not (relative_to is None or
                isinstance(relative_to, types.ModuleType) or
                    isinstance(relative_to, type) and issubclass(relative_to, Message)):
        raise TypeError('relative_to must be None, Message definition or module.  '
                        'Found: %s' % relative_to)

    name_path = name.split('.')

    # Handle absolute path reference.
    if not name_path[0]:
        relative_to = None
        name_path = name_path[1:]

    def search_path():
        """Performs a single iteration searching the path from relative_to.

        This is the function that searches up the path from a relative object.

          fully.qualified.object . relative.or.nested.Definition
                                   ---------------------------->
                                                      ^
                                                      |
                                this part of search --+

        Returns:
          Message or Enum at the end of name_path, else None.
        """
        next = relative_to
        for node in name_path:
            # Look for attribute first.
            attribute = getattr(next, node, None)

            if attribute is not None:
                next = attribute
            else:
                # If module, look for sub-module.
                if next is None or isinstance(next, types.ModuleType):
                    if next is None:
                        module_name = node
                    else:
                        module_name = '%s.%s' % (next.__name__, node)

                    try:
                        fromitem = module_name.split('.')[-1]
                        next = importer(module_name, '', '', [str(fromitem)])
                    except ImportError:
                        return None
                else:
                    return None

            if (not isinstance(next, types.ModuleType) and
                    not (isinstance(next, type) and
                             issubclass(next, (Message, Enum)))):
                return None

        return next

    while True:
        found = search_path()
        if isinstance(found, type) and issubclass(found, (Enum, Message)):
            return found
        else:
            # Find next relative_to to search against.
            #
            #   fully.qualified.object . relative.or.nested.Definition
            #   <---------------------
            #           ^
            #           |
            #   does this part of search
            if relative_to is None:
                # Fully qualified search was done.  Nothing found.  Fail.
                raise DefinitionNotFoundError('Could not find definition for %s'
                                              % (name,))
            else:
                if isinstance(relative_to, types.ModuleType):
                    # Find parent module.
                    module_path = relative_to.__name__.split('.')[:-1]
                    if not module_path:
                        relative_to = None
                    else:
                        # Should not raise ImportError.  If it does... weird and
                        # unexepected.  Propagate.
                        relative_to = importer(
                            '.'.join(module_path), '', '', [module_path[-1]])
                elif (isinstance(relative_to, type) and
                          issubclass(relative_to, Message)):
                    parent = relative_to.message_definition()
                    if parent is None:
                        last_module_name = relative_to.__module__.split('.')[-1]
                        relative_to = importer(
                            relative_to.__module__, '', '', [last_module_name])
                    else:
                        relative_to = parent
