Tipos e classes de propriedades

Nota: os programadores que criam novas aplicações são fortemente aconselhados a usar a biblioteca de cliente NDB, que tem várias vantagens em comparação com esta biblioteca de cliente, como o armazenamento em cache automático de entidades através da API Memcache. Se estiver a usar atualmente a biblioteca cliente DB mais antiga, leia o guia de migração de DB para NDB

O Datastore do App Engine suporta um conjunto fixo de tipos de valores para propriedades em entidades de dados. Property classes podem definir novos tipos que são convertidos para e a partir dos tipos de valores subjacentes, e os tipos de valores podem ser usados diretamente com Expando propriedades dinâmicas e ListProperty modelos de propriedades agregadas.

A tabela seguinte descreve as classes de propriedades cujos valores correspondem diretamente aos tipos de dados subjacentes. Qualquer um destes tipos de valores pode ser usado numa propriedade dinâmica Expando ou num tipo agregado ListProperty.

Classe de propriedade	Tipo de valor	Ordenaçã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 dos bytes
BlobProperty	db.Blob	Nenhum
DateProperty TimeProperty DateTimeProperty	datetime.date datetime.time datetime.datetime	Cronológico
GeoPtProperty	db.GeoPt	Por latitude, depois longitude
PostalAddressProperty	db.PostalAddress	Unicode
PhoneNumberProperty	db.PhoneNumber	Unicode
EmailProperty	db.Email	Unicode
UserProperty	users.User	Endereço de email por ordem Unicode. Tenha em atenção que deve evitar usar UserProperty, de acordo com a nota em Descrição da classe UserProperty.
IMProperty	db.IM	Unicode
LinkProperty	db.Link	Unicode
CategoryProperty	db.Category	Unicode
RatingProperty	db.Rating	Numérico
ReferenceProperty SelfReferenceProperty	db.Key	Por elementos de caminho (tipo, identificador, tipo, identificador...)
blobstore.BlobReferenceProperty	blobstore.BlobInfo	Ordem dos bytes
ListProperty StringListProperty	list de um tipo suportado	Se for ascendente, pelo elemento mais pequeno; se for descendente, pelo elemento mais elevado

Tipos de valores do armazenamento de dados

Os valores das propriedades das entidades da base de dados podem ser de um dos seguintes tipos. Consulte acima uma lista das classes correspondentes a usar com as definições.PropertyModel

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

str ou unicode

Uma string curta (1500 bytes ou menos).

Um valor str é considerado texto codificado com o codec ascii e é convertido num valor unicode antes de ser armazenado. O valor é devolvido pelo arquivo de dados como um valor unicode. Para strings curtas que usam outros codecs, use um valor unicode.

As strings curtas são indexadas pelo arquivo de dados e podem ser usadas em filtros e ordens de ordenação. Para strings de texto com mais de 1500 bytes (que não são indexadas), use uma instância de Text. Para strings de bytes não codificadas com mais de 1500 bytes (também não indexadas), use uma instância de Blob. Para strings de bytes não textuais não codificadas até 1500 bytes (não carateres) que devem ser indexadas, use uma instância de ByteString.

Propriedade do modelo: StringProperty

bool

Um valor booleano (True ou False).

Propriedade do modelo: BooleanProperty

int ou long

Um valor inteiro, até 64 bits.

Os valores Python int são convertidos em valores Python long antes do armazenamento. Um valor armazenado como int é devolvido como long.

Se for atribuído um long superior a 64 bits, apenas são armazenados os 64 bits menos significativos.

Propriedade do modelo: IntegerProperty

float

Um número de vírgula flutuante.

Propriedade do modelo: FloatProperty

datetime.datetime

Uma data e uma hora. Consulte a datetimedocumentação do módulo.

Se o valor datetime tiver um atributo tzinfo, é convertido no fuso horário UTC para armazenamento. Os valores são devolvidos do arquivo de dados como UTC, com um tzinfo de None. Uma aplicação que precise de valores de data e hora numa fuso horário específico tem de definir tzinfo corretamente quando atualiza o valor e converter os valores para o fuso horário quando acede ao valor.

