Tipos e classes de propriedade

Observação: é altamente recomendável a desenvolvedores que criam novos aplicativos usar a biblioteca de cliente NDB, porque ela oferece diversos benefícios em comparação com esta biblioteca de cliente, como armazenamento em cache automático de entidades por meio da API Memcache. Se você estiver usando a antiga biblioteca de cliente DB, leia o Guia de migração de DB para NDB.

O App Engine Datastore aceita 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 em/de tipos de valor subjacentes, e os tipos de valor podem ser usados diretamente com propriedades dinâmicas Expando e modelos de propriedade agregada ListProperty.

A tabela abaixo descreve as classes Property com valores diretamente correspondentes aos tipos de dados subjacentes. Qualquer um desses tipos de valor pode ser usado em uma propriedade dinâmica Expando ou um tipo agregado ListProperty.

Classe Property	Tipo de valor	Ordem de classificação
IntegerProperty	int long (64 bits)	Numérico
FloatProperty	float	Numérico
BooleanProperty	bool	False < True
StringProperty	str unicode	Unicode (str é tratado como ASCII)
TextProperty	db.Text	Nenhum
ByteStringProperty	ByteString	Ordem de bytes
BlobProperty	db.Blob	Nenhum
DateProperty TimeProperty DateTimeProperty	datetime.date datetime.time datetime.datetime	Cronológica
GeoPtProperty	db.GeoPt	Por latitude, e depois longitude
PostalAddressProperty	db.PostalAddress	Unicode
PhoneNumberProperty	db.PhoneNumber	Unicode
EmailProperty	db.Email	Unicode
UserProperty	users.User	Endereço de e-mail em ordem Unicode. Evite o uso de UserProperty, conforme a observação na descrição da classe UserPropert.
IMProperty	db.IM	Unicode
LinkProperty	db.Link	Unicode
CategoryProperty	db.Category	Unicode
RatingProperty	db.Rating	Numérico
ReferenceProperty SelfReferenceProperty	db.Key	Por elementos do caminho (tipo, identificador, tipo, identificador...)
blobstore.BlobReferenceProperty	blobstore.BlobInfo	Ordem de bytes
ListProperty StringListProperty	list de um tipo compatível	Se crescente, pelo menor elemento; se decrescente, pelo maior elemento

Tipos de valor do armazenamento de dados

Os valores de propriedade da entidade do armazenamento de dados podem ser de um dos tipos abaixo. Acima, uma lista de classes Property correspondentes a serem usadas com definições Model.

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

str ou unicode

Uma string curta (1.500 bytes ou menos).

Um valor str é considerado como texto codificado com o codec ascii, e é convertido em um valor unicode antes de ser armazenado. O valor é retornado pelo armazenamento de dados como um valor 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 com mais de 1.500 bytes (que não estão indexadas), use uma instância de Text. Para strings de bytes não codificadas com mais de 1.500 bytes (também não indexadas), use uma instância de Blob. Para strings de bytes não textuais e não codificadas de até 1.500 bytes (não caracteres) que precisam ser indexadas, use uma instância de ByteString.

Propriedade de modelo: StringProperty

bool

Um valor booleano (True ou False).

Propriedade de modelo: BooleanProperty

int ou long

Um valor inteiro de até 64 bits.

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

Se for atribuído um long maior que 64 bits, apenas os 64 bits menos significativos serão armazenados.

Propriedade de modelo: IntegerProperty

float

Um número de ponto flutuante.

Propriedade de modelo: FloatProperty

datetime.datetime

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 de None. Um aplicativo que precisa de valores de data e hora para estar em um fuso horário específico precisa definir tzinfo corretamente ao atualizar o valor e converter valores no fuso horário ao acessar o valor.

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

Se você apenas converter valores em/de um fuso horário específico, poderá implementar um datetime.tzinfo personalizado para converter valores do armazenamento de dados:

import datetime
import time

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

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

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

        if dst_start <= dt.replace(tzinfo=None) < dst_end:
            return datetime.timedelta(hours=1)
        else:
            return datetime.timedelta(hours=0)
    def tzname(self, dt):
        if self.dst(dt) == datetime.timedelta(hours=0):
            return "PST"
        else:
            return "PDT"

pacific_time = datetime.datetime.fromtimestamp(time.mktime(utc_time.timetuple()), Pacific_tzinfo())

Consulte a datetime documentação do módulo (incluindo datetime.tzinfo), bem como o módulo de terceiros pytz, mas observe que a distribuição pytz tem muitos arquivos.

A classe de propriedade de modelo DateTimeProperty inclui recursos como a capacidade de usar automaticamente a data e a hora do armazenamento de uma instância de modelo. Esses recursos são do modelo e não estão disponíveis no valor bruto 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 compatíveis.

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

