Tipos e classes Property

O armazenamento de dados do Google App Engine suporta um conjunto fixo de tipos de valores para as propriedades nas entidades de dados. As classes Property podem definir novos tipos, que são convertidos e reconvertidos em tipos de valores básicos. Os tipos de valores podem ser usados diretamente com as propriedades dinâmicas Expando e modelos de propriedade de agregado ListProperty.

A tabela abaixo descreve as classes Property cujos valores correspondem diretamente aos tipos de dados básicos. Qualquer um desses tipos de valores pode ser usado em um tipo de propriedade dinâmica Expando ou agregado ListProperty.

Tipos de valores do armazenamento de dados

Os valores de propriedade das entidades do armazenamento de dados podem pertencer a um dos tipos abaixo. Veja acima uma lista de classes Property correspondentes, para serem usadas com definições Model.

Fora os tipos padrão de Python e users.User, todas as classes descritas nesta seção são fornecidas pelo módulo google.appengine.ext.db.

str ou unicode

Um valor de string curta, abaixo de 500 bytes de comprimento.

Supõe-se que um valor str é texto codificado com o codec ascii, sendo convertido para um valor unicode antes de ser armazenado. O valor é retornado pelo armazenamento de dados como unicode. Para strings curtas utilizando outros codecs, use um valor unicode.

As strings curtas são indexadas pelo armazenamento de dados e podem ser usadas em filtros e ordens de classificação. Para strings de texto mais longas que 500 bytes (não indexadas), use uma instância Text. Para strings de bytes não codificadas mais longas que 500 bytes (não indexadas), use uma instância Blob.

Propriedade de modelo: StringProperty

bool

Um valor booleano, True ou False.

Propriedade de modelo: BooleanProperty

int ou long

Um valor inteiro.

Os valores int Python são convertidos em valores long Python antes do armazenamento. Um valor armazenado como int será retornado como long.

Propriedade de modelo: IntegerProperty

float

Um valor com ponto flutuante.

Propriedade de modelo: FloatProperty

datetime.datetime

Uma data e hora. Consulte a documentação do módulo datetime.

Se o valor datetime tiver um atributo tzinfo, ele será convertido no fuso horário UTC para armazenamento. Os valores são retornados do armazenamento de dados como UTC, com tzinfo igual a None. Um aplicativo que necessite de valores de data e hora em um fuso horário específico deve definir tzinfo corretamente ao atualizar o valor e converter os valores para o fuso horário ao acessar o valor.

Algumas bibliotecas utilizam a variável de ambiente TZ para controlar o fuso horário aplicado aos valores de data e hora. O Google App Engine define esta variável de ambiente para "UTC". A alteração desta variável em um aplicativo não altera o comportamento de alguma funções datetime, pois as alterações nas variáveis de ambiente não são visíveis fora do código Python.

Se você apenas converter e reconverter os valores de um fuso horário específico, implemente um datetime.tzinfo personalizado para converter os valores do armazenamento de dados:

class Pacific_tzinfo(datetime_module.tzinfo):
 """Implementation of the Pacific timezone."""
 def utcoffset(self, dt):
   return datetime_module.timedelta(hours=-8) + self.dst(dt)

 def _FirstSunday(self, dt):
   """First Sunday on or after dt."""
   return dt + datetime_module.timedelta(days=(6-dt.weekday()))

 def dst(self, dt):
   # 2 am on the second Sunday in March
   dst_start = self._FirstSunday(datetime_module.datetime(dt.year, 3, 8, 2))
   # 1 am on the first Sunday in November
   dst_end = self._FirstSunday(datetime_module.datetime(dt.year, 11, 1, 1))

   if dst_start <= dt.replace(tzinfo=None) < dst_end:
     return datetime_module.timedelta(hours=1)
   else:
     return datetime_module.timedelta(hours=0)

 def tzname(self, dt):
   if self.dst(dt) == datetime_module.timedelta(hours=0):
     return "PST"
   else:
     return "PDT"

pacific_time = utc_time.astimezone(Pacific_tzinfo())

Consulte a documentação do módulo datetime (incluindo datetime.tzinfo). Veja também o módulo pytz de terceiros. Entretanto, é bom observar que a distribuição de pytz contém diversos arquivos.

