Nota: Python 2.7 ha raggiunto la fine del supporto il 31 gennaio 2024. Le applicazioni Python 2.7 esistenti continueranno a essere eseguite e a ricevere traffico. Tuttavia, App Engine potrebbe bloccare il ri deployment di applicazioni che utilizzano runtime dopo la data di fine del supporto. Ti consigliamo di eseguire la migrazione all'ultima versione supportata di Python.

La classe della proprietà

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, come la memorizzazione nella cache automatica delle entità tramite l'API Memcache. Se attualmente utilizzi la libreria client DB precedente, leggi la Guida alla migrazione dal database a NDB

La classe Proprietà è la superclasse delle definizioni di proprietà per i modelli di dati. Una classe Property definisce il tipo di valore di una proprietà, le modalità di convalida dei valori e 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 caratteristiche di una proprietà di un Modello. Ogni classe di proprietà è una sottoclasse della classe Proprietà. L'API del datastore include classi di proprietà per ciascuno dei tipi di valore del datastore e molti altri che offrono funzionalità aggiuntive oltre ai tipi di datastore. Consulta Tipi e classi di proprietà.

Una classe di proprietà può accettare la configurazione da argomenti passati al costruttore. Il costruttore della classe base supporta diversi argomenti generalmente supportati in tutte le classi di proprietà, incluse quelle fornite nell'API datastore. Questa configurazione può includere un valore predefinito, indipendentemente dal fatto che sia 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 stessa. In termini Python, le istanze delle classi di proprietà sono "descrittori" che personalizzano il comportamento degli attributi delle istanze del modello. Consulta la documentazione di Python per ulteriori informazioni sui descrittori.

Costruttore

Il costruttore della classe base della proprietà viene definito come segue:

class Property(verbose_name=None, name=None, default=None, required=False, Convalida=Nessuno, choices=Nessuno, indexed=Vero)

La superclasse delle definizioni delle proprietà modello.

Argomenti

verbose_name

Un nome facile da usare della proprietà. Deve essere sempre il primo argomento per un costruttore di proprietà. La libreria djangoforms la utilizza per creare etichette per i campi dei moduli, mentre altri possono utilizzarla per uno scopo simile.

nome

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 modello hanno attributi diversi dalle proprietà (che non possono essere utilizzate per le proprietà), una proprietà può utilizzare name per utilizzare un nome dell'attributo riservato come nome della proprietà nel datastore e usare un nome diverso per l'attributo della proprietà. Per ulteriori informazioni, consulta la sezione Nomi di proprietà non consentite.

predefinita

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

Nota: le definizioni delle classi dei modelli vengono memorizzate nella cache insieme al resto del codice dell'applicazione. Ciò include i valori predefiniti per la memorizzazione nella cache delle 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 Modello che inizializza i valori delle proprietà.

obbligatorio

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

Una proprietà obbligatoria e con un valore predefinito utilizza il valore predefinito se nel costruttore non ne è specificato uno. Tuttavia, alla proprietà non può essere assegnato il 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 che deve essere chiamata 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 sono avvenute altre convalide, ad esempio dopo aver verificato 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 la convalida obbligatoria e di altro tipo, un'istanza del modello deve inizializzare tutte le proprietà con opzioni in modo che l'istanza non venga creata con valori non validi. Se il valore di choices è None, sono accettabili tutti i valori che altrimenti superano la convalida.

indicizzato

Indica se la proprietà deve essere inclusa negli indici integrati e definiti dallo sviluppatore. Con False, le entità scritte nel datastore non verranno mai restituite dalle query che ordinano o filtrano in questa proprietà, come per le proprietà Blob e Testo.

Nota: ogni proprietà indicizzata comporta un piccolo aumento di overhead, costi della CPU e latenza alle chiamate put() e delete(). Se non avrai mai bisogno di filtrare o ordinare i dati per una proprietà, ti consigliamo di utilizzare indexed=False per evitare questo sovraccarico. Fai attenzione, però. Se in un secondo momento decidi di voler indicizzare la proprietà, la modifica del valore indexed=True avrà effetto 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: La classe o il tipo di dati Python che la proprietà accetta come valore nativo di Python.

Metodi di istanza

Le istanze delle classi di proprietà 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à può sostituire questo valore per fornire un comportamento speciale per il valore predefinito, come la funzionalità ora automatica 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 controlla che value non sia None se necessario (l'argomento obbligatorio per il costruttore della proprietà di base), il valore è una delle scelte valide se la proprietà è stata configurata con opzioni (l'argomento choices) e il valore trasmette lo strumento di convalida personalizzato, se presente (l'argomento Convalida).

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

vuoto(valore)

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 il 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 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ò sostituire questa impostazione in modo da utilizzare per il datastore un tipo di dati diverso da quello per l'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 Python per il valore specificato dal datastore. L'implementazione di base restituisce semplicemente il valore. Una classe di proprietà può sostituire questa impostazione in modo da utilizzare un tipo di dati diverso per l'istanza del modello e per il datastore.

make_value_from_datastore_index_value(value)

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