Propriedade de modelo: ListProperty

db.Key

A chave de outra entidade de armazenamento de dados.

Observação: as strings de chave são limitadas a 1.500 bytes ou menos.

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

blobstore.BlobKey

A chave de um valor do Blobstore gerada por ele quando o valor é enviado.

Propriedades de modelo: blobstore.BlobReferenceProperty

users.User

Um usuário com uma conta do Google.

Um valor user.User no armazenamento de dados não é atualizado quando o usuário altera o próprio endereço de e-mail. Por esse motivo, é altamente recomendável evitar armazenar um users.User como um valor UserProperty, porque isso inclui o endereço de e-mail e o ID exclusivo. Se um usuário alterar o endereço de e-mail e você comparar o user.User antigo armazenado com o novo valor de user.User, eles não serão correspondentes. Em vez disso, use o user_id() do valor de user.User como o identificador estável exclusivo do usuário.

Propriedade de modelo: UserProperty

class Blob(arg=None)

Dados binários, como uma string de bytes. É 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. Ele usa um valor str, mas esse valor é armazenado como uma string de bytes e não é codificado como texto. Use 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", "rb").read())

Em XML, os blobs tem codificação base64 independentemente de conterem ou não dados binários.

class ByteString(arg)

Um valor de blob curto (uma "string de bytes") de 1.500 bytes ou menos. ByteString é uma subclasse de str, e usa um valor str não codificado como argumento para o 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 com mais de 1.500 bytes (não indexadas), use uma instância de Blob. Para dados de texto codificados, use str (curto, indexado) ou Text (longo, não indexado).

Propriedade de modelo: ByteStringProperty

class Text(arg=None, encoding=None)

Uma string longa. É uma subclasse do tipo unicode integrado.

arg um valor de unicode ou str. Se arg for um str, então ele será analisado com a codificação especificada por encoding, ou ascii se nenhuma codificação for especificada. Consulte a lista de codificações padrão (em inglês) para possíveis valores de encoding.

Ao contrário de uma propriedade de entidade com valor igual a um strou unicode, uma propriedade Text pode ter mais de 1.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". É 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, é um elemento Category do Atom.

class Email(email)

Um endereço de e-mail. É 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("[e-mail]")

Em XML, este é um elemento gd:email.

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.

class IM(protocol, address=None)

Um gerenciador de mensagens instantâneas.

Protocol é o URL canônico do serviço de mensagens instantâneas. Alguns valores possíveis:

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

address é o endereço do gerenciador.

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.

class Link(link)

Um URL totalmente qualificado. É 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, isso é um elemento Link (em inglês) do Atom.

class PhoneNumber(phone)

Um número de telefone legível por seres humanos. É uma subclasse do tipo unicode integrado.

Propriedade de modelo: PhoneNumberProperty

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

m = MyModel()
m.phone = db.PhoneNumber("1 [phone]")

Em XML, este é um elemento gd.phoneNumber.

class PostalAddress(address)

Um endereço postal. É 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.

class Rating(rating)

Uma classificação fornecida pelo usuário para uma parte de conteúdo, como um inteiro entre 0 e 100. É uma subclasse do tipo long integrado. A classe confirma que o valor é um número inteiro entre 0 e 100, bem como gera um BadValueError quando o valor é invá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.

Classes Property

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

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

class BlobProperty(...)

Uma coleção não interpretada de dados binários.

Os dados do blob são uma string de bytes. Para dados de texto, que podem envolver codificação, use TextProperty.

Tipo de valor: Blob

class BooleanProperty(...)

Um valor booleano (True ou False).

Tipo de valor: bool

class ByteStringProperty(verbose_name=None, ...)

Um valor de blob curto (uma "string de bytes") de 1.500 bytes ou menos.

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

Como StringProperty, exceto que o valor não é codificado de forma alguma. Os bytes são armazenados literalmente.

ISe ByteStringPropertyfor obrigatório, o valor não poderá ser uma string vazia.

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 data sem hora. Consulte DateTimeProperty para mais informações.

Tipo de valor: datetime.date; convertido internamente em datetime.datetime

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

Data e hora.

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

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

Os valores de data e hora são armazenados e retornados com o fuso horário UTC. Consulte datetime.datetime para uma discussão sobre como gerenciar fusos horários.

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(...)

Um número de 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 gerenciador de mensagens instantâneas.

Tipo de valor: IM

class IntegerProperty(...)

Um valor inteiro de até 64 bits.

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

Se for atribuído um long maior que 64 bits, apenas os 64 bits menos significativos serão armazenados.

Tipo de valor: int ou long

class LinkProperty(...)

Um URL totalmente qualificado.

