Funciones de NDB

Functions

En esta página se describe cómo usar los servicios y las APIs antiguos agrupados. Esta API solo se puede ejecutar en los tiempos de ejecución de primera generación del entorno estándar de App Engine. Si vas a actualizar al entorno de ejecución de Python 3 de App Engine, consulta la guía de migración para obtener información sobre las opciones de migración de los servicios agrupados antiguos.

ndb.add_flow_exception(exc)

Especifica que no se debe registrar una excepción, sino que forma parte del flujo normal del programa. Normalmente, al generar una excepción se escribe un mensaje de advertencia en los registros de la aplicación.

Argumentos

exc

Clase de excepción que no se debe registrar.

De forma predeterminada, no se registran las siguientes excepciones:

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

ndb.delete_multi(claves, **ctx_options)

Elimina las entidades identificadas por la secuencia de claves proporcionada.

Argumentos

claves

Secuencia de teclas

**ctx_options

Opciones de contexto

ndb.delete_multi_async(keys, **ctx_options)

Elimina de forma asíncrona las entidades identificadas por la secuencia de claves proporcionada.

Argumentos

claves

Secuencia de teclas

**ctx_options

Opciones de contexto

Devuelve una lista de objetos Future. El resultado de cada futuro será None.

ndb.get_multi(keys, **ctx_options)

Obtiene las entidades identificadas por la secuencia de claves proporcionada.

Argumentos

claves

Secuencia de teclas

**ctx_options

Opciones de contexto

Devuelve una lista. Cada elemento de la lista es una instancia de Model o None si no se ha encontrado la clave.

ndb.get_multi_async(keys, **ctx_options)

Obtiene de forma asíncrona las entidades identificadas por la secuencia de claves proporcionada.

Argumentos

claves

Secuencia de teclas

**ctx_options

Opciones de contexto

Devuelve una lista de objetos Future. El resultado de cada futuro es una instancia de Model o None si no se ha encontrado la clave.

ndb.in_transaction()

Devuelve un valor booleano que indica si hay una transacción activa.

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

Decorador para asegurarse de que una función se ejecuta fuera de una transacción.

Argumentos:

allow_existing

Si True (valor predeterminado) y la función decorada se llama mediante código en una transacción, la función se ejecuta independientemente de la transacción. Si False y si el código llama a la función decorada en una transacción, se genera una excepción.

ndb.put_multi(entities, **ctx_options)

Almacena una secuencia de instancias de Model.

Argumentos

entities

Secuencia de instancias de Model

**ctx_options

Opciones de contexto

Devuelve una lista con las claves almacenadas.

ndb.put_multi_async(entities, **ctx_options)

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

Argumentos

entities

Secuencia de instancias de Model

**ctx_options

Opciones de contexto

Devuelve una lista de objetos Future. El resultado de cada futuro será una clave almacenada.

ndb.transaction(callback, **ctx_options)

Ejecuta una retrollamada en una transacción.

Argumentos

devolución de llamada

Función o tasklet al que se debe llamar

**ctx_options

Opciones de transacción

Devuelve lo que devuelva callback. Genera lo que genere callback o una excepción TransactionFailedError si la transacción falla.

Para transferir argumentos a una función de retrollamada, usa una función lambda. Por ejemplo,

def my_callback(key, inc):
  ...

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

ndb.transaction_async(callback, **ctx_options)

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

Argumentos

devolución de llamada

Función o tasklet al que se debe llamar

**ctx_options

Opciones de transacción

Devuelve un Future. El futuro devuelve lo que devuelva callback o genera lo que genere callback o un TransactionFailedError si la transacción falla.

Para transferir argumentos a una función de retrollamada, usa una función lambda. Por ejemplo,

def my_callback(key, inc):
  ...

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

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

Decorador para que una función se ejecute automáticamente en una transacción.

Argumentos:

Este decorador puede tener opciones de transacción.

Opciones de contexto y opciones de transacción

Las opciones de contexto le permiten ejecutar operaciones de almacén de datos específicas con diferentes configuraciones. Por ejemplo, puede que quieras variar la política de lectura o el plazo de RPC de solicitudes concretas. Para ello, puedes enviar opciones de contexto a casi cualquier operación. Algunas funciones relacionadas con las transacciones usan opciones de transacción, que incluyen opciones adicionales además de un conjunto de opciones de contexto.

Aquí tienes algunos ejemplos de uso de las opciones de contexto. Para definir el plazo de RPC en 1 segundo al leer una entidad, puedes usar lo siguiente:

key.get(deadline=1)

Para definir el tiempo de espera de memcache en 30 segundos al escribir una entidad, puedes usar lo siguiente:

ent.put(ndb_memcache_timeout=30)

Para eliminar un elemento que se ha almacenado en caché y forzar su recarga, puedes usar lo siguiente:

key.delete(use_datastore=False)