A classe de propriedade de modelo DateTimeProperty inclui recursos como a capacidade de usar automaticamente a data e a hora em que uma instância de modelo foi armazenada. Estes são recursos do modelo e não estão disponíveis no valor puro do armazenamento de dados (como em uma propriedade dinâmica Expando).

Propriedades de modelo: DateTimeProperty, DateProperty, TimeProperty

list

Uma lista de valores, cada um sendo um dos tipos de dados suportados. Consulte Entidades e modelos: Listas.

Uma list usada como o valor de uma propriedade dinâmica Expando não pode ser vazia. Isto se deve ao modo como os valores das listas são armazenados. Quando uma propriedade de lista não contém valores, ela não tem representação no armazenamento de dados. Você pode usar uma propriedade estática e a classe ListProperty para representar um valor de lista vazia para uma propriedade.

Propriedade de modelo: ListProperty

db.Key

A chave de outra entidade do armazenamento de dados.

m = Employee(name="Susan", key_name="susan5")
m.put()
e = Employee(name="Bob", manager=m.key())
e.put()

m_key = db.Key.from_path("Employee", "susan5")
e = Employee(name="Jennifer", manager=m_key)

Propriedades de modelo: ReferenceProperty, SelfReferenceProperty

users.User

Um usuário com uma conta do Google.

Um valor User no armazenamento de dados não é atualizado se o usuário alterar o seu endereço de e-mail. Isso pode ser corrigido em uma versão futura. Até lá, é possível usar o user_id() do valor User como o identificador exclusivo estável do usuário.

Propriedade de modelo: UserProperty

class Blob(arg=None)

Dados binários, como uma string de bytes. Esta é uma subclasse do tipo str integrado.

As propriedades Blob não são indexadas e não podem ser usadas em filtros ou ordens de classificação.

Blob é para dados binários, como imagens. Ela assume um valor str, mas este valor é armazenado como string de bytes e não é codificado como texto. Utilize uma instância de Text para dados de texto grandes.

Propriedade de modelo: BlobProperty

class MyModel(db.Model):
  blob = db.BlobProperty()

m = MyModel()
m.blob = db.Blob(open("image.png").read())

Em XML, os blobs são codificados com base64 independentemente de terem ou não dados binários.

class ByteString(arg)

Um valor de blob curto (uma "string de bytes"), abaixo de 500 bytes de comprimento. ByteString é uma subclasse de str e assume um valor str não codificado como um argumento para o seu construtor.

As ByteStrings são indexadas pelo armazenamento de dados e podem ser usadas em filtros e ordens de classificação. Para strings de bytes mais longas que 500 bytes (não indexadas), use uma instância Blob. Para dados de texto codificados, use srt (curto, indexado) ou Text (longo, não indexado).

Propriedade de modelo: ByteStringProperty

class Text(arg=None, encoding=None)

Uma string longa. Esta é uma subclasse do tipo unicode integrado.

arg um valor unicode ou str. Se arg for str, ele é analisado e a codificação é especificada por encoding, ou ascii se não for especificada uma codificação. Consulte a lista de codificações padrão para obter os possíveis valores de encoding.

Diferente de uma propriedade de entidade cujo valor é simplesmente str ou unicode, uma propriedade Text pode ter mais de 500 bytes de comprimento. Entretanto, as propriedades Text não são indexadas e não podem ser usadas em filtros ou ordens de classificação.

Propriedade de modelo: TextProperty

class MyModel(db.Model):
  text = db.TextProperty()

m = MyModel()
m.text = db.Text(u"kittens")

m.text = db.Text("kittens", encoding="latin-1")

class Category(tag)

Uma categoria ou "tag". Esta é uma subclasse do tipo unicode integrado.

Propriedade de modelo: CategoryProperty

class MyModel(db.Model):
  category = db.CategoryProperty()

m = MyModel()
m.category = db.Category("kittens")

Em XML, este é um elemento category de Atom. Consulte a especificação do Atom.

class Email(email)

Um endereço de e-mail. Esta é uma subclasse do tipo unicode integrado.

Os endereços de e-mail não são validados pela classe de propriedade nem pela classe de valor. Elas apenas armazenam o valor.

Propriedade de modelo: EmailProperty

class MyModel(db.Model):
  email_address = db.EmailProperty()

