Módulo google.appengine.ext.ndb.key

Resumo

A classe Key e os utilitários associados.

Uma chave encapsula as informações a seguir, que, juntas, designam com exclusividade uma entidade (possível) no armazenamento de dados do App Engine:

  • um ID do aplicativo (uma string)

  • um namespace (uma string)

  • uma lista de um ou mais pares (kind, id) em que kind é uma string e id é uma string ou um inteiro.

O ID do aplicativo precisa sempre fazer parte da chave, mas como a maioria dos aplicativos só pode acessar as próprias entidades, o padrão é o ID do aplicativo atual e você raramente precisa se preocupar com isso. Ele não precisa estar vazio.

O namespace designa uma partição de nível superior do espaço de chave para um determinado aplicativo. Caso jamais tenha ouvido falar de namespaces, você pode ignorar com segurança esse recurso.

A maior parte da ação está nos pares (kind, id). Uma chave precisa ter pelo menos um par (kind, id). O último par (kind, id) dá o tipo e o id da entidade a que a chave se refere. Os outros apenas especificam uma "chave pai".

O tipo é uma string que dá o nome da classe de modelo usada para representar a entidade. Em bancos de dados mais tradicionais, ele seria o nome da tabela. Classe de modelo é uma classe Python derivada de ndb.Model. Consulte a documentação de ndb/model.py. Somente o próprio nome da classe é usado como o tipo. Isso significa que todas as classes de modelo precisam ser nomeadas com exclusividade em um aplicativo. Substitua-o por classe.

Código é uma string ou um inteiro. Quando o código é uma string, o aplicativo está no controle de como ele atribui códigos: por exemplo, caso você possa usar um endereço de e-mail como o código das entidades Account.

Para usar códigos inteiros, você precisa permitir que o armazenamento de dados escolha um código exclusivo para uma entidade quando inserido pela primeira vez no armazenamento de dados. Defina o código como None para representar a chave de uma entidade que ainda não foi inserida no armazenamento de dados. A chave final (inclusive o código atribuído) será retornada depois que a entidade for inserida com êxito no armazenamento de dados.

Uma chave para que o código do último par (kind, id) seja definido como None é chamado de chave incompleta. Essas chaves só podem ser usadas para inserir entidades no armazenamento de dados.

Uma chave com exatamente um par (kind, id) é chamada de chave de nível superior ou chave raiz. As chaves de nível superior também são usadas como grupos de entidades, que desempenham um papel no gerenciamento de transações.

Caso haja mais de um par (kind, id), todos, exceto o último par, representam o "caminho ancestral", também conhecido como a chave da "entidade pai".

Outras restrições

  • Os tipos e os códigos de string não precisam estar vazios e ter, no máximo, 500 bytes (após a codificação UTF-8 caso fornecida como objetos Unicode Python). OBSERVAÇÃO: isso é definido como uma constante de nível de módulo _MAX_KEYPART_BYTES.

  • Os códigos inteiros precisam ser pelo menos 1 e menores que 2**63.

Para mais informações sobre namespaces, consulte http://code.google.com/appengine/docs/python/multitenancy/overview.html. O namespace assume como padrão o "namespace padrão" selecionado pelo administrador de namespace. Para selecionar explicitamente o namespace vazio, passe o namespace=’‘.

Conteúdo

class google.appengine.ext.ndb.key.Keysource

Bases: object

Uma chave de armazenamento de dados imutável.

Para flexibilidade e praticidade, várias assinaturas de construtor são aceitas.

A maneira principal de criar uma chave é usar argumentos posicionais: - Key(kind1, id1, kind2, id2, …).

Esta é uma forma abreviada para qualquer uma destas duas formas mais longas: - Key(pairs=[(kind1, id1), (kind2, id2), …]) - Key(flat=[kind1, id1, kind2, id2, …])

Qualquer uma das formas de construtor acima pode passar outra chave usando parent=<key>. Os pares (kind, id) da chave pai são inseridos antes dos pares (kind, id) serem passados explicitamente.

Você também pode criar uma chave com base em uma string codificada "segura para URL": - Key(urlsafe=<string>)

Para fins internos, existem os seguintes construtores: - Key(reference=<reference>): passa um objeto Reference de nível inferior. - Key(serialized=<string>): passa um Reference de nível inferior serializado. - Key(<dict>): para liberação, o mesmo de Key(**<dict>).

A string "url-safe" é realmente um Reference serializado codificado em base64 seguro para Web, mas é melhor pensar nela apenas como uma string exclusiva opaca.

Outros argumentos de palavra-chave do construtor: - app=<string>: especifique o ID do aplicativo. - namespace=<string>: especifique o namespace.

Se um Reference for passado (usando um de referência, serializado ou seguro para URL), os argumentos e as palavras-chave de namespace precisarão corresponder ao que já está presente no Reference (depois da decodificação, se necessário). A palavra-chave pai não pode ser combinada com um Reference de forma alguma.

