Skip to content


Subversion checkout URL

You can clone with
Download ZIP
a django plugin that provides the ability create key value models with only one line.
Branch: master

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'
Something went wrong with that request. Please try again.