App Engine Python SDK  v1.6.9 rev.445
The Python runtime is available as an experimental Preview feature.
Classes | Functions | Variables
google.appengine.ext.ndb.model Namespace Reference

Classes

class  _BaseValue
 
class  _CompressedValue
 
class  _NestedCounter
 
class  _NotEqualMixin
 
class  _StructuredGetForDictMixin
 
class  BlobKeyProperty
 
class  BlobProperty
 
class  BooleanProperty
 
class  ComputedProperty
 
class  ComputedPropertyError
 
class  DateProperty
 
class  DateTimeProperty
 
class  Expando
 
class  FloatProperty
 
class  GenericProperty
 
class  GeoPtProperty
 
class  Index
 
class  IndexProperty
 
class  IndexState
 
class  IntegerProperty
 
class  InvalidPropertyError
 
class  JsonProperty
 
class  KeyProperty
 
class  KindError
 
class  LocalStructuredProperty
 
class  MetaModel
 
class  Model
 
class  ModelAdapter
 
class  ModelAttribute
 
class  ModelKey
 
class  PickleProperty
 
class  Property
 
class  ReadonlyPropertyError
 
class  StringProperty
 
class  StructuredProperty
 
class  TextProperty
 
class  TimeProperty
 
class  UnprojectedPropertyError
 
class  UserProperty
 

Functions

def make_connection
 
def transaction
 
def transaction_async
 
def in_transaction
 
def transactional
 
def transactional_async
 
def transactional_tasklet
 
def non_transactional
 
def get_multi_async
 
def get_multi
 
def put_multi_async
 
def put_multi
 
def delete_multi_async
 
def delete_multi
 
def get_indexes_async
 
def get_indexes
 

Variables

string __author__ = 'guido@google.com (Guido van Rossum)'
 
 Key = key_module.Key
 
list __all__
 
 BlobKey = datastore_types.BlobKey
 
 GeoPt = datastore_types.GeoPt
 
 Rollback = datastore_errors.Rollback
 
 BadProjectionError = InvalidPropertyError
 
 _MAX_LONG = key_module._MAX_LONG
 
 _MAX_STRING_LENGTH = datastore_types._MAX_STRING_LENGTH
 
dictionary _DIR_MAP
 
dictionary _STATE_MAP
 
string _MEANING_URI_COMPRESSED = 'ZLIB'
 
tuple _EPOCH = datetime.datetime.utcfromtimestamp(0)
 

Detailed Description

Model and Property classes and associated stuff.

A model class represents the structure of entities stored in the
datastore.  Applications define model classes to indicate the
structure of their entities, then instantiate those model classes
to create entities.

All model classes must inherit (directly or indirectly) from Model.
Through the magic of metaclasses, straightforward assignments in the
model class definition can be used to declare the model's structure:

  class Person(Model):
name = StringProperty()
age = IntegerProperty()

We can now create a Person entity and write it to the datastore:

  p = Person(name='Arthur Dent', age=42)
  k = p.put()

The return value from put() is a Key (see the documentation for
ndb/key.py), which can be used to retrieve the same entity later:

  p2 = k.get()
  p2 == p  # Returns True