As chaves são imutáveis, o que significa que um objeto Key não poderá ser modificado depois de ter sido criado. Isso é aplicado pela implementação, assim como o Python permite.

Para acessar o conteúdo de uma chave, os seguintes métodos e operações são aceitos:

  • repr(key), str(key): retornam uma representação de string semelhante à forma de construtor mais curta, omitindo o app e o namespace, a menos que eles sejam diferentes do valor padrão.

  • key1 == key2, key1 != key2: comparação de igualdade entre Keys.

  • hash(key): um valor de hash suficiente para armazenar Keys em um dict.

  • key.pairs(): uma tupla de pares (kind, id).

  • key.flat(): uma tupla de valores kind e id simples, ou seja (kind1, id1, kind2, id2…).

  • key.app(): o ID do aplicativo.

  • key.id(): o código da string ou do inteiro no último par (kind, id) ou None, caso a chave esteja incompleta.

  • key.string_id(): o código da string no último par (kind, id) ou None, caso a chave tenha um código do inteiro ou esteja incompleta.

  • key.integer_id(): o código do inteiro no último par (kind, id) ou None, caso a chave tenha um código da string ou esteja incompleta.

  • key.namespace(): o namespace.

  • key.kind(): um atalho para key.pairs()[-1][0].

  • key.parent(): um Key criado com base em todos, menos os últimos pares (kind, id).

  • key.urlsafe(): um Reference serializado codificado em base64 seguro para Web.

  • key.serialized(): um Reference serializado.

  • key.reference(): um objeto Reference. O autor da chamada promete não mudá-lo.

As chaves também são compatíveis com a interação com o armazenamento de dados. Esses métodos são os únicos que interagem em qualquer tipo de atividade de E/S. Para objetos Future, consulte o documento de ndb/tasklets.py.

  • key.get(): retorne a entidade de Key.

  • key.get_async(): retorne um Future com o resultado eventual que será a entidade de Key.

  • key.delete(): exclua a entidade de Key.

  • key.delete_async(): exclua de maneira assíncrona a entidade de Key.

As chaves podem ser liberadas.

É melhor evitar Key subclasse. Seria difícil acertá-lo.

app()source

Retorne o ID do aplicativo.

delete(**ctx_options)source

Exclua de maneira síncrona a entidade para essa Key.

Trata-se de um ambiente autônomo caso não haja uma entidade assim.

delete_async(**ctx_options)source

Programe a exclusão da entidade para essa Key.

Isso retorna um Future com um resultado disponibilizado assim que a exclusão é concluída. Se essa entidade não existir, um Future continuará sendo retornado. Em todos os casos, o resultado de Future é None (ou seja, não há como saber se a entidade existiu ou não).

flat()source

Retorne uma tupla de valores kind e id alternados.

classmethod from_old_key(old_key)source
get(**ctx_options)source

Consiga de maneira síncrona a entidade dessa Key.

Retorne None, caso não haja essa entidade.

get_async(**ctx_options)source

Retorne um Future com um resultado que seja a entidade de Key.

Se essa entidade não existir, um Future continuará sendo retornado, e o resultado de retorno eventual Future será None.

id()source

Retorne o código de string ou inteiro no último par (kind, id), caso haja.

Retorna

Um código de string ou inteiro ou None, caso a chave esteja incompleta.

integer_id()source

Retorne o código do inteiro no último par (kind, id), caso haja.

Retorna

Um código de inteiro ou None, caso a chave tenha um código de string ou esteja incompleta.

kind()source

Retorne o tipo da entidade referenciada.

Este é o tipo do último par (kind, id).

namespace()source

Retorne o namespace.

pairs()source

Retorne uma tupla de pares (kind, id).

parent()source

Retorne um Key criado com base em todos, menos os últimos pares (kind, id).

Se houver apenas um par (kind, id), retorne None.

reference()source

Retorne o objeto Reference deste Key.

Trata-se de uma instância entity_pb.Reference: uma classe de buffer de protocolo usada pela API de nível inferior para o armazenamento de dados.

OBSERVAÇÃO: o autor da chamada não precisa modificar o valor de retorno.

root()source

Retorne a chave raiz. Trata-se do próprio pai ou superior.

serialized()source

Retorne o objeto Reference serializado deste Key.

string_id()source

Retorne o código da string no último par (kind, id), caso haja.

Retorna

Um código de string ou None, caso a chave tenha um código de inteiro ou esteja incompleta.

to_old_key()source
urlsafe()source

Retorne uma codificação de string segura para URL que codifica Reference de Key.

Essa string é compatível com outras APIs e linguagens e com as strings usadas para representar Keys no GQL e no Admin Console do App Engine.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Ambiente padrão do App Engine para Python 2