Funciones de NDB

Funciones

En esta página, se describe cómo usar las API y los servicios agrupados en paquetes heredados. Esta API solo puede ejecutarse en entornos de ejecución de primera generación en el entorno estándar de App Engine. Si actualizas al entorno de ejecución de Python 3 de App Engine, consulta la guía de migración para obtener información sobre tus opciones de migración para servicios agrupados en paquetes heredados.

ndb.add_flow_exception(exc)

Especifica que una excepción no se debe registrar, sino que es parte de un flujo de programa normal. (Por lo general, cuando se genera una excepción, se escribe un mensaje de advertencia en los registros de la aplicación).

Argumentos

exc

Indica la clase de excepción que no se debe registrar.

Según la configuración predeterminada, no se registran las siguientes excepciones:

• webob.exc.HTTPException (y sus subclases)
• ndb.Rollback

ndb.delete_multi(keys, **ctx_options)

Borra entidades identificadas por la secuencia de claves pasada.

Argumentos

keys

Indica la secuencia de claves

**ctx_options

Opciones de contexto

ndb.delete_multi_async(keys, **ctx_options)

Borra de forma asíncrona entidades identificadas por la secuencia de claves pasada.

Argumentos

keys

Indica la secuencia de claves

**ctx_options

Opciones de contexto

Muestra una lista de objetos Future. El resultado de cada objeto Future será None.

ndb.get_multi(keys, **ctx_options)

Recupera entidades identificadas por la secuencia de claves pasada.

Argumentos

keys

Indica la secuencia de claves

**ctx_options

Opciones de contexto

Muestra una lista. Cada elemento de la lista es una instancia Modelo o None si no se encontró la clave.

ndb.get_multi_async(keys, **ctx_options)

Recupera entidades identificadas en forma asíncrona por la secuencia de claves pasada.

Argumentos

keys

Indica la secuencia de claves

**ctx_options

Opciones de contexto

Muestra una lista de objetos Future. El resultado de cada objeto Future es una instancia Modelo o None si no se encontró la clave.

ndb.in_transaction()

Muestra un valor booleano que indica si una transacción está activa en este momento.

@ndb.non_transactional
@ndb.non_transactional(allow_existing=True)

El decorador asegura que una función se ejecuta por fuera de una transacción.

Argumentos:

allow_existing

Si es True (el valor predeterminado) y si se llama por código a la función decorada en una transacción, la función se ejecutará de forma independiente de la transacción. Si es False y se llama por código a la función decorada en una transacción, se generará una excepción.

ndb.put_multi(entities, **ctx_options)

Almacena una secuencia de instancias Modelo.

Argumentos

entities

Indica una secuencia de instancias Modelo

**ctx_options

Opciones de contexto

Muestra una lista con las claves almacenadas.

ndb.put_multi_async(entities, **ctx_options)

Almacena una secuencia de instancias Modelo de forma asíncrona.

Argumentos

entities

Indica una secuencia de instancias Modelo

**ctx_options

Opciones de contexto

Muestra una lista de objetos Future. El resultado de cada objeto Future será una clave almacenada.

ndb.transaction(callback, **ctx_options)

Ejecuta una devolución de llamada en una transacción.

Argumentos

callback

Función o tasklet a llamar

**ctx_options

Opciones de transacción

Muestra lo que muestre la devolución de llamada. Genera lo que genere la devolución de llamada o, en caso de que no se pueda realizar la transacción, una excepción TransactionFailedError.

Para pasar los argumentos a una función de devolución de llamada, usa un lambda. Por ejemplo:

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))

ndb.transaction_async(callback, **ctx_options)

Ejecuta una devolución de llamada en una transacción en forma asíncrona.

Argumentos

callback

Función o tasklet a llamar

**ctx_options

Opciones de transacción

Muestra un objeto Future. El objeto Future muestra lo que muestre la devolución de llamada, o genera lo mismo que la devolución de llamada, o una excepción TransactionFailedError si no se puede realizar la transacción.

Para pasar los argumentos a una función de devolución de llamada, usa un lambda. Por ejemplo:

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))

@ndb.transactional
@ndb.transactional(**ctx_options)

El decorador hace que una función se ejecute en una transacción de forma automática.

Argumentos:

Este decorador puede tener opciones de transacción.

Opciones de contexto y de transacción

Las opciones de contexto te permiten ejecutar operaciones de almacenamiento de datos específicas con distintas configuraciones. Por ejemplo, quizás desees variar la política de lectura o el plazo de RPC de las solicitudes individuales. Puedes hacerlo si pasas las opciones de contexto a casi cualquier operación. Algunas funciones relacionadas con las transacciones toman las opciones de transacción, que incluyen las opciones adicionales que se basan en un conjunto de opciones de contexto.

Estos son algunos ejemplos que usan opciones de contexto. Para establecer el plazo de RPC a 1 segundo cuando lee una entidad, puedes usar lo siguiente:

key.get(deadline=1)

Para establecer el tiempo de espera de Memcache a 30 segundos cuando escribe una entidad, puedes usar lo siguiente:

ent.put(ndb_memcache_timeout=30)

Para borrar un elemento que se almacenó en caché y forzar una carga nueva, puedes usar lo siguiente:

key.delete(use_datastore=False)

