Class Properti

Catatan: Developer yang membuat aplikasi baru sangat dianjurkan untuk menggunakan Library Klien NDB, yang memiliki beberapa manfaat dibandingkan dengan library klien ini, seperti menyimpan entity dalam cache secara otomatis melalui Memcache API. Jika saat ini Anda menggunakan Library Klien DB versi lama, baca Panduan Migrasi DB ke NDB

Class Properti adalah superclass dari definisi properti untuk model data. Class Properti menentukan jenis nilai properti, cara nilai divalidasi, dan cara nilai disimpan di datastore.

Property disediakan oleh modul google.appengine.ext.db.

Pengantar

Class properti menjelaskan jenis nilai, nilai default, logika validasi, dan fitur lain dari properti Model. Setiap class properti adalah subclass dari class Properti. Datastore API menyertakan class properti untuk setiap jenis nilai datastore, dan beberapa jenis lainnya yang menyediakan fitur tambahan selain jenis datastore. Lihat Jenis dan Properti Class.

Class properti dapat menerima konfigurasi dari argumen yang diteruskan ke konstruktor. Konstruktor class dasar mendukung beberapa argumen yang biasanya didukung di semua class properti, termasuk semua yang disediakan dalam datastore API. Konfigurasi tersebut dapat menyertakan nilai default, terlepas dari apakah nilai eksplisit diperlukan atau tidak, daftar nilai yang dapat diterima, dan logika validasi khusus. Lihat dokumentasi untuk jenis properti tertentu guna mendapatkan informasi selengkapnya tentang cara mengonfigurasi properti.

Class properti menentukan model untuk properti datastore. Class tidak berisi nilai properti untuk instance model. Instance class Properti adalah milik class Model, bukan instance class. Dalam istilah Python, instance class properti adalah "deskriptor" yang menyesuaikan perilaku atribut instance Model. Lihat dokumentasi Python untuk mengetahui informasi selengkapnya tentang deskriptor.

Konstruktor

Konstruktor class dasar Properti didefinisikan sebagai berikut:

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

Superclass definisi properti model.

Argumen

verbose_name

Nama properti yang mudah digunakan. Ini harus selalu menjadi argumen pertama bagi konstruktor properti. Library djangoforms menggunakannya untuk membuat label bagi kolom formulir, dan pengguna lain dapat menggunakannya untuk tujuan serupa.

name

Nama penyimpanan untuk properti, yang digunakan dalam kueri. Nilai ini ditetapkan secara default ke nama atribut yang digunakan untuk properti. Karena class model memiliki atribut selain properti (yang tidak dapat digunakan untuk properti), properti dapat menggunakan name untuk menggunakan nama atribut yang dicadangkan sebagai nama properti di datastore, dan menggunakan nama yang berbeda untuk atribut properti. Lihat Nama Properti yang Tidak Diizinkan untuk informasi selengkapnya.

default

Nilai default untuk properti. Jika nilai properti tidak pernah diberikan nilai, atau diberi nilai None, nilai tersebut akan dianggap sebagai nilai default.

Catatan: Definisi class model disimpan dalam cache bersama dengan kode aplikasi lainnya. Ini termasuk menyimpan nilai default untuk properti dalam cache. Jangan tetapkan default dalam definisi model dengan data khusus untuk permintaan (seperti users.get_current_user()). Sebagai gantinya, tentukan metode __init__() untuk class Model yang menginisialisasi nilai properti.

required

Jika True, properti tidak boleh memiliki nilai None. Instance model harus melakukan inisialisasi semua properti yang diperlukan dalam konstruktornya agar instance tersebut tidak dibuat dengan nilai yang hilang. Percobaan untuk membuat instance tanpa menginisialisasi properti yang diperlukan, atau upaya untuk menetapkan None ke properti yang diperlukan, akan memunculkan BadValueError.

Properti yang diperlukan dan memiliki nilai default akan menggunakan nilai default jika tidak diberikan dalam konstruktor. Namun, properti tidak dapat diberi nilai None, dan tidak ada cara otomatis untuk memulihkan nilai default setelah nilai lain ditetapkan. Anda dapat mengakses atribut default properti kapan saja untuk mendapatkan nilai ini dan menetapkannya secara eksplisit.

validator