Tipo de valor: Link

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

Uma lista de valores do tipo especificado por item_type.

Em uma consulta, a comparação de uma propriedade de lista com um valor realiza o teste em relação aos membros da lista: list_property = value testa se o valor aparece em qualquer lugar da lista, list_property < value testa se algum dos membros da lista é menor que o valor fornecido e assim por diante.

Uma consulta não pode comparar dois valores de lista. Não há como 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 ou classe Python. Todos os itens no valor da lista precisam ser do tipo especificado. item_type precisa ser um dos tipos de valor do armazenamento de dados, e não pode ser list.

O valor de um ListProperty não pode ser None. Entretanto, pode ser uma lista vazia. Quando None é especificado para o argumento padrão (ou quando o argumento padrão não é especificado), o valor padrão da propriedade é a lista vazia.

Dica: como os tipos agregados ListProperty não usam 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 você quiser validar um valor de membro usando uma classe Property class, you can instantiate the class poderá instanciar a classe e chamar o respectivo método validate() no valor.

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

Consulte a página Modelagem de dados para mais informações sobre propriedades e valores de lista.

Tipo de valor: um list Python de valores do tipo especificado

class PhoneNumberProperty(...)

Um número de telefone legível por seres humanos.

Tipo de valor: PhoneNumber

class PostalAddressProperty(...)

Um endereço postal.

Tipo de valor: PostalAddress

class RatingProperty()

Uma classificação fornecida pelo usuário para uma parte de 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 referenciado pela propriedade.

reference_class é a classe de modelo da instância de modelo referenciada. Se especificada, somente instâncias de modelo da classe poderão ser atribuídas a essa propriedade. Se None, qualquer instância de modelo poderá ser o valor desta propriedade.

collection_name é o nome da propriedade a ser dado à classe de modelo referenciada. O valor da propriedade é um Query de todas as entidades que referenciam a entidade. Se nenhum collection_name for definido, será usado modelname_set (com o nome do modelo referenciado em letras minúsculas e _set adicionado).

Observação: collection_name precisará ser definido se houver várias propriedades no mesmo modelo que referenciam a mesma classe de modelo. Caso contrário, um DuplicatePropertyError será gerado quando os nomes padrão forem gerados.

ReferenceProperty automaticamente referencia e desreferencia as instâncias de modelo como valores de propriedade: uma instância de modelo pode ser atribuída diretamente a uma propriedade de referência e a respectiva chave será usada. O valor ReferenceProperty pode ser usado como uma instância de modelo, e a entidade do armazenamento de dados será buscada e a instância de modelo criada quando for usada pela primeira vez dessa forma. Propriedades de referência não utilizadas não fazem consultas de 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

author = db.get(author_key)
stories_by_author = author.story_set.get()

Como no caso de um valor Key, é possível que um valor de propriedade referencie uma entidade de dados que não existe. Se uma entidade referenciada for excluída do armazenamento de dados, as referências à entidade não serão atualizadas. Acessar uma entidade que não existe gera um ReferencePropertyResolveError.

A exclusão de uma entidade não remove as entidades referenciadas por uma propriedade de referência.

Tipo de valor: db.Key

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

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

Semelhante a uma propriedade de lista de valores Python str ou unicode (basestring).

Tipo de valor: um valor Python list de str ou unicode

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

Uma string curta. Usa um valor Python str ou unicode (basestring) de 1.500 bytes ou menos.

Os valores 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 alimentação de linha. A biblioteca djangoforms usa isso para impor uma diferença entre campos de texto e campos de área de texto no modelo de dados, e outros podem usá-lo para finalidade semelhante.

Se a propriedade string for necessária, o valor correspondente não poderá ser uma string vazia.

Tipo de valor: str ou unicode

class TextProperty()

Uma string longa.

Ao contrário de StringProperty, um valor TextProperty pode ter mais de 1.500 bytes de comprimento. Entretanto, os valores 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, use BlobProperty.

Se a propriedade texto for necessária, o valor correspondente não poderá ser uma string vazia.

Tipo de valor: Text

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

Uma hora do dia sem data. Usa um valor datetime.time da biblioteca padrão do Python. Consulte DateTimeProperty para mais informações.

Tipo de valor: datetime.time; convertido internamente em datetime.datetime

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

Importante: é altamente recomendável não armazenar um UserProperty, porque ele inclui o endereço de e-mail e o código exclusivo do usuário. Se um usuário alterar o endereço de e-mail e você comparar o User antigo armazenado com o novo valor de User, eles não serão correspondentes.

Um usuário com uma conta do Google.

Se auto_current_user for True, o valor da propriedade será definido com o usuário atualmente conectado 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 com o usuário atualmente conectado na primeira vez 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