Los argumentos de palabras clave especiales options y config (que tienen significados idénticos por razones históricas) permiten que se especifiquen varias opciones como un objeto de configuración. Puede ser un objeto ndb.ContextOptions o ndb.TransactionOptions (para las funciones y los decoradores transaccionales). Por ejemplo, key.get(options=ndb.ContextOptions(use_cache=True)) es equivalente a key.get(use_cache=True). Las opciones que se establecieron en el objeto de opciones se pueden anular con los parámetros de palabra clave.

Estas opciones de contexto se encuentran disponibles:

Opción	Tipo	Descripción
deadline	float	El plazo de llamada al almacén de datos especificado en segundos. (Según la configuración predeterminada, solo el plazo del controlador de la solicitud interrumpe la llamada).
read_policy	ndb.EVENTUAL_CONSISTENCY	Establécelo en ndb.EVENTUAL_CONSISTENCY si, en lugar de esperar a que Datastore termine de aplicar los cambios a todos los resultados que se muestran, deseas obtener los resultados de forma más rápida, aunque exista el riesgo de que no estén actualizados.
force_writes	bool	Especifica si una solicitud de escritura debe realizarse de forma correcta incluso si la app es de solo lectura. (Esto aplica a los períodos de solo lectura controlados por el usuario).
use_cache	bool	Especifica si se deben almacenar las entidades en la caché en proceso. Esto anula la política de caché en proceso de esta operación.
use_memcache	bool	Especifica si se deben almacenar las entidades en Memcache. Esto anula la política de Memcache para esta operación.
use_datastore	bool	Especifica si se deben almacenar las entidades en Datastore. Esto anula la política de Datastore para esta operación.
memcache_timeout	int	Duración máxima de las entidades en Memcache. Esto anula la política de tiempo de espera de Memcache para esta operación.
max_memcache_items	int	Tamaño del lote máximo para la función de procesamiento por lotes automático de los métodos de Contexto de Memcache. Por ejemplo, con el tamaño predeterminado de max_memcache_items (100), se combinarán hasta 100 operaciones de conjunto de Memcache en una sola operación set_multi.
Para algunas funciones relacionadas con la transacción, están disponibles las siguientes opciones de transacción (junto con las opciones de contexto heredadas que se mencionaron antes):
Opción	Tipo	Descripción
xg	bool	Permite las transacciones entre grupos (XG). Es False de forma predeterminada.
propagation	int	NDB proporciona asistencia limitada para las transacciones dentro de transacciones, que se conocen como “transacciones anidadas”. El parámetro de propagación controla lo que ocurre si tu código intenta iniciar una transacción anidada. La política de propagación para @ndb.transactional se establece de forma predeterminada en ALLOWED. La política de propagación para ndb.transaction() se establece de forma predeterminada en NESTED. La política NESTED no es compatible con NDB, por lo que el código generará una excepción BadRequestError. NDB establece un valor predeterminado no compatible para que, en este caso, los programadores estén al tanto de forma explícita de las limitaciones de las transacciones anidadas. El parámetro de propagación puede ser uno de los siguientes valores: ndb.TransactionOptions.NESTED La política de propagación NESTED confirmaría todos los cambios en las transacciones internas y externas cuando la política externa se confirme. Sin embargo, si se genera una excepción en la transacción interna, todos los cambios se rechazarán, pero se permitirá que la transacción externa se recupere y continúe de manera opcional. La política NESTED no es compatible. Si usas esta política, tu código generará una excepción BadRequestError. ndb.TransactionOptions.MANDATORY Siempre propaga una transacción existente. Si no existe una transacción, se genera una excepción. Si una función que usa esta política genera una excepción, quizás no sea seguro detectar la excepción y confirmar la transacción externa. Es probable que la función haya dejado la transacción externa en un estado incorrecto. ndb.TransactionOptions.ALLOWED Si existe una transacción, propágala. Si una función que usa esta política genera una excepción, quizás no sea seguro detectar la excepción y confirmar la transacción externa. Es probable que la función haya dejado la transacción externa en un estado incorrecto. ndb.TransactionOptions.INDEPENDENT Siempre usa una transacción nueva que “pone en pausa” cualquier transacción existente. Una función que usa esta política no debe mostrar ninguna entidad leída en la transacción nueva, ya que las entidades no son consistentes de forma transaccional con la transacción del emisor.
retries	int	Cuántas veces reintentar de forma automática en caso de fallas de transacción. Cero significa intentar una vez, pero no reintentar.

En algunos casos, se ignoran las opciones debido al almacenamiento en caché. Por ejemplo, si especificas un plazo de RPC para una operación de lectura que se ejecuta desde la caché en contexto, se ignora el plazo. Por otro lado, las opciones no reconocidas provocan que se genere un TypeError.

Las operaciones con distintas opciones se agrupan cuando se aplica el procesamiento por lotes automático. Por ejemplo, si usas put_async() a fin de escribir algunas entidades con deadline = 5 y otras sin especificar un plazo, y todas son aptas para el procesamiento por lotes automático, el procesador por lotes automático realizará dos llamadas RPC separadas, una para el grupo de entidades con deadline = 5 y una para el otro grupo, aunque el plazo de RPC predeterminado también es 5. Esto se aplica incluso cuando la opción especificada es irrelevante para la operación de RPC (por ejemplo, ndb_should_cache).