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

La classe Property è la superclasse delle definizioni delle proprietà per i modelli dei dati. Una classe Property definisce il tipo di valore di una proprietà, la 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 diverse altre 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, con o senza la necessità di 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 specifico di proprietà.

Una classe di proprietà definisce il modello di una proprietà 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 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à è definito come segue:

class Proprietà(verbose_name=None, verbose_name=None, verbose_name=None, verbose_name=False, verbose_name=Nessuno, verbose_name=None, verbose_name=True)

La superclasse delle definizioni delle proprietà del modello.

Argomenti

verbose_name

Un nome semplice della proprietà. Deve sempre essere il primo argomento di un costruttore di proprietà. La libreria djangoforms lo utilizza per creare etichette per i campi dei moduli e altri possono usarle 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 modello 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 un nome diverso per l'attributo della proprietà. Per saperne di più, consulta la sezione Nomi di proprietà non consentiti.

predefinita

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

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

obbligatorio

Se True, la proprietà non può avere il valore None. Un'istanza di modello deve inizializzare tutte le proprietà richieste nel 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 BadValueError.

Una proprietà obbligatoria e con un valore predefinito utilizza il valore predefinito se non è stato specificato nel costruttore. Tuttavia, alla proprietà non può essere assegnato il valore None e non è possibile ripristinare automaticamente 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 il valore. La funzione prende il valore come unico argomento e genera un'eccezione se il valore non è valido. Lo strumento di convalida viene chiamato dopo che sono state effettuate altre convalide, ad esempio la verifica 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 impostato, non è possibile assegnare alla proprietà un valore non presente nell'elenco. Come per required e altri tipi di convalida, un'istanza di un 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.

indicizzato

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 da query che ordinano o filtrano in base a questa proprietà, in modo simile alle proprietà Blob e Testo.

Nota:ogni proprietà indicizzata aggiunge un piccolo overhead, costi di CPU e latenza alle chiamate put() e delete(). Se non dovrai mai applicare filtri o ordinamenti per una proprietà, valuta la possibilità di utilizzare indexed=False per evitare questo sovraccarico. Fai attenzione però! Se in un secondo momento decidi di volere che la proprietà venga indicizzata, la modifica ripristinando indexed=True influirà solo sulle scritture da quel momento in poi. Le entità scritte originariamente con indexed=False non verranno reindicizzate.

Attributi classe

Le sottoclassi della classe Property definiscono il seguente attributo classe:

data_type

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

Metodi di 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 dei valori predefiniti, ad esempio la funzionalità di attivazione automatica di DateTimeProperty.

validate(value)

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

L'implementazione di base verifica che value non sia None se richiesto (l'argomento required per il costruttore della proprietà di base), il valore sia una delle scelte valide se la proprietà è stata configurata con scelte (l'argomento choices) e il valore passa 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 a una proprietà del tipo viene assegnato un valore. La routine non dovrebbe avere effetti collaterali.

vuoto(valore)

Restituisce True se value è considerato un valore vuoto per questo tipo di proprietà. L'implementazione di base equivale a not value, che è sufficiente per la maggior parte dei tipi. Altri tipi, come il 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 questo comando 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 dal datastore. L'implementazione di base restituisce semplicemente il valore. Una classe di proprietà può sostituire questo valore in modo da 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ò sostituire questo valore in modo da utilizzare un tipo di dati diverso per l'istanza del modello rispetto al datastore.