La classe Property

Nota:gli sviluppatori che creano nuove applicazioni sono fortemente incoraggiati a utilizzare la libreria client NDB, che offre diversi vantaggi rispetto a questa libreria client, ad esempio la memorizzazione automatica nella cache delle entità tramite l'API Memcache. Se al momento utilizzi la libreria client DB precedente, leggi la guida alla migrazione da DB a NDB.

La classe Property è la superclasse delle definizioni delle proprietà per i modelli di dati. Una classe di proprietà definisce il tipo di valore di una proprietà, come vengono convalidati i valori e come vengono archiviati nel datastore.

Property è fornito dal modulo google.appengine.ext.db.

Introduzione

Una classe di proprietà descrive il tipo di valore, il valore predefinito, la logica di convalida e altre funzionalità di una proprietà di un modello. Ogni classe di proprietà è una sottoclasse della classe Property. L'API Datastore include classi di proprietà per ciascuno dei tipi di valori Datastore e diverse altre che forniscono funzionalità aggiuntive oltre ai tipi Datastore. Consulta la sezione Tipi e classi di proprietà.

Una classe di proprietà può accettare la configurazione dagli argomenti passati al costruttore. Il costruttore della classe base supporta diversi argomenti in genere supportati in tutte le classi di proprietà, inclusi tutti quelli forniti nell'API Datastore. Questa configurazione può includere un valore predefinito, se è richiesto o meno un valore esplicito, un elenco di valori accettabili e una logica di convalida personalizzata. Per saperne di più sulla configurazione della proprietà, consulta la documentazione relativa a un tipo di proprietà specifico.

Una classe di proprietà definisce il modello per una proprietà del datastore. Non contiene il valore della proprietà per un'istanza del modello. Le istanze della classe Property appartengono alla classe Model, non alle istanze della classe. In termini Python, le istanze della classe di proprietà sono "descrittori" che personalizzano il comportamento degli attributi delle istanze del modello. Per saperne di più sui descrittori, consulta la documentazione di Python.

Costruttore

Il costruttore della classe base Property è definito come segue:

class Property(verbose_name=None, name=None, default=None, required=False, validator=None, choices=None, indexed=True)

La superclasse delle definizioni delle proprietà del modello.

Argomenti

verbose_name

Un nome facile da usare della proprietà. Deve sempre essere il primo argomento di un costruttore di proprietà. La libreria djangoforms lo utilizza per creare etichette per i campi del modulo e altri possono utilizzarlo per uno scopo simile.

name

Il nome dell'archiviazione per la proprietà, utilizzato nelle query. Il valore predefinito è il nome dell'attributo utilizzato per la proprietà. Poiché le classi di modelli hanno attributi diversi dalle proprietà (che non possono essere utilizzate per le proprietà), una proprietà può utilizzare name per utilizzare un nome di attributo riservato come nome della proprietà nel datastore e utilizzare un nome diverso per l'attributo della proprietà. Per ulteriori informazioni, consulta Nomi delle proprietà non consentiti.

predefinito

Un valore predefinito per la proprietà. Se alla proprietà non viene mai assegnato un valore o le viene assegnato il valore None, il valore viene considerato quello predefinito.

Nota:le definizioni delle classi di modelli vengono memorizzate nella cache insieme al resto del codice dell'applicazione. Ciò include la memorizzazione nella cache dei valori predefiniti per le proprietà. Non impostare un valore predefinito nella definizione del modello con dati specifici della richiesta (ad esempio users.get_current_user()). Definisci invece un metodo __init__() per la classe Model che inizializza i valori delle proprietà.

obbligatorio

Se True, la proprietà non può avere un valore di None. Un'istanza del modello deve inizializzare tutte le proprietà richieste nel costruttore in modo che l'istanza non venga creata con valori mancanti. Un tentativo di creare un'istanza senza inizializzare una proprietà obbligatoria o un tentativo di assegnare None a una proprietà obbligatoria genera un BadValueError.

Una proprietà sia obbligatoria sia con un valore predefinito utilizza il valore predefinito se non ne viene specificato uno nel costruttore. Tuttavia, alla proprietà non può essere assegnato un valore di None e non esiste un modo automatico per ripristinare il valore predefinito dopo che è stato assegnato un altro valore. Puoi sempre accedere all'attributo default della proprietà per ottenere questo valore e assegnarlo in modo esplicito.

validator

