A classe Model

A classe Model é a superclasse das definições de modelo de dados.

Model é fornecida pelo módulo google.appengine.ext.db.

• Introdução
• Model()
• Métodos da classe:
  • Model.get()
  • Model.get_by_id()
  • Model.get_by_key_name()
  • Model.get_or_insert()
  • Model.all()
  • Model.gql()
  • Model.kind()
  • Model.properties()
• Métodos da instância:
  • key()
  • put()
  • delete()
  • is_saved()
  • parent()
  • parent_key()
  • to_xml()
• Nomes de propriedade não permitidos

Introdução

Um aplicativo define um modelo de dados definindo uma classe que é subclasse de Model. As propriedades do modelo são definidas utilizando atributos de classe e instâncias da classe Property. Por exemplo:

class Story(db.Model):
  title = db.StringProperty()
  body = db.TextProperty()
  created = db.DateTimeProperty(auto_now_add=True)

Um aplicativo cria uma nova entidade de dados instanciando uma subclasse da classe Model. As propriedades de uma entidade podem ser atribuídas utilizando os atributos da instância ou como argumentos de palavra-chave do construtor.

s = Story()
s.title = "The Three Little Pigs"

s = Story(title="The Three Little Pigs")

O nome da subclasse de modelo é usado como nome do tipo de entidade do armazenamento de dados. Os nomes dos atributos são usados como nomes das propriedades correspondentes de uma entidade. Os atributos de instância de Model cujos nomes começam com um caractere sublinhado (_) são ignorados. Portanto, seu aplicativo pode utilizar tais atributos para armazenar dados em uma instância de modelo não armazenada no armazenamento de dados.

A API da classe de modelo e armazenamento de dados impõe diversas restrições sobre nomes de propriedades e atributos de instância de modelo. Para obter uma descrição completa, consulte Nomes de propriedade não permitidos.

Uma entidade de dados pode ter uma entidade pai opcional. Os relacionamentos pai-filho formam grupos de entidades, que são usados para controlar as transações e localização dos dados no armazenamento de dados. Um aplicativo cria um relacionamento pai-filho entre duas entidades, passando a entidade pai ao construtor da entidade filho como o argumento parent. Para obter mais informações sobre pais e ancestrais, consulte Chaves e grupos de entidade.

Cada entidade possui uma chave, um identificador exclusivo que a representa. Uma entidade pode ter um nome de chave opcional, uma string exclusiva dentre as entidades de um tipo determinado. O tipo e o nome da entidade podem ser usados com os métodos Key.from_path() e Model.get_by_key_name() para recuperar a entidade. Para obter mais informações sobre as chaves, consulte Chaves e grupos de entidade.

O método Model.get_or_insert() pode ser utilizado para recuperar uma entidade que talvez não exista, criando-a no armazenamento de dados, se necessário:

keyname = "some_key"
s = Story.get_or_insert(keyname, title="The Three Little Pigs")

Observação: Uma instância de Model não tem uma entidade correspondente no armazenamento de dados até ser colocada (put()) pela primeira vez, seja de forma explícita ou através de Model.get_or_insert().

A classe Model é fornecida pelo pacote google.appengine.ext.db.

Construtor

O construtor da classe Model é definido como é mostrado abaixo:

class Model(parent=None, key_name=None, **kw)

A superclasse para as definições de modelo de dados.

Argumentos:

parent

A instância de Model ou de Key para a entidade que é pai da nova entidade.

key_name

O nome da nova entidade. O nome se torna parte da chave principal. Se None, é usado um ID gerado pelo sistema para a chave.

O valor de key_name não deve começar com um número e não deve ter o formato __*__. Se seu aplicativo utiliza dados enviados pelo usuário como nomes de chave de entidade do armazenamento de dados (como um endereço de e-mail), o aplicativo deve limpar o valor primeiro, por exemplo, colocando como prefixo uma string conhecida como "key:", para atender a estes requisitos.

Um key_name é armazenado como string Unicode, com os valores de str convertidos em texto ASCII.

**kw

Valores iniciais das propriedades da instância, como argumentos de palavra-chave. Cada nome corresponde a um atributo definido na classe Model.

Métodos da classe

A classe Model fornece os seguintes métodos de classe:

Model.get(keys)

Obtém a instância (ou instâncias) do modelo dos objetos Key dados. As chaves devem representar entidades do tipo do modelo. Se uma chave fornecida não for do tipo correto, é emitido um KindError.

Este método é semelhante à função db.get(), com verificação de tipo adicional.

Argumentos:

keys

Um objeto Key ou uma lista de objetos Key. Também pode ser uma versão string ou uma lista de strings de um objeto Key.

Model.get_by_id(ids, parent=None)

Obtém a instância (ou instâncias) do modelo do ID (ou IDs) numérico dado.

Argumentos:

ids

Um ID numérico ou uma lista de IDs numéricos de entidade.

parent

A entidade pai das entidades solicitadas, como instância de Model ou de Key, ou None (o padrão) se as entidades solicitadas não tiverem um pai. Diversas entidades solicitadas por uma chamada devem ter o mesmo pai.

Se ids for uma string representando um nome, o método retorna a instância de modelo do nome ou None, se a entidade não existir. Se ids for uma lista, o método retorna uma lista de instâncias de modelo com valor None quando não existir uma entidade para uma chave correspondente.

Model.get_by_key_name(key_names, parent=None)

Obtém a instância (ou instâncias) do modelo do nome (ou nomes) de chave dado.

Argumentos:

key_names