Fungsi yang harus dipanggil untuk memvalidasi nilai properti saat nilai ditetapkan. Fungsi ini menggunakan nilai sebagai satu-satunya argumen, dan memunculkan pengecualian jika nilai tidak valid. Validator tertentu dipanggil setelah validasi lain dilakukan, seperti pemeriksaan apakah properti yang diperlukan memiliki nilai. Jika properti yang tidak diperlukan tidak diberi nilai, validator dipanggil dengan argumen None.

choices

Daftar nilai yang dapat diterima untuk properti. Jika ditetapkan, properti tidak dapat diberi nilai yang tidak ada dalam daftar. Seperti halnya validasi required dan lainnya, instance model harus menginisialisasi semua properti dengan pilihan agar instance tidak dibuat dengan nilai yang tidak valid. Jika choices adalah None, semua nilai yang lolos validasi dapat diterima.

indexed

Properti ini harus disertakan dalam indeks bawaan dan yang ditentukan developer. Jika False, entity yang ditulis ke datastore tidak akan pernah ditampilkan oleh kueri yang mengurutkan atau memfilter properti ini, mirip dengan properti Blob dan Text.

Catatan: Setiap properti yang diindeks menambahkan sejumlah kecil overhead, biaya CPU, dan latensi ke panggilan put() dan delete(). Jika Anda tidak perlu memfilter atau mengurutkan properti, sebaiknya gunakan indexed=False untuk menghindari overhead tersebut. Namun, berhati-hatilah! Jika nantinya Anda memutuskan ingin properti diindeks, mengubahnya kembali ke indexed=True hanya akan memengaruhi penulisan sejak saat itu dan seterusnya. Entity yang awalnya ditulis dengan indexed=False tidak akan diindeks ulang.

Atribut Class

Subclass dari class Properti mendefinisikan atribut class berikut:

data_type

Jenis data atau class Python yang diterima properti sebagai nilai native Python.

Metode Instance

Instance class Properti memiliki metode berikut:

default_value()

Menampilkan nilai default untuk properti. Implementasi dasar menggunakan nilai argumen default yang diteruskan ke konstruktor. Class properti dapat mengganti class ini untuk memberikan perilaku nilai default khusus, seperti fitur auto-now DateTimeProperty.

validate(value)

Rutinitas validasi lengkap untuk properti. Jika value valid, nilai akan ditampilkan, baik yang tidak berubah atau telah disesuaikan dengan jenis yang diperlukan. Jika tidak, pengecualian yang sesuai akan dimunculkan.

Implementasi dasar memeriksa bahwa value bukan None jika diperlukan (argumen required untuk konstruktor Properti dasar), nilai adalah salah satu pilihan yang valid jika properti dikonfigurasi dengan pilihan (argumen choices), dan nilai akan diteruskan ke validator kustom jika ada (argumen validator).

Rutinitas validasi dipanggil saat model yang menggunakan jenis properti dibuat menjadi instance (dengan nilai yang diinisialisasi atau default), dan saat properti jenis diberi nilai. Rutinitas seharusnya tidak memiliki efek samping.

empty(value)

Menampilkan True jika value dianggap sebagai nilai kosong untuk jenis properti ini. Implementasi dasar setara dengan not value, yang cukup untuk sebagian besar jenis. Jenis lain, seperti jenis Boolean, dapat mengganti metode ini dengan pengujian yang lebih sesuai.

get_value_for_datastore(model_instance)

Menampilkan nilai yang harus disimpan di datastore untuk properti ini dalam instance model yang diberikan. Implementasi dasar hanya menampilkan nilai native Python properti di instance model. Class properti dapat mengganti class ini untuk menggunakan jenis data yang berbeda untuk datastore dibandingkan untuk instance model, atau untuk melakukan konversi data lain tepat sebelum menyimpan instance model.

make_value_from_datastore(value)

Menampilkan representasi berbasis Python untuk nilai yang diberikan dari datastore. Implementasi dasar hanya menampilkan nilai. Class properti dapat mengganti class ini untuk menggunakan jenis data yang berbeda untuk instance model dan untuk datastore.

make_value_from_datastore_index_value(value)

Menampilkan representasi native Python untuk nilai yang diberikan dari indeks datastore. Implementasi dasar hanya menampilkan nilai. Class properti dapat mengganti class ini untuk menggunakan jenis data yang berbeda untuk instance model dan untuk datastore.