Algumas bibliotecas usam a variável de ambiente TZ para controlar o fuso horário aplicado aos valores de data/hora. O App Engine define esta variável de ambiente como "UTC". Tenha em atenção que a alteração desta variável numa aplicação não altera o comportamento de algumas funções de data/hora, porque as alterações às variáveis de ambiente não são visíveis fora do código Python.

Se apenas converter valores para e de um fuso horário específico, pode implementar um datetime.tzinfo personalizado para converter valores do arquivo 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 documentação do módulo datetime (incluindo datetime.tzinfo). Consulte também o módulo de terceiros pytz, embora a distribuição pytz tenha muitos ficheiros.

A classe de propriedade do modelo inclui funcionalidades como a capacidade de usar automaticamente a data e a hora em que uma instância do modelo é armazenada.DateTimeProperty Estas são funcionalidades do modelo e não estão disponíveis no valor da base de dados não processados (como numa propriedade dinâmica).Expando

Propriedades do modelo: DateTimeProperty, DateProperty, TimeProperty

list

Uma lista de valores, cada um dos quais é de um dos tipos de dados suportados.

Quando é usado um list como valor de uma propriedade dinâmica Expando, não pode ser uma lista vazia. Isto deve-se à forma como os valores de lista são armazenados: quando uma propriedade de lista não tem itens, não tem representação no arquivo de dados. Pode usar uma propriedade estática e a classe ListProperty para representar um valor de lista vazio para uma propriedade.

Propriedade do modelo: ListProperty

db.Key

A chave de outra entidade do arquivo de dados.

Nota: as strings de chaves estão limitadas a 1500 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 do modelo: ReferenceProperty, SelfReferenceProperty

blobstore.BlobKey

A chave de um valor do Blobstore, gerada pelo Blobstore quando o valor é carregado.

Propriedades do modelo: blobstore.BlobReferenceProperty

users.User

Um utilizador com uma Conta Google.

Um valor user.User no arquivo de dados não é atualizado se o utilizador alterar o respetivo endereço de email. Por este motivo, recomendamos vivamente que evite armazenar um users.User como um valor UserProperty, uma vez que inclui o endereço de email juntamente com o ID único. Se um utilizador alterar o endereço de email e, em seguida, comparar o user.User antigo armazenado com o novo valor de user.User, estes não vão corresponder. Em alternativa, use o valor user.Useruser_id() como identificador exclusivo estável do utilizador.

Propriedade do modelo: UserProperty

class Blob(arg=None)

Dados binários, como uma sequência 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 nem ordens de ordenação.

O Blob destina-se a dados binários, como imagens. Aceita um valor str, mas este valor é armazenado como uma string de bytes e não é codificado como texto. Use uma instância de Text para grandes quantidades de dados de texto.

Propriedade do modelo: BlobProperty

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

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

Em XML, os BLOBs são codificados em base64, quer contenham ou não dados binários.

class ByteString(arg)

Um valor de blob curto (uma "string de bytes") de 1500 bytes ou menos. ByteString é uma subclasse de str, e usa um valor str não codificado como argumento para o respetivo construtor.

As ByteStrings são indexadas pela base de dados e podem ser usadas em filtros e ordens de ordenação. Para strings de bytes com mais de 1500 bytes (que não são indexadas), use uma instância de Blob. Para dados de texto codificados, use str (curto, indexado) ou Text (longo, não indexado).

Propriedade do 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 um str, é analisado com a codificação especificada por encoding ou ascii se não for especificada nenhuma codificação. Consulte a lista de codificações padrão para ver os valores possíveis de codificação.

Ao contrário de uma propriedade de entidade cujo valor é um simples str ou unicode, uma propriedade de texto pode ter mais de 1500 bytes. No entanto, as propriedades de texto não são indexadas e não podem ser usadas em filtros nem ordens de ordenação.

Propriedade do 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 uma "etiqueta". Esta é uma subclasse do tipo unicode integrado.

Propriedade do modelo: CategoryProperty

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

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

Em XML, este é um elemento Atom Category.

class Email(email)

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

Nem a classe de propriedade nem a classe de valor validam os endereços de email. Apenas armazenam o valor.

Propriedade do modelo: EmailProperty

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

m = MyModel()
m.email_address = db.Email("[e-mail]")

Em XML, trata-se de um elemento gd:email.