m = MyModel()
m.email_address = db.Email("larry@example.com")

Em XML, este é um elemento gd:email. Consulte a referência da API do Google Data.

class GeoPt(lat, lon=None)

Um ponto geográfico representado por coordenadas de latitude e longitude com ponto flutuante.

Propriedade de modelo: GeoPtProperty

Em XML, este é um elemento georss:point. Consulte georss.org.

class IM(protocol, address=None)

Um apelido de mensagem instantânea.

protocol é o URL fixo do serviço de mensagens instantâneas. Alguns valores possíveis:

Protocol	Descrição
sip	SIP/SIMPLE
xmpp	XMPP/Jabber
http://aim.com/	AIM
http://icq.com/	ICQ
http://talk.google.com/	Google Talk
http://messenger.msn.com/	MSN Messenger
http://messenger.yahoo.com/	Yahoo Messenger
http://sametime.com/	Lotus Sametime
http://gadu-gadu.pl/	Gadu-Gadu
unknown	Desconhecido ou não especificado

address é o endereço do manipulador.

Propriedade de modelo: IMProperty

class MyModel(db.Model):
  im = db.IMProperty()

m = MyModel()
m.im = db.IM("http://example.com/", "Larry97")

Em XML, este é um elemento gd:im. Consulte a referência da API do Google Data.

class Link(link)

Um URL completo. Esta é uma subclasse do tipo unicode integrado.

Propriedade de modelo: LinkProperty

class MyModel(db.Model):
  link = db.LinkProperty()

m = MyModel()
m.link = db.Link("http://www.google.com/")

Em XML, este é um elemento link de Atom. Consulte a especificação do Atom.

class PhoneNumber(phone)

Um número de telefone legível. Esta é uma subclasse do tipo unicode integrado.

Propriedade de modelo: PhoneNumberProperty

class MyModel(db.Model):
  phone = db.PhoneNumberProperty()

m = MyModel()
m.phone = db.PhoneNumber("1 (206) 555-1212")

Em XML, este é um elemento gd.phoneNumber. Consulte a referência da API do Google Data.

class PostalAddress(address)

Um endereço postal. Esta é uma subclasse do tipo unicode integrado.

Propriedade de modelo: PostalAddressProperty

class MyModel(db.Model):
  address = db.PostalAddressProperty()

m = MyModel()
m.address = db.PostalAddress("1600 Ampitheater Pkwy., Mountain View, CA")

Em XML, este é um elemento gd:postalAddress. Consulte a referência da API do Google Data.

class Rating(rating)

Uma classificação fornecida pelo usuário para algum conteúdo, como um inteiro entre 0 e 100. Esta é uma subclasse do tipo long integrado. A classe valida que o valor é um inteiro entre 0 e 100 e emite BadValueError se o valor não for válido.

Propriedade de modelo: RatingProperty

class MyModel(db.Model):
  rating = db.RatingProperty()

m = MyModel()
m.rating = db.Rating(97)

Em XML, este é um elemento gd:rating. Consulte a referência da API do Google Data.

Classe Property

Todas as classes de propriedade de modelo fornecidas por google.appengine.ext.db são subclasses da classe base Property e suportam todos os argumentos do construtor base. Consulte a documentação da classe base para obter informações sobre esses argumentos.

O pacote google.appengine.ext.db fornece as classes de propriedade de modelo abaixo:

class BlobProperty(...)

Uma propriedade de dados binários.

Os dados de Blob são uma string de bytes. Para dados de texto que podem envolver codificação, utilize TextProperty.

Tipo de valor: Blob

class BooleanProperty(...)

Uma propriedade booleana.

Tipo de valor: bool

class ByteStringProperty(verbose_name=None, ...)

Uma propriedade de blob curto (uma "string de bytes"). Assume um valor ByteString de até 500 bytes.

Os valores da propriedade ByteStringProperty são indexados e podem ser usados em filtros e ordens de classificação.

Como a StringProperty, exceto pelo valor que não está codificado de maneira alguma. Os bytes são armazenados literalmente.

Tipo de valor: ByteString

class CategoryProperty(...)

Uma categoria ou "tag", uma palavra ou frase descritiva.

Tipo de valor: Category

class DateProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)