Una funzione da chiamare per convalidare il valore della proprietà quando viene assegnato. La funzione accetta il valore come unico argomento e genera un'eccezione se il valore non è valido. Il validatore specificato viene chiamato dopo che è stata eseguita un'altra convalida, ad esempio il controllo che una proprietà obbligatoria abbia un valore. Quando a una proprietà non obbligatoria non viene assegnato un valore, lo strumento di convalida viene chiamato con l'argomento None.

scelte

Un elenco di valori accettabili per la proprietà. Se impostata, alla proprietà non può essere assegnato un valore non presente nell'elenco. Come per la convalida obbligatoria e altre convalide, un'istanza del modello deve inizializzare tutte le proprietà con le scelte in modo che l'istanza non venga creata con valori non validi. Se choices è None, tutti i valori che superano la convalida sono accettabili.

indicizzata

Indica se questa proprietà deve essere inclusa negli indici integrati e definiti dallo sviluppatore. Se False, le entità scritte nel datastore non verranno mai restituite dalle query che ordinano o filtrano in base a questa proprietà, in modo simile alle proprietà Blob e Text.

Nota:ogni proprietà indicizzata aggiunge una piccola quantità di overhead, costo della CPU e latenza alle chiamate put() e delete(). Se non avrai mai bisogno di filtrare o ordinare in base a una proprietà, valuta la possibilità di utilizzare indexed=False per evitare questo sovraccarico. Fai attenzione, però. Se in un secondo momento decidi di indicizzare la proprietà, la modifica di nuovo in indexed=True influirà solo sulle scritture da quel momento in poi. Le entità originariamente scritte con indexed=False non verranno reindicizzate.

Attributi classe

Le sottoclassi della classe Property definiscono il seguente attributo di classe:

data_type

Il tipo di dati o la classe Python che la proprietà accetta come valore nativo di Python.

Metodi dell'istanza

Le istanze delle classi Property hanno i seguenti metodi:

default_value()

Restituisce il valore predefinito della proprietà. L'implementazione di base utilizza il valore dell'argomento default passato al costruttore. Una classe di proprietà potrebbe eseguire l'override di questo valore per fornire un comportamento speciale del valore predefinito, ad esempio la funzionalità di aggiornamento automatico di DateTimeProperty.

validate(value)

La routine di convalida completa per la proprietà. Se value è valido, restituisce il valore, invariato o adattato al tipo richiesto. In caso contrario, genera un'eccezione appropriata.

L'implementazione di base verifica che value non sia None se richiesto (l'argomento required del costruttore della proprietà di base), che il valore sia una delle scelte valide se la proprietà è stata configurata con delle scelte (l'argomento choices) e che il valore superi il validatore personalizzato, se presente (l'argomento validator).

La routine di convalida viene chiamata quando viene istanziato un modello che utilizza il tipo di proprietà (con valori predefiniti o inizializzati) e quando a una proprietà del tipo viene assegnato un valore. La routine non dovrebbe avere effetti collaterali.

empty(value)

Restituisce True se value è considerato un valore vuoto per questo tipo di proprietà. L'implementazione di base è equivalente a not value, che è sufficiente per la maggior parte dei tipi. Altri tipi, come un tipo booleano, possono eseguire l'override di questo metodo con un test più appropriato.

get_value_for_datastore(model_instance)

Restituisce il valore che deve essere archiviato nel datastore per questa proprietà nell'istanza del modello specificata. L'implementazione di base restituisce semplicemente il valore nativo di Python della proprietà nell'istanza del modello. Una classe di proprietà può eseguire l'override di questa impostazione per utilizzare un tipo di dati diverso per il datastore rispetto all'istanza del modello o per eseguire un'altra conversione dei dati appena prima di archiviare l'istanza del modello.

make_value_from_datastore(value)

Restituisce la rappresentazione nativa di Python per il valore specificato dall'archivio dati. L'implementazione di base restituisce semplicemente il valore. Una classe di proprietà può eseguire l'override di questa impostazione per utilizzare un tipo di dati diverso per l'istanza del modello rispetto al datastore.

make_value_from_datastore_index_value(value)

Restituisce la rappresentazione nativa di Python per il valore specificato dall'indice del datastore. L'implementazione di base restituisce semplicemente il valore. Una classe di proprietà può eseguire l'override di questa impostazione per utilizzare un tipo di dati diverso per l'istanza del modello rispetto al datastore.