class GeoPt(lat, lon=None)

Um ponto geográfico representado por coordenadas de latitude e longitude de vírgula flutuante.

Propriedade do modelo: GeoPtProperty

Em XML, trata-se de um elemento georss:point.

class IM(protocol, address=None)

Um identificador 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 identificador.

Propriedade do modelo: IMProperty

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

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

Em XML, trata-se de um elemento gd:im.

class Link(link)

Um URL totalmente qualificado. Esta é uma subclasse do tipo unicode integrado.

Propriedade do modelo: LinkProperty

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

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

Em XML, este é um elemento Atom Link.

class PhoneNumber(phone)

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

Propriedade do modelo: PhoneNumberProperty

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

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

Em XML, trata-se de um elemento gd.phoneNumber.

class PostalAddress(address)

Uma morada. Esta é uma subclasse do tipo unicode integrado.

Propriedade do modelo: PostalAddressProperty

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

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

Em XML, trata-se de um elemento gd:postalAddress.

class Classificação(classificação)

Uma classificação fornecida pelo utilizador para um conteúdo, como um número inteiro entre 0 e 100. Esta é uma subclasse do tipo long integrado. A classe valida se o valor é um número inteiro entre 0 e 100 e gera um erro BadValueError se o valor for inválido.

Propriedade do modelo: RatingProperty

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

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

Em XML, trata-se de um elemento gd:rating.

Classes de propriedades

Todas as classes de propriedades do 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 ver informações sobre esses argumentos.

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

class BlobProperty(...)

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

Os dados de 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 1500 bytes ou menos.

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

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

Se o elemento ByteStringProperty for obrigatório, o valor não pode ser uma string vazia.

Tipo de valor: ByteString

class CategoryProperty(...)

Uma categoria ou "etiqueta", uma palavra ou uma expressão descritiva.

Tipo de valor: Category

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

Uma data sem uma hora do dia; consulte DateTimeProperty para mais informações.

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

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

Uma data e uma hora.

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

Se auto_now_add for True, o valor da propriedade é definido para a hora atual da primeira vez que a instância do modelo é armazenada no arquivo de dados, a menos que já tenha sido atribuído um valor à propriedade. Isto é útil para armazenar a data e a hora de "criação" de uma instância do modelo.

Os valores de data/hora são armazenados e devolvidos através do fuso horário UTC. Consulte datetime.datetime para ver uma discussão sobre como gerir fusos horários.

Tipo de valor: datetime.datetime

class EmailProperty(...)

Um endereço de email.

Nem a classe de propriedade nem a classe de valor validam os endereços de email. Apenas armazenam o valor.

Tipo de valor: Email

class FloatProperty(...)

Um número de vírgula flutuante.

Tipo de valor: float

class GeoPtProperty(...)

Um ponto geográfico representado por coordenadas de latitude e longitude de vírgula flutuante.

Tipo de valor: GeoPt

class IMProperty(...)

Um identificador de mensagens instantâneas.

Tipo de valor: IM

class IntegerProperty(...)

Um valor inteiro, até 64 bits.

Os valores Python int são convertidos em valores Python long antes do armazenamento. Um valor armazenado como int é devolvido como long.

Se for atribuído um long superior a 64 bits, apenas são armazenados os 64 bits menos significativos.

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.

Numa consulta, a comparação de uma propriedade de lista com um valor executa o teste em relação aos 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 é inferior ao valor indicado e assim sucessivamente.

Uma consulta não pode comparar dois valores de lista. Não existe forma de testar a igualdade de duas listas sem testar a associação de cada elemento separadamente.

item_type é o tipo dos itens na lista, como um tipo ou uma classe Python. Todos os itens no valor da lista têm de ser do tipo indicado. item_type tem de ser um dos tipos de valores da base de dados, e não pode ser list.

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

Dica: uma vez que os tipos de agregação ListProperty não usam as classes Property, as funcionalidades de classe Property, como valores automáticos e validação, não são aplicadas automaticamente aos membros do valor da lista. Se quiser validar um valor de membro através de uma classe Property, pode instanciar a classe e chamar o respetivo método validate() no valor.

default é o valor predefinido para a propriedade de lista. Se None, a predefinição é uma lista vazia. Uma propriedade de lista pode definir um validador personalizado para não permitir a lista vazia.

