English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# Messages Module Functions

#### Experimental!

ProtoRPC is an experimental, innovative, and rapidly changing new feature for App Engine. Unfortunately, being on the bleeding edge means that we may make backwards-incompatible changes to ProtoRPC. We will inform the community when this feature is no longer experimental.

The `protorpc.messages` package provides the following positional utility function:

find_definition(name, relative_to=None)

  Find definition by name in module-space.

  The find algorithm finds definitions by name relative to a message definition or by fully qualified name. If no definition is found relative to the `relative_to` parameter, it searches against the container of `relative_to`. If `relative_to` is a nested Message, it searches its message_definition(). If that message has no message_definition(), it searches its module. If `relative_to` is a module, the find algorithm searches for the containing module and searches relative to it. If the module is a top-level module, the find algorithm searches for the a message using a fully qualified name. If it still finds no message, the search fails and the method raises a DefinitionNotFoundError.

  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)

  The arguments to this method follow a pattern similar to a search for 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, ignoring non-Message values.

  A name that begins with `'.'` is considered to be a fully qualified name. The find algorithm begins searching from the topmost package. For example, assume two message types:

      abc.xyz.SomeMessage
      xyz.SomeMessage

  Searching for `.xyz.SomeMessage` relative to `abc` resolves 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 the Protocol Buffers Package specifier.

  Arguments:

  name
    Name of a definition to find. May be fully qualified or relative.
  relative_to
    Searches for a definition relative to the message definition or module. If None, causes a fully qualified name search.

  Returns an Enum or Message class definition associated with the name.

  raises a DefinitionNotFoundError if no definition is found in any search path.