Scrittura nelle sottoclassi di proprietà

In questa pagina viene descritto come utilizzare le API e i servizi legacy raggruppati. Questa API può essere eseguita solo nei runtime di prima generazione nell'ambiente standard di App Engine. Se esegui l'aggiornamento al runtime App Engine Python 3, consulta la guida alla migrazione per scoprire di più sulle opzioni di migrazione per i servizi in bundle legacy.

La classe Property è progettata per essere sottoclassificata. Tuttavia, in genere è più facile creare una sottoclasse di una Property esistente.

Tutti gli attributi Property speciali, anche quelli considerati "pubblici", hanno nomi che iniziano con un trattino basso. Questo perché StructuredProperty utilizza lo spazio dei nomi degli attributi senza trattini bassi per fare riferimento ai nomi Property nidificati. Questo è essenziale per specificare le query sulle proprietà secondarie.

La classe Property e i relativi sottoclassi predefiniti consentono di creare sottoclassi utilizzando API di convalida e conversione composable (o impilabili). Queste richiedono alcune definizioni di terminologia:

• Un valore utente è un valore che verrebbe impostato e a cui verrebbe eseguito l'accesso dal codice dell'applicazione utilizzando gli attributi standard dell'entità.
• Un valore base è un valore che verrebbe serializzato e deserializzato dal Datastore.

Una sottoclasse Property che implementa una trasformazione specifica tra valori utente e valori serializzabili deve implementare due metodi, _to_base_type() e _from_base_type(). Questi metodi non devono chiamare il metodo super(). Questo è ciò che si intende per API composable (o impilabili).

L'API supporta le classi di accodamento con conversioni basate sugli utenti sempre più sofisticate: la conversione da utente a base avviene da più sofisticata a meno sofisticata, mentre la conversione da base a utente avviene da meno sofisticata a più sofisticata. Ad esempio, osserva la relazione tra BlobProperty, TextProperty e StringProperty. Ad esempio, TextProperty eredita da BlobProperty; il suo codice è piuttosto semplice perché eredita la maggior parte del comportamento di cui ha bisogno.

Oltre a _to_base_type() e _from_base_type(), anche il metodo _validate() è un'API componibile.

L'API di convalida distingue tra valori utente rilassati e rigorosi. L'insieme di valori lax è un superinsieme dell'insieme di valori rigorosi. Il metodo _validate() prende un valore lax e, se necessario, lo trasforma in un valore rigoroso. Ciò significa che, quando si imposta il valore della proprietà, sono accettati valori lax, mentre quando si ottiene il valore della proprietà, vengono restituiti solo valori rigorosi. Se non è necessaria alcuna conversione, _validate() può restituire None. Se l'argomento rientra nell'insieme di valori lax accettati, _validate() deve generare un'eccezione, preferibilmente TypeError o datastore_errors.BadValueError.

_validate(), _to_base_type() e _from_base_type() non devono gestire:

• None: non verranno chiamati con None (e se restituiscono None, significa che il valore non richiede conversione).
• Valori ripetuti: l'infrastruttura si occupa di chiamare _from_base_type() o _to_base_type() per ogni elemento dell'elenco in un valore ripetuto.
• Distinguere i valori utente dai valori di base: l'infrastruttura gestisce questo compito chiamando le API componibili.
• Confronti: le operazioni di confronto chiamano _to_base_type() sul loro operando.
• Distinzione tra valori utente e di base: l'infrastruttura garantisce che _from_base_type() venga chiamato con un valore di base (scollegato) e che _to_base_type() venga chiamato con un valore utente.

Ad esempio, supponiamo che tu debba memorizzare numeri interi molto lunghi. IntegerProperty standard supporta solo interi a 64 bit (con segno). La proprietà potrebbe memorizzare un numero intero più lungo come stringa. È consigliabile che la classe della proprietà gestisca la conversione. Un'applicazione che utilizza la tua classe di proprietà potrebbe avere il seguente aspetto

from datetime import date

import my_models

...

class MyModel(ndb.Model):
    name = ndb.StringProperty()
    abc = LongIntegerProperty(default=0)
    xyz = LongIntegerProperty(repeated=True)

...

# Create an entity and write it to the Datastore.
entity = my_models.MyModel(name='booh', xyz=[10**100, 6**666])
assert entity.abc == 0
key = entity.put()

...

# Read an entity back from the Datastore and update it.
entity = key.get()
entity.abc += 1
entity.xyz.append(entity.abc//3)
entity.put()

...

# Query for a MyModel entity whose xyz contains 6**666.
# (NOTE: using ordering operations don't work, but == does.)
results = my_models.MyModel.query(
    my_models.MyModel.xyz == 6**666).fetch(10)

Sembra semplice e diretto. Inoltre, mostra l'uso di alcune opzioni di proprietà standard (predefinite, ripetute); in qualità di autore di LongIntegerProperty, ti farà piacere sapere che non devi scrivere alcun "boilerplate" per utilizzarle. È più facile definire una sottoclasse di un'altra proprietà, ad esempio:

class LongIntegerProperty(ndb.StringProperty):
    def _validate(self, value):
        if not isinstance(value, (int, long)):
            raise TypeError('expected an integer, got %s' % repr(value))

    def _to_base_type(self, value):
        return str(value)  # Doesn't matter if it's an int or a long

    def _from_base_type(self, value):
        return long(value)  # Always return a long

Quando imposti un valore della proprietà in un'entità, ad esempio ent.abc = 42, viene chiamato il metodo _validate() e (se non viene sollevata un'eccezione) il valore viene memorizzato nell'entità. Quando scrivi l'entità in Datastore, viene chiamato il metodo _to_base_type(), che converte il valore in stringa. Il valore viene poi serializzato dalla classe di base, StringProperty. La catena di eventi inversa si verifica quando l'entità viene letta nuovamente da Datastore. Le classi StringProperty e Property si occupano insieme degli altri dettagli, come la serializzazione e la deserializzazione della stringa, l'impostazione del valore predefinito e la gestione dei valori di proprietà ripetuti.