Uma propriedade de data, sem horário. Para obter mais informações, consulte DateTimeProperty.

Tipo de valor: datetime.date. Este é convertido internamente para datetime.datetime.

class DateTimeProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)

Uma propriedade de data e hora.

Se auto_now for True, o valor da propriedade é definido para a hora atual sempre que a instância de modelo for armazenada no armazenamento de dados, substituindo o valor anterior da propriedade. Isto é útil para rastrear data e hora da "última modificação" de uma instância de modelo.

Se auto_now_add for True, o valor da propriedade é definido para a hora atual na primeira vez em que a instância de modelo for armazenada no armazenamento de dados, a menos que a propriedade já tenha recebido um valor. Isto é útil para rastrear data e hora da "criação" de uma instância de modelo.

Os valores de data e hora são armazenados e retornados utilizando os fusos horários UTC. Leia uma discussão sobre como gerenciar fusos horários em datetime.datetime.

Tipo de valor: datetime.datetime

class EmailProperty(...)

Um endereço de e-mail.

Os endereços de e-mail não são validados pela classe de propriedade nem pela classe de valor. Elas apenas armazenam o valor.

Tipo de valor: Email

class FloatProperty(...)

Uma propriedade de número com ponto flutuante.

Tipo de valor: float

class GeoPtProperty(...)

Um ponto geográfico representado por coordenadas de latitude e longitude com ponto flutuante.

Tipo de valor: GeoPt

class IMProperty(...)

Um apelido de mensagem instantânea.

Tipo de valor: IM

class IntegerProperty(...)

Uma propriedade de inteiro.

Os valores int Python são convertidos em valores long Python antes do armazenamento. Um valor armazenado como int será retornado como long.

Tipo de valor: int ou long

class LinkProperty(...)

Um URL completo.

Tipo de valor: Link

class ListProperty(item_type, verbose_name=None, default=None, ...)

Uma lista de valores do tipo dado como item_type.

Em uma consulta, a comparação de uma propriedade de lista com um valor executa o teste nos membros da lista. list_property = value testa se o valor aparece em qualquer parte da lista, list_property < value testa se algum dos membros da lista é menor que o valor dado e assim por diante.

Uma consulta não pode comparar dois valores de lista. Não há uma maneira de testar a igualdade de duas listas sem testar a presença de cada elemento separadamente.

item_type é o tipo dos itens da lista, como um tipo Python ou classe. Todos os itens do valor da lista devem ser do tipo dado. item_type deve ser um dos tipos de valor do armazenamento de dados e não pode ser list. Consulte Tipos de valores do armazenamento de dados acima.

O valor de uma propriedade estática ListProperty não pode ser None. Entretanto, ele pode ser uma lista vazia.

Dica: Como os tipos agregados de ListProperty não utilizam as classes Property, recursos da classe Property como valores automáticos e validação não são aplicados automaticamente aos membros do valor da lista. Se desejar validar um valor membro utilizando uma classe Property, você pode instanciar a classe e chamar seu método validate() para o valor.

default é o valor padrão da propriedade de lista. Se for None, o padrão é uma lista vazia. Uma propriedade de lista pode definir um validador personalizado para proibir a lista vazia.

Consulte Entidades e modelos para obter mais informações sobre ListProperty e valores de lista.

Tipo de valor: um list Python de zero ou mais valores, onde cada valor é do tipo configurado

class PhoneNumberProperty(...)

Um número de telefone legível.

Tipo de valor: PhoneNumber

class PostalAddressProperty(...)

Um endereço postal.

Tipo de valor: PostalAddress

class RatingProperty()

Uma classificação fornecida pelo usuário para algum conteúdo, como um inteiro entre 0 e 100.

Tipo de valor: Rating

class ReferenceProperty(reference_class=None, verbose_name=None, collection_name=None, ...)

Uma referência a outra instância de modelo. Por exemplo, uma referência pode indicar um relacionamento de vários-para-um entre o modelo com a propriedade e o modelo ao qual a propriedade faz referência.

reference_class é a classe de modelo da instância de modelo da referência. Se especificada, somente instâncias de modelo da classe poderão ser atribuídas a esta propriedade. Se for None, qualquer instância de modelo pode ser o valor desta propriedade.