Los argumentos de palabras clave especiales options y config (que tienen significados idénticos por motivos históricos) permiten especificar varias opciones como objeto Configuration. Puede ser un objeto ndb.ContextOptions o, en el caso de las funciones y el decorador transaccionales, un objeto ndb.TransactionOptions. Por ejemplo: key.get(options=ndb.ContextOptions(use_cache=True)) es equivalente a key.get(use_cache=True). Los parámetros de palabras clave pueden anular las opciones definidas en un objeto de opciones.

Estas son las opciones contextuales disponibles:

Opción	Tipo	Descripción
deadline	float	Fecha límite de llamada para el almacén de datos, especificada como un número de segundos. De forma predeterminada, la llamada solo se interrumpe cuando se alcanza el plazo del controlador de solicitudes.
read_policy	ndb.EVENTUAL_CONSISTENCY	Defina este valor en ndb.EVENTUAL_CONSISTENCY si, en lugar de esperar a que Datastore termine de aplicar los cambios a todos los resultados devueltos, quiere obtener resultados posiblemente no actualizados más rápido.
force_writes	bool	Especifica si una solicitud de escritura debe completarse correctamente aunque la aplicación sea de solo lectura. Esto solo se aplica a los periodos de solo lectura controlados por el usuario.
use_cache	bool	Especifica si se deben almacenar entidades en la caché en proceso. Anula la política de caché en proceso de esta operación.
use_memcache	bool	Especifica si se deben almacenar entidades en memcache. Anula la política de memcache para esta operación.
use_datastore	bool	Especifica si se deben almacenar entidades en Datastore. Anula la política de Datastore para esta operación.
memcache_timeout	int	Tiempo de vida máximo de las entidades en Memcache. Anula la política de tiempo de espera de Memcache para esta operación.
max_memcache_items	int	Tamaño máximo de lote para la función de creación automática de lotes de los métodos de caché de memoria Context. Por ejemplo, con el tamaño predeterminado de max_memcache_items (100), se combinarán hasta 100 operaciones de definición de memcache en una sola operación set_multi.
En algunas funciones relacionadas con las transacciones, se pueden usar las siguientes opciones de transacción (además de las opciones de contexto heredadas que se indican más arriba):
Opción	Tipo	Descripción
xg	bool	Permitir transacciones entre grupos (XG). False de forma predeterminada.
propagation	int	NDB ofrece asistencia limitada para las transacciones dentro de las 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 de @ndb.transactional tiene el valor predeterminado ALLOWED. La política de propagación de ndb.transaction() tiene el valor predeterminado NESTED. La política de NESTED no es compatible con NDB, por lo que tu código generará una excepción BadRequestError. NDB asigna un valor predeterminado no admitido, en este caso, para que los programadores sean conscientes de las limitaciones de las transacciones anidadas. El parámetro de propagación puede tener uno de los siguientes valores: ndb.TransactionOptions.NESTED La política de propagación NESTED confirmaría todos los cambios de las transacciones externas e internas a la vez cuando se confirmara la política externa. Sin embargo, si se produce una excepción en la transacción interna, se descartarán todos los cambios, pero se permitirá que la transacción externa se recupere y continúe de forma opcional. No se admite la política NESTED. Si usas esta política, tu código generará una excepción BadRequestError. ndb.TransactionOptions.MANDATORY Propaga siempre una transacción ya iniciada; lanza una excepción si no hay ninguna transacción. Si una función que usa esta política genera una excepción, probablemente no sea seguro capturar la excepción y confirmar la transacción externa, ya que la función puede haber dejado la transacción externa en un estado incorrecto. ndb.TransactionOptions.ALLOWED Si hay una transacción, propágala. Si una función que usa esta política genera una excepción, probablemente no sea seguro capturar la excepción y confirmar la transacción externa, ya que la función puede haber dejado la transacción externa en un estado incorrecto. ndb.TransactionOptions.INDEPENDENT Siempre se usa una transacción nueva y se "pausan" las transacciones que ya haya. Una función que use esta política no debe devolver ninguna entidad leída en la nueva transacción, ya que las entidades no son coherentes transaccionalmente con la transacción de la persona que llama.
retries	int	Número de veces que se debe volver a intentar automáticamente en caso de que se produzcan errores en las transacciones. Cero significa que se intenta una vez, pero no se vuelve a intentar.

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

Las operaciones con diferentes opciones se agrupan cuando se aplica el procesamiento por lotes automático. Por ejemplo, si usas put_async() para escribir algunas entidades con deadline = 5 y otras sin especificar una fecha límite, y todas cumplen los requisitos para el procesamiento automático por lotes, el procesador automático por lotes hará dos llamadas RPC independientes: una para el grupo de entidades con deadline = 5 y otra para el otro grupo, aunque la fecha límite de la llamada RPC predeterminada también sea 5. Esto se aplica aunque la opción especificada no sea pertinente para la operación RPC (por ejemplo, ndb_should_cache).