La classe Property

Nota: Gli sviluppatori che creano nuove applicazioni sono vivamente incoraggiati a utilizzare il Libreria client NDB, che offre numerosi vantaggi rispetto a questa libreria client, come la memorizzazione automatica nella cache delle entità tramite tramite Google Cloud CLI o tramite l'API Compute Engine. Se al momento utilizzi la libreria client DB precedente, leggi il 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 caratteristiche di una proprietà di un modello. Ogni classe di proprietà è una sottoclasse della classe Property. 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à.

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 Python, le istanze delle classi di proprietà sono "descrittori" che personalizzano il comportamento degli attributi delle istanze del modello. 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 raccolta 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 saperne di più, consulta la sezione Nomi di 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 di 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 ne è specificato uno 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 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 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.

choices

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 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 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 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 voler indicizzare la proprietà, la reimpostazione di indexed=True inciderà 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 classe:

data_type

Il tipo di dati o la classe Python accettata 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 dei valori predefiniti, come la funzionalità di attivazione automatica di DateTimeProperty.

validate(valore)

La routine di convalida completa per la proprietà. Se value è 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 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 equivale 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 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 questa impostazione 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 data store. 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 rispetto al datastore.