a django plugin that provides the ability create key value models with only one line.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Django KVModel

KVModel provides a very convenient way to create key-value models with just two lines of code.

from kvmodel.models import KVModel

class SystemSettings(KVModel):
    SystemSettings Model now extends KVModel, and you will
    be able to access the key and the value fields on that Model


You can Install django-kvmodel from PyPI.
pip install django-kvmodel


Add kvmodel to your INSTALLED_APPS setting::


This will enable kvmodel, form more advanced settings please check the advanced section.


KVModel is an abstract model that has two fields key and value.

  • key is a unique CharField.
  • value is a SerializableField which means that it's type is restored when loading an instance from the database, check out the advanced section for more details about SerializableField.

Defining key-value models

Extend KVModel to create a key-value model:

from kvmodel.models import KVModel

class Settings(KVModel):

Creating instances

You can create Instances the same way you will use a Django Model
setting = Settings(key='dragons_in_store', value=123)
for a persistent instance
setting = Settings.create(key='dragons_in_store', value=123)

Retrieving instances

you can use Django filters to retrieve data from your model, however you shouldn't use the value field to search for data.

there is also a method to retrieve objects using their key:
setting = Settings.get_by_key('dragons_in_store')
which is equivalent to:
setting = Settings.get(key='dragons_in_store')

Advanced Usage


this is a custom field that extends TextField, it encodes the data before saving and decodes it once an instance is loaded from the database.

you can use SerilizableField like this:

from kvmodes.models import KVModel
from kvmodel.fields import SerilizableField

class SystemSettings(KVModel):
    default = SerialiableField()

By default SerializableField uses JSON for de-serializing data however you can define your custom de-serializers.

the serialize function is called before the object is saved to the database, it should accept the value and returns a string.

the deserialize function is called when loading an instance from the data base, it should accept a string and return the restored value

Defining Custom serializer/derserilizer

define the functions you want to use as de-serilizers:

    return aes_encrypt(json.dumps(value), key='super secret key')

    return json.loads(aes_decrypt(s, key='super secret key'))

next you should update the KVMODEL setting:

    'SERIALIZE_FUNCTION': 'appname.modulename.aes_serilize',
    'DESERIALIZE_FUNCTION': 'appname.modulename.aes_deserialize'