In questo esempio, il supporto delle disuguaglianze (ovvero query che utilizzano <, <=, >, >=) richiede più lavoro. L'implementazione di esempio riportata di seguito impone una dimensione massima di un numero intero e immagazzina i valori come stringhe di lunghezza fissa:

class BoundedLongIntegerProperty(ndb.StringProperty):
    def __init__(self, bits, **kwds):
        assert isinstance(bits, int)
        assert bits > 0 and bits % 4 == 0  # Make it simple to use hex
        super(BoundedLongIntegerProperty, self).__init__(**kwds)
        self._bits = bits

    def _validate(self, value):
        assert -(2 ** (self._bits - 1)) <= value < 2 ** (self._bits - 1)

    def _to_base_type(self, value):
        # convert from signed -> unsigned
        if value < 0:
            value += 2 ** self._bits
        assert 0 <= value < 2 ** self._bits
        # Return number as a zero-padded hex string with correct number of
        # digits:
        return '%0*x' % (self._bits // 4, value)

    def _from_base_type(self, value):
        value = int(value, 16)
        if value >= 2 ** (self._bits - 1):
            value -= 2 ** self._bits
        return value

Può essere utilizzato nello stesso modo di LongIntegerProperty tranne per il fatto che devi passare il numero di bit al costruttore della proprietà, ad es. BoundedLongIntegerProperty(1024).

Puoi creare sottoclassi di altri tipi di proprietà in modi simili.

Questo approccio funziona anche per l'archiviazione di dati strutturati. Supponiamo di avere una classe Python FuzzyDate che rappresenti un intervallo di date. Utilizza i campi first e last per memorizzare l'inizio e la fine dell'intervallo di date:

from datetime import date

...

class FuzzyDate(object):
    def __init__(self, first, last=None):
        assert isinstance(first, date)
        assert last is None or isinstance(last, date)
        self.first = first
        self.last = last or first

Puoi creare un FuzzyDateProperty che deriva da StructuredProperty. Purtroppo, quest'ultimo non funziona con le classi Python standard, ma richiede una sottoclasse Model. Quindi, definisci una sottoclasse Model come rappresentazione intermedia.

class FuzzyDateModel(ndb.Model):
    first = ndb.DateProperty()
    last = ndb.DateProperty()

Successivamente, crea una sottoclasse di StructuredProperty che codifichi l'argomento modelclass come FuzzyDateModel e definisce i metodi _to_base_type() e _from_base_type() per convertire da FuzzyDate a FuzzyDateModel:

class FuzzyDateProperty(ndb.StructuredProperty):
    def __init__(self, **kwds):
        super(FuzzyDateProperty, self).__init__(FuzzyDateModel, **kwds)

    def _validate(self, value):
        assert isinstance(value, FuzzyDate)

    def _to_base_type(self, value):
        return FuzzyDateModel(first=value.first, last=value.last)

    def _from_base_type(self, value):
        return FuzzyDate(value.first, value.last)

Un'applicazione potrebbe utilizzare questa classe nel seguente modo:

class HistoricPerson(ndb.Model):
    name = ndb.StringProperty()
    birth = FuzzyDateProperty()
    death = FuzzyDateProperty()
    # Parallel lists:
    event_dates = FuzzyDateProperty(repeated=True)
    event_names = ndb.StringProperty(repeated=True)

...

columbus = my_models.HistoricPerson(
    name='Christopher Columbus',
    birth=my_models.FuzzyDate(date(1451, 8, 22), date(1451, 10, 31)),
    death=my_models.FuzzyDate(date(1506, 5, 20)),
    event_dates=[my_models.FuzzyDate(
        date(1492, 1, 1), date(1492, 12, 31))],
    event_names=['Discovery of America'])
columbus.put()

# Query for historic people born no later than 1451.
results = my_models.HistoricPerson.query(
    my_models.HistoricPerson.birth.last <= date(1451, 12, 31)).fetch()

Supponiamo che tu voglia accettare oggetti date semplici oltre agli oggetti FuzzyDate come valori per FuzzyDateProperty. Per farlo, modifica il metodo _validate() come segue:

def _validate(self, value):
    if isinstance(value, date):
        return FuzzyDate(value)  # Must return the converted value!
    # Otherwise, return None and leave validation to the base class

In alternativa, puoi creare una sottoclasse di FuzzyDateProperty come segue (supponendo che FuzzyDateProperty._validate() sia come mostrato sopra).

class MaybeFuzzyDateProperty(FuzzyDateProperty):
    def _validate(self, value):
        if isinstance(value, date):
            return FuzzyDate(value)  # Must return the converted value!
        # Otherwise, return None and leave validation to the base class

Quando assegni un valore a un campo MaybeFuzzyDateProperty, MaybeFuzzyDateProperty._validate() e FuzzyDateProperty._validate() vengono richiamati in questo ordine. Lo stesso vale per _to_base_type() e _from_base_type(): i metodi nella superclasse e nella sottoclasse vengono combinati implicitamente. Non utilizzare super per controllare il comportamento ereditato per questo. Per questi tre metodi, l'interazione è sottile e super non fa ciò che vuoi.