To update an entity, simple change its attributes and write it back
(note that this doesn't change the key):

  p2.name = 'Arthur Philip Dent'
  p2.put()

We can also delete an entity (by using the key):

  k.delete()

The property definitions in the class body tell the system the names
and the types of the fields to be stored in the datastore, whether
they must be indexed, their default value, and more.

Many different Property types exist.  Most are indexed by default, the
exceptions indicated in the list below:

- StringProperty: a short text string, limited to 500 bytes

- TextProperty: an unlimited text string; unindexed

- BlobProperty: an unlimited byte string; unindexed

- IntegerProperty: a 64-bit signed integer

- FloatProperty: a double precision floating point number

- BooleanProperty: a bool value

- DateTimeProperty: a datetime object.  Note: App Engine always uses
  UTC as the timezone

- DateProperty: a date object

- TimeProperty: a time object

- GeoPtProperty: a geographical location, i.e. (latitude, longitude)

- KeyProperty: a datastore Key value, optionally constrained to
  referring to a specific kind

- UserProperty: a User object (for backwards compatibility only)

- StructuredProperty: a field that is itself structured like an
  entity; see below for more details

- LocalStructuredProperty: like StructuredProperty but the on-disk
  representation is an opaque blob; unindexed

- ComputedProperty: a property whose value is computed from other
  properties by a user-defined function.  The property value is
  written to the datastore so that it can be used in queries, but the
  value from the datastore is not used when the entity is read back

- GenericProperty: a property whose type is not constrained; mostly
  used by the Expando class (see below) but also usable explicitly

- JsonProperty: a property whose value is any object that can be
  serialized using JSON; the value written to the datastore is a JSON
  representation of that object

- PickleProperty: a property whose value is any object that can be
  serialized using Python's pickle protocol; the value written to the
  datastore is the pickled representation of that object, using the
  highest available pickle protocol

Most Property classes have similar constructor signatures.  They
accept several optional keyword arguments:

- name=<string>: the name used to store the property value in the
  datastore.  Unlike the following options, this may also be given as
  a positional argument

- indexed=<bool>: indicates whether the property should be indexed
  (allowing queries on this property's value)

- repeated=<bool>: indicates that this property can have multiple
  values in the same entity.

- required=<bool>: indicates that this property must be given a value

- default=<value>: a default value if no explicit value is given

- choices=<list of values>: a list or tuple of allowable values

- validator=<function>: a general-purpose validation function.  It
  will be called with two arguments (prop, value) and should either
  return the validated value or raise an exception.  It is also
  allowed for the function to modify the value, but calling it again
  on the modified value should not modify the value further.  (For
  example: a validator that returns value.strip() or value.lower() is
  fine, but one that returns value + '$' is not.)

- verbose_name=<value>: A human readable name for this property.  This
  human readable name can be used for html form labels.

The repeated and required/default options are mutually exclusive: a
repeated property cannot be required nor can it specify a default
value (the default is always an empty list and an empty list is always
an allowed value), but a required property can have a default.

Some property types have additional arguments.  Some property types
do not support all options.

Repeated properties are always represented as Python lists; if there
is only one value, the list has only one element.  When a new list is
assigned to a repeated property, all elements of the list are
validated.  Since it is also possible to mutate lists in place,
repeated properties are re-validated before they are written to the
datastore.

No validation happens when an entity is read from the datastore;
however property values read that have the wrong type (e.g. a string
value for an IntegerProperty) are ignored.

For non-repeated properties, None is always a possible value, and no
validation is called when the value is set to None.  However for
required properties, writing the entity to the datastore requires
the value to be something other than None (and valid).

The StructuredProperty is different from most other properties; it
lets you define a sub-structure for your entities.  The substructure
itself is defined using a model class, and the attribute value is an
instance of that model class.  However it is not stored in the
datastore as a separate entity; instead, its attribute values are
included in the parent entity using a naming convention (the name of
the structured attribute followed by a dot followed by the name of the
subattribute).  For example:

  class Address(Model):
street = StringProperty()
city = StringProperty()

  class Person(Model):
name = StringProperty()
address = StructuredProperty(Address)

  p = Person(name='Harry Potter',
         address=Address(street='4 Privet Drive',
                         city='Little Whinging'))
  k.put()

This would write a single 'Person' entity with three attributes (as
you could verify using the Datastore Viewer in the Admin Console):

  name = 'Harry Potter'
  address.street = '4 Privet Drive'
  address.city = 'Little Whinging'

Structured property types can be nested arbitrarily deep, but in a
hierarchy of nested structured property types, only one level can have
the repeated flag set.  It is fine to have multiple structured
properties referencing the same model class.

It is also fine to use the same model class both as a top-level entity
class and as for a structured property; however queries for the model
class will only return the top-level entities.

The LocalStructuredProperty works similar to StructuredProperty on the
Python side.  For example:

  class Address(Model):
street = StringProperty()
city = StringProperty()

  class Person(Model):
name = StringProperty()
address = LocalStructuredProperty(Address)

  p = Person(name='Harry Potter',
         address=Address(street='4 Privet Drive',
                         city='Little Whinging'))
  k.put()

However the data written to the datastore is different; it writes a
'Person' entity with a 'name' attribute as before and a single
'address' attribute whose value is a blob which encodes the Address
value (using the standard"protocol buffer" encoding).

Sometimes the set of properties is not known ahead of time.  In such
cases you can use the Expando class.  This is a Model subclass that
creates properties on the fly, both upon assignment and when loading
an entity from the datastore.  For example:

  class SuperPerson(Expando):
name = StringProperty()
superpower = StringProperty()

  razorgirl = SuperPerson(name='Molly Millions',
                      superpower='bionic eyes, razorblade hands',
                      rasta_name='Steppin\' Razor',
                      alt_name='Sally Shears')
  elastigirl = SuperPerson(name='Helen Parr',
                       superpower='stretchable body')
  elastigirl.max_stretch = 30  # Meters

You can inspect the properties of an expando instance using the
_properties attribute:

  >>> print razorgirl._properties.keys()
  ['rasta_name', 'name', 'superpower', 'alt_name']
  >>> print elastigirl._properties
  {'max_stretch': GenericProperty('max_stretch'),
   'name': StringProperty('name'),
   'superpower': StringProperty('superpower')}

Note: this property exists for plain Model instances too; it is just
not as interesting for those.

The Model class offers basic query support.  You can create a Query
object by calling the query() class method.  Iterating over a Query
object returns the entities matching the query one at a time.

Query objects are fully described in the docstring for query.py, but
there is one handy shortcut that is only available through
Model.query(): positional arguments are interpreted as filter
expressions which are combined through an AND operator.  For example:

  Person.query(Person.name == 'Harry Potter', Person.age >= 11)

is equivalent to:

  Person.query().filter(Person.name == 'Harry Potter', Person.age >= 11)

Keyword arguments passed to .query() are passed along to the Query()
constructor.

It is possible to query for field values of stuctured properties.  For
example:

  qry = Person.query(Person.address.city == 'London')

A number of top-level functions also live in this module:

- transaction() runs a function inside a transaction
- get_multi() reads multiple entities at once
- put_multi() writes multiple entities at once
- delete_multi() deletes multiple entities at once

All these have a corresponding *_async() variant as well.
The *_multi_async() functions return a list of Futures.

And finally these (without async variants):

- in_transaction() tests whether you are currently running in a transaction
- @transactional decorates functions that should be run in a transaction

There are many other interesting features.  For example, Model
subclasses may define pre-call and post-call hooks for most operations
(get, put, delete, allocate_ids), and Property classes may be
subclassed to suit various needs.  Documentation for writing a
Property subclass is in the docstring for the Property class.

Function Documentation

def google.appengine.ext.ndb.model.delete_multi (   keys,
  ctx_options 
)
Deletes a sequence of keys.

Args:
  keys: A sequence of keys.
  **ctx_options: Context options.

Returns:
  A list whose items are all None, one per deleted key.
def google.appengine.ext.ndb.model.delete_multi_async (   keys,
  ctx_options 
)
Deletes a sequence of keys.

Args:
  keys: A sequence of keys.
  **ctx_options: Context options.

Returns:
  A list of futures.
def google.appengine.ext.ndb.model.get_indexes (   ctx_options)
Get a data structure representing the configured indexes.

Args:
  **ctx_options: Context options.

Returns:
  A list of Index objects.
def google.appengine.ext.ndb.model.get_indexes_async (   ctx_options)
Get a data structure representing the configured indexes.

Args:
  **ctx_options: Context options.

Returns:
  A future.
def google.appengine.ext.ndb.model.get_multi (   keys,
  ctx_options 
)
Fetches a sequence of keys.

Args:
  keys: A sequence of keys.
  **ctx_options: Context options.

Returns:
  A list whose items are either a Model instance or None if the key wasn't
  found.
def google.appengine.ext.ndb.model.get_multi_async (   keys,
  ctx_options 
)
Fetches a sequence of keys.

Args:
  keys: A sequence of keys.
  **ctx_options: Context options.

Returns:
  A list of futures.
def google.appengine.ext.ndb.model.in_transaction ( )
Return whether a transaction is currently active.
def google.appengine.ext.ndb.model.make_connection (   config = None,
  default_model = None 
)
Create a new Connection object with the right adapter.

Optionally you can pass in a datastore_rpc.Configuration object.
def google.appengine.ext.ndb.model.non_transactional (   func,
  args,
  kwds,
  allow_existing = True 
)
A decorator that ensures a function is run outside a transaction.

If there is an existing transaction (and allow_existing=True), the
existing transaction is paused while the function is executed.

Args:
  allow_existing: If false, throw an exception if called from within
    a transaction.  If true, temporarily re-establish the
    previous non-transactional context.  Defaults to True.

This supports two forms, similar to transactional().

Returns:
  A wrapper for the decorated function that ensures it runs outside a
  transaction.
def google.appengine.ext.ndb.model.put_multi (   entities,
  ctx_options 
)
Stores a sequence of Model instances.

Args:
  entities: A sequence of Model instances.
  **ctx_options: Context options.

Returns:
  A list with the stored keys.
def google.appengine.ext.ndb.model.put_multi_async (   entities,
  ctx_options 
)
Stores a sequence of Model instances.

Args:
  entities: A sequence of Model instances.
  **ctx_options: Context options.

Returns:
  A list of futures.
def google.appengine.ext.ndb.model.transaction (   callback,
  ctx_options 
)
Run a callback in a transaction.

Args:
  callback: A function or tasklet to be called.
  **ctx_options: Transaction options.

Useful options include:
  retries=N: Retry up to N times (i.e. try up to N+1 times)
  propagation=<flag>: Determines how an existing transaction should be
    propagated, where <flag> can be one of the following:
    TransactionOptions.NESTED: Start a nested transaction (this is the
      default; but actual nested transactions are not yet implemented,
      so effectively you can only use this outside an existing transaction).
    TransactionOptions.MANDATORY: A transaction must already be in progress.
    TransactionOptions.ALLOWED: If a transaction is in progress, join it.
    TransactionOptions.INDEPENDENT: Always start a new parallel transaction.
  xg=True: On the High Replication Datastore, enable cross-group
    transactions, i.e. allow writing to up to 5 entity groups.

WARNING: Using anything other than NESTED for the propagation flag
can have strange consequences.  When using ALLOWED or MANDATORY, if
an exception is raised, the transaction is likely not safe to
commit.  When using INDEPENDENT it is not generally safe to return
values read to the caller (as they were not read in the caller's
transaction).

Returns:
  Whatever callback() returns.

Raises:
  Whatever callback() raises; datastore_errors.TransactionFailedError
  if the transaction failed.

Note:
  To pass arguments to a callback function, use a lambda, e.g.
    def my_callback(key, inc):
      ...
    transaction(lambda: my_callback(Key(...), 1))
def google.appengine.ext.ndb.model.transaction_async (   callback,
  ctx_options 
)
Run a callback in a transaction.

This is the asynchronous version of transaction().
def google.appengine.ext.ndb.model.transactional (   func,
  args,
  kwds,
  options 
)
Decorator to make a function automatically run in a transaction.

Args:
  **ctx_options: Transaction options (see transaction(), but propagation
    default to TransactionOptions.ALLOWED).

This supports two forms:

(1) Vanilla:
    @transactional
    def callback(arg):
      ...

(2) With options:
    @transactional(retries=1)
    def callback(arg):
      ...
def google.appengine.ext.ndb.model.transactional_async (   func,
  args,
  kwds,
  options 
)
The async version of @ndb.transaction.
def google.appengine.ext.ndb.model.transactional_tasklet (   func,
  args,
  kwds,
  options 
)
The async version of @ndb.transaction.

Will return the result of the wrapped function as a Future.

Variable Documentation

list google.appengine.ext.ndb.model.__all__
Initial value:
1 = ['Key', 'BlobKey', 'GeoPt', 'Rollback',
2  'Index', 'IndexState', 'IndexProperty',
3  'ModelAdapter', 'ModelAttribute',
4  'ModelKey', 'MetaModel', 'Model', 'Expando',
5  'transaction', 'transaction_async', 'in_transaction',
6  'transactional', 'transactional_async', 'transactional_tasklet',
7  'non_transactional',
8  'get_multi', 'get_multi_async',
9  'put_multi', 'put_multi_async',
10  'delete_multi', 'delete_multi_async',
11  'get_indexes', 'get_indexes_async',
12  'make_connection',
13  ]
dictionary google.appengine.ext.ndb.model._DIR_MAP
Initial value:
1 = {
2  entity_pb.Index_Property.ASCENDING: 'asc',
3  entity_pb.Index_Property.DESCENDING: 'desc',
4  }
dictionary google.appengine.ext.ndb.model._STATE_MAP
Initial value:
1 = {
2  entity_pb.CompositeIndex.ERROR: 'error',
3  entity_pb.CompositeIndex.DELETED: 'deleting',
4  entity_pb.CompositeIndex.READ_WRITE: 'serving',
5  entity_pb.CompositeIndex.WRITE_ONLY: 'building',
6  }