Consulte a página Modelagem de dados para mais informações sobre as propriedades e os valores das listas.

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

class PhoneNumberProperty(...)

Um número de telefone legível.

Tipo de valor: PhoneNumber

class PostalAddressProperty(...)

Uma morada.

Tipo de valor: PostalAddress

class RatingProperty()

Uma classificação fornecida pelo utilizador para um conteúdo, como um número 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 do modelo. Por exemplo, uma referência pode indicar uma relação muitos-para-um entre o modelo com a propriedade e o modelo referenciado pela propriedade.

reference_class é a classe do modelo da instância do modelo que está a ser referenciada. Se for especificado, apenas as instâncias do modelo da classe podem ser atribuídas a esta propriedade. Se None, qualquer instância do modelo pode ser o valor desta propriedade.

collection_name é o nome da propriedade a atribuir à classe do modelo referenciada. O valor da propriedade é um Query para todas as entidades que fazem referência à entidade. Se não for definido nenhum collection_name, é usado modelname_set (com o nome do modelo referenciado em letras minúsculas e _set adicionado).

Nota: collection_name tem de ser definido se existirem várias propriedades no mesmo modelo que referenciem a mesma classe de modelo. Caso contrário, é apresentado um DuplicatePropertyError quando os nomes predefinidos são gerados.

ReferenceProperty faz automaticamente referência e desreferência a instâncias de modelos como valores de propriedades: uma instância de modelo pode ser atribuída diretamente a uma propriedade de referência e a respetiva chave é usada. O valor ReferenceProperty pode ser usado como se fosse uma instância de modelo, e a entidade de armazenamento de dados é obtida e a instância de modelo criada quando é usada pela primeira vez desta forma. As propriedades de referência intocadas não consultam 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()

Tal como acontece com um valor Key, é possível que um valor de propriedade de referência se refira a uma entidade de dados que não existe. Se uma entidade referenciada for eliminada do arquivo de dados, as referências à entidade não são atualizadas. O acesso a uma entidade que não existe gera um erro ReferencePropertyResolveError.

A eliminação de uma entidade não elimina as entidades referidas 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 do 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 str ou unicode (basestring) do Python.

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

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

Uma string curta. Aceita um valor str ou unicode (basestring) do Python de 1500 bytes ou menos.

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

Se multiline for False, o valor não pode incluir carateres de mudança de linha. A biblioteca djangoforms usa isto para aplicar uma diferença entre campos de texto e campos de área de texto no modelo de dados, e outros podem usá-lo para um objetivo semelhante.

Se a propriedade de string for obrigatória, o respetivo valor não pode 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 1500 bytes. No entanto, os valores de TextProperty não são indexados e não podem ser usados em filtros nem ordens de ordenação.

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

Se a propriedade de texto for obrigatória, o respetivo valor não pode 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 uma data. Aceita um valor da biblioteca padrão do Python; consulte DateTimeProperty para mais informações.datetime.time

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

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

Importante: recomendamos vivamente que não armazene um UserProperty, uma vez que inclui o endereço de email e o ID exclusivo do utilizador. Se um utilizador alterar o respetivo endereço de email e comparar o valor User antigo armazenado com o novo valor User, não vai haver correspondência.

Um utilizador com uma Conta Google.

Se auto_current_user for True, o valor da propriedade é definido para o utilizador com sessão iniciada atualmente sempre que a instância do modelo é armazenada no arquivo de dados, substituindo o valor anterior da propriedade. Isto é útil para acompanhar que utilizador modifica uma instância do modelo.

Se auto_current_user_add for True, o valor da propriedade é definido para o utilizador com sessão iniciada atualmente na primeira vez que a instância do modelo é armazenada no repositório de dados, a menos que a propriedade já tenha sido atribuída a um valor. Isto é útil para acompanhar que utilizador cria uma instância do modelo, que pode não ser o mesmo utilizador que a modifica posteriormente.

UserProperty não aceita um valor predefinido. Os valores predefinidos são definidos quando a classe do modelo é importada pela primeira vez e, com a colocação em cache da importação, podem não corresponder ao utilizador com sessão iniciada atualmente.

Tipo de valor: users.User