collection_name é o nome da propriedade fornecida à classe de modelo da referência cujo valor é uma consulta (Query) de todas as entidades que fazem referência à entidade. Se não for definido nenhum collection_name, é utilizado modelname_set (com o nome do modelo em minúsculas e "_set" adicionado).

Observação: collection_name deve ser definido caso haja diversas propriedades dentro do mesmo modelo fazendo referência à mesma classe de modelo. Caso contrário, é emitido um DuplicatePropertyError quando os nomes padrão são gerados.

ReferenceProperty faz e desfaz automaticamente referência às instâncias de modelo como valores de propriedade. Uma instância de modelo pode ser atribuída diretamente a ReferenceProperty e sua chave será usada. O valor de ReferenceProperty pode ser usado como se fosse uma instância de modelo. A entidade do armazenamento de dados será obtida e a instância será criada quando for usada dessa maneira pela primeira vez. Propriedades de referência não utilizadas não fazem consultas por dados desnecessários.

class Author(db.Model):
  name = db.StringProperty()

class Story(db.Model):
  author = db.ReferenceProperty(Author)

story = db.get(story_key)
author_name = story.author.name

Semelhante ao valor de Key, é possível que o de uma propriedade de referência faça referência a uma entidade de dados inexistente. Se uma entidade de referência for excluída do armazenamento de dados, as referências à entidade não serão atualizadas. Um aplicativo pode utilizar db.get() de forma explícita para obter o valor de uma ReferenceProperty (que é uma chave) para testar se a entidade da referência existe.

A exclusão de uma entidade não exclui as entidades às quais ReferenceProperty faz referência.

Veja também esta introdução a propriedades de referência.

Tipo de valor: db.Key (veja acima)

class SelfReferenceProperty(verbose_name=None, collection_name=None, ...)

Uma referência a outra instância de modelo da mesma classe. Consulte ReferenceProperty.

Tipo de valor: db.Key (veja acima)

class StringListProperty(verbose_name=None, default=None, ...)

Semelhante a uma ListProperty de valores Python str ou unicode (basestring). Consulte ListProperty.

Tipo de valor: uma list Python de valores str ou unicode

class StringProperty(verbose_name=None, multiline=False, ...)

Uma propriedade de string curta. Assume um valor Python str ou unicode (basestring) de até 500 bytes.

Os valores da propriedade StringProperty são indexados e podem ser usados em filtros e ordens de classificação.

Se multiline for False, o valor não poderá incluir caracteres de entrelinha. A biblioteca djangoforms utiliza isto para impor uma diferença entre campos de texto e campos textarea no modelo de dados, e outros podem usá-lo com finalidade semelhante.

Tipo de valor: str ou unicode

class TextProperty()

Uma string longa.

Diferente de StringProperty, um valor de TextProperty pode ter mais de 500 bytes de comprimento. Entretanto, os valores de TextProperty não são indexados e não podem ser usados em filtros ou ordens de classificação.

Os valores de TextProperty armazenam texto com codificação de texto. Para dados binários, utilize BlobProperty.

Tipo de valor: Text

class TimeProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)

Uma propriedade de tempo sem uma data. Assume um valor datetime.time da biblioteca padrão de Python. Para obter mais informações, consulte DateTimeProperty.

Tipo de valor: datetime.time. Este é convertido internamente para datetime.datetime.

class UserProperty(verbose_name=None, auto_current_user=False, auto_current_user_add=False, ...)

Um usuário com uma conta do Google.

Se auto_current_user for True, o valor da propriedade será definido para o usuário conectado no momento sempre que a instância de modelo for armazenada no armazenamento de dados, substituindo o valor anterior da propriedade. Isso é útil para rastrear qual usuário modifica uma instância de modelo.

Se auto_current_user_add for True, o valor da propriedade será definido para o usuário conectado no momento na primeira vez em que a instância de modelo for armazenada no armazenamento de dados, a menos que a propriedade já tenha recebido um valor. Isso é útil para rastrear qual usuário cria uma instância de modelo, que pode não ser o mesmo usuário que a modificará posteriormente.

UserProperty não aceita um valor padrão. Os valores padrão são definidos na primeira importação da classe de modelo. O cache de importação pode não ser o usuário conectado no momento.

Tipo de valor: users.User (veja acima)