La classe Property

Nota: gli sviluppatori che creano nuove applicazioni sono vivamente incoraggiati a utilizzare la libreria client NDB, che offre diversi vantaggi rispetto a questa libreria client, ad esempio la memorizzazione nella cache automatica 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 Property definisce il tipo di valore di una proprietà, la modalità di convalida e la modalità di archiviazione dei valori 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 di Datastore e molte altre che forniscono funzionalità aggiuntive oltre ai tipi di Datastore. Consulta Tipi e classi di proprietà.

Un'entità di proprietà può accettare la configurazione dagli argomenti passati al costruttore. Il costruttore della classe di base supporta diversi argomenti che in genere sono supportati in tutte le classi di proprietà, inclusi tutti quelli forniti nell'API Datastore. Questa configurazione può includere un valore predefinito, l'eventuale obbligatorietà di un valore esplicito, un elenco di valori accettabili e una logica di convalida personalizzata. Per ulteriori informazioni sulla configurazione di un tipo di proprietà specifico, consulta la documentazione relativa a quel tipo.

Una classe di proprietà definisce il modello per una proprietà del data store. 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 di Python, le istanze di classi di proprietà sono "descrittori" che personalizzano il comportamento degli attributi delle istanze di Model. Per ulteriori informazioni sui descrittori, consulta la documentazione di Python.

Costruttore

Il costruttore della classe di 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 per la proprietà. Deve sempre essere il primo argomento del costruttore di una proprietà. La libreria djangoforms la utilizza per creare etichette per i campi dei moduli e altri possono utilizzarla per uno scopo simile.
name
Il nome dello spazio di archiviazione della proprietà, utilizzato nelle query. Per impostazione predefinita, viene utilizzato il nome dell'attributo utilizzato per la proprietà. Poiché le classi di modelli hanno attributi diversi dalle proprietà (che non possono essere utilizzati per le proprietà), una proprietà può utilizzare name per utilizzare un nome di attributo riservato come nome della proprietà nel datastore e un nome diverso per l'attributo della proprietà. Per ulteriori informazioni, consulta Nomi proprietà non consentiti.
default

Un valore predefinito per la proprietà. Se al valore della proprietà non viene mai assegnato un valore o se viene assegnato il valore None, questo valore viene considerato il valore predefinito.

Nota:le definizioni delle classi del modello vengono memorizzate nella cache insieme al resto del codice dell'applicazione. Sono inclusi la memorizzazione nella cache dei valori predefiniti per le proprietà. Non impostare un valore predefinito nella definizione del modello con dati specifici per la 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 None. Un'istanza di modello deve inizializzare tutte le proprietà richieste nel relativo costruttore in modo che 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 errore BadValue.

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

validator
Una funzione da chiamare per convalidare il valore della proprietà quando viene assegnato. La funzione prende il valore come unico argomento e genera un'eccezione se il valore non è valido. Lo strumento di convalida 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.
choices
Un elenco di valori accettabili per la proprietà. Se impostato, alla proprietà non può essere assegnato un valore non presente nell'elenco. Come per required e altre convalide, un'istanza di modello deve inizializzare tutte le proprietà con 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 data store non verranno mai restituite dalle query che ordinano o filtrano in base a questa proprietà, in modo simile alle proprietà Blob e Testo.

Nota:ogni proprietà indicizzata aggiunge una piccola quantità di overhead, costi della CPU e latenza alle chiamate put() e delete(). Se non dovrai mai filtrare o ordinare in base a una proprietà, ti consigliamo di utilizzare indexed=False per evitare questo sovraccarico. Fai attenzione, però. Se in un secondo momento decidi di indicizzare la proprietà, la reimpostazione su indexed=True influirà solo sulle scritture da quel momento in poi. Le entità originariamente scritte con indexed=False non verranno sottoposte a nuova indicizzazione.

Attributi della classe

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

data_type
Il tipo di dati o la classe Python accettati dalla proprietà come valore nativo di Python.

Metodi istanza

Le istanze delle classi Property hanno i seguenti metodi:

default_value()

Restituisce il valore predefinito per la proprietà. L'implementazione di base utilizza il valore dell'argomento default passato al costruttore. Una classe di proprietà potrebbe sostituire questo valore per fornire un comportamento speciale del valore predefinito, ad esempio la funzionalità automatica ora corrente 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, viene sollevata un'eccezione appropriata.

L'implementazione di base verifica che value non sia None, se richiesto (l'argomento required del costruttore di proprietà di base), che il valore sia una delle scelte valide se la proprietà è stata configurata con le 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 creato 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 deve 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 sostituire questo metodo con un test più appropriato.

get_value_for_datastore(model_instance)

Restituisce il valore che deve essere archiviato nel data store 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ò sostituire questo valore 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 memorizzare l'istanza del modello.

make_value_from_datastore(value)

Restituisce la rappresentazione nativa di Python per il valore specificato dal datastore. L'implementazione di base restituisce semplicemente il valore. Una classe di proprietà può sostituire questo valore per utilizzare un tipo di dati diverso per l'istanza del modello rispetto al data store.

make_value_from_datastore_index_value(value)

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