Um nome de chave ou uma lista de nomes de chave.

parent

A entidade pai das entidades solicitadas, como instância de Model ou de Key, ou None (o padrão) se as entidades solicitadas não tiverem um pai. Diversas entidades solicitadas por uma chamada devem ter o mesmo pai.

Se key_names for uma string representando um nome, o método retorna a instância de modelo do nome ou None, se a entidade não existir. Se key_names for uma lista, o método retorna uma lista de instâncias de modelo com valor None quando não existir uma entidade para uma chave correspondente.

Model.get_or_insert(key_name, **kwds)

Obtém ou cria uma entidade do tipo do modelo com o nome de chave dado, usando uma única transação. A transação assegura que, caso dois usuários tentem obter ou inserir a entidade com o nome dado simultaneamente, os dois usuários terão uma instância de modelo que faz referência à entidade, independente do processo que a criou.

Argumentos:

key_name

O nome da chave da entidade

**kwds

Argumentos de palavra-chave a serem passados à classe de modelo caso não exista uma instância com o nome de chave especificado. O argumento parent é obrigatório, se a entidade desejada tiver pai.

O método retorna uma instância da classe de modelo que representa a entidade solicitada, seja ela já existente ou criada pelo método. Assim como em todas as operações com o armazenamento de dados, este método pode emitir um TransactionFailedError caso a transação não possa ser concluída.

Model.all()

Retorna um objeto Query que representa todas as entidades do tipo correspondente a este modelo. Os métodos do objeto Query podem aplicar filtros e ordens de classificação à consulta antes que ela seja executada. Para obter mais informações, consulte Query.

Model.gql(query_string, *args, **kwds)

Executa uma consulta GQL nas instâncias deste modelo.

Argumentos:

query_string

A parte da consulta GQL após SELECT * FROM model (que é implícita ao utilizar este método de classe).

*args

Vinculações de parâmetro de posição, semelhantes ao construtor de GqlQuery.

**kw

Vinculações de parâmetro de palavra-chave, semelhante ao construtor de GqlQuery.

s = Story.gql("WHERE title = :1", "Little Red Riding Hood")

s = Story.gql("WHERE title = :title", title="Little Red Riding Hood")

O valor retornado é um objeto GqlQuery, que pode ser usado para acessar os resultados.

Model.kind()

Retorna o tipo do modelo, normalmente o nome da subclasse de Model.

Model.properties()

Retorna um dicionário com todas as propriedades definidas para esta classe de modelo.

Métodos da instância

As instâncias de Model têm os métodos abaixo:

key()

Retorna a chave do armazenamento de dados para esta instância de modelo.

Uma instância de modelo não tem uma chave até esta ser inserida (put()) no armazenamento de dados. Chamar key() antes que a instância tenha uma chave emite um NotSavedError.

put()

Armazena a instância de modelo no armazenamento de dados. Se a instância de modelo acabou de ser criada e nunca foi armazenada, este método cria uma nova entidade de dados no armazenamento de dados. Caso contrário, ele atualiza a entidade de dados com os valores da propriedade atual.

O método retorna a chave da entidade armazenada.

delete()

Exclui a instância de modelo do armazenamento de dados. Se a instância nunca foi inserida (put()), não ocorre nada.

is_saved()

Retorna True se a instância de modelo foi colocada (put()) no armazenamento de dados pelo menos uma vez.

Este método apenas verifica se a instância foi armazenada pelo menos uma vez desde que foi criada. Ele não verifica se as propriedades da instância foram atualizadas desde o último put().

dynamic_properties()

Retorna uma lista dos nomes de todas as propriedades dinâmicas definidas para esta instância de modelo. Isto se aplica apenas a instâncias das classes Expando. Para instâncias de modelo não Expando, é retornada uma lista vazia.

parent()

Retorna uma instância de modelo para a entidade pai desta instância ou None, se a instância não tiver pai.

parent_key()

Retorna a chave da entidade pai desta instância ou None, se a instância não tiver pai.

to_xml()

Retorna uma representação XML da instância de modelo.

Os valores de Property conformam-se às especificações de Atom e GData.

Nomes de propriedade não permitidos

O armazenamento de dados e sua API impõem diversas restrições sobre os nomes das propriedades de entidade e atributos de instância de modelo.

O armazenamento de dados reserva todos os nomes de propriedade que começam e terminam com dois caracteres sublinhados (__*__). Uma entidade do armazenamento de dados não pode ter uma propriedade com tal nome.

A API de modelo do Python ignora todos os atributos em Model ou Expando que comecem com um caractere sublinhado (_). Seu aplicativo pode usar estes atributos para associar dados não salvos no armazenamento de dados aos objetos de modelo.

Por fim, a API de modelo do Python utiliza atributos de objeto para definir as propriedades de um modelo. Como padrão, as propriedades da entidade do armazenamento de dados são nomeadas segundo os atributos. Como a classe Model possui diversas propriedades e métodos para outras finalidades, esses atributos não podem ser usados para propriedades na API Python. Por exemplo, não é possível acessar uma propriedade de Model com o atributo key.

Entretanto, uma propriedade pode especificar um nome diferente do atributo para o armazenamento de dados, fornecendo um argumento name ao construtor da propriedade. Isto permite que a entidade do armazenamento de dados tenha um nome de propriedade semelhante a um atributo reservado da classe Model e utilize um nome de atributo diferente na classe.

class MyModel(db.Model):
  obj_key = db.StringProperty(name="key")

Os nomes de atributo abaixo são reservados pela classe Model na API Python: