Key.from_path: confusing python code in datastore documents for applications

Question

On this page: https://developers.google.com/appengine/docs/python/datastore/keyclass#Key_from_path

This part:

Key.from_path (view, id_or_name, parent = none, namespace = None, ** kwds) Creates a new Key object from the path of the ancestor of one or more entity keys.

A path represents a hierarchy of parent-child relationships for an object. Each object in the path represents an entity type, as well as its numerical identifier or its key name. The full path represents the object that appears last in the path, with its ancestors (parents) as previous objects.

For example, the following call creates a key for an entity of type Address with a numeric identifier of 9876, whose parent is an entity of the form of a user with the named key Boris:

k = Key.from_path ('User', 'Boris', 'Address', 9876)

For more information about paths, see Object Groups and Groups.

The function call and explanation just doesn't make sense here if Address is the "good" argument, if it's the first time? And ID 9876 should go second? Why are they 3rd and 4th?
And "parent" is the third parameter, why are there two "parent" arguments (the form "User" and the name "Boris"), and they are the first and second in the list of arguments?

Answer 1

Keys in AppEngine are hierarchical, to get the full key, you need to pass all the pedigree information.

In the case of the example, there are two types of objects: User and Address, User is the parent address for the address. In the from_path call, the User object type is first set, its identifier is Boris (id can be a string name or integer id), this object has a child object of type Address, its identifier is 9876.

Answer 2

From the Gee source code, the signature of the static method from_path of the Key class:

 def from_path(*args, **kwds): 

accepting a nonzero even number of positional arguments in the form (kind, id or name, kind, id or name, etc. etc.) :

 if not args or len(args) % 2: raise datastore_errors.BadArgumentError( 'A non-zero even number of positional arguments is required ' '(kind, id or name, kind, id or name, ...); received %s' % repr(args)) 

As indicated in the documentation, the full path is the entity that appears last in the path, with its ancestors (parents) being the previous objects.

So the example seems right; the created key is a key of an object of the type Address with id 9876, which has the parent view of the user with Boris as key name .