Getting started

Install hierarkey

You only need to install the hierarkey package, for example using pip:

$ pip install django-hierarkey

That’s it!

Attach a storage to a single models

As a first example, we will attach a storage object to a single model. For example, you could use this to store settings for every user. If you want to use the hierarchical features of hierarkey, just skip to the next example.

First of all, in your models.py, we will create a Hierarkey object:

from hierarkey.models import Hierarkey

hierarkey = Hierarkey(attribute_name='settings')

The attribute name defines the name that you will use later to access the storage. This allows you to use multiple separated storage hierarchies within one model, if you want to. Next, add a decorator to the model you want to associate the storage with:

@hierarkey.add()
class User(models.Model):
    ....

Note

The parentheses in the call to the @hierarkey.add() decorator are required. Refer to the API documentation for more information on its parameters.s

Now, you need to create a database migration and apply it:

$ python manage.py makemigrations
$ python manage.py migrate

Build a hierarchical storage

To build a hierarchy, we need multiple models. In our example, we will have a three-level hierarchy, consisting of global settings, organization settings and user settings. You can use more levels if you want to, or you can omit the global settings. There can only be one level of global settings.

As in the previous example, we first create a Hierarkey object:

from hierarkey.models import GlobalSettingsBase, Hierarkey

hierarkey = Hierarkey(attribute_name='settings')

Next, we define a class, and attach the global settings. This class can be empty and is not needed except for consistency in the hierarkey API. You can define it like this:

@hierarkey.set_global()
class GlobalSettings(GlobalSettingsBase):
    pass

Then, we add our other two layers. The organization layer works the same way as in the first example above. In contrast, for the user model we have to specify the name of the parent relation:

@hierarkey.add()
class Organization(models.Model):
    ...

@hierarkey.add(parent_field='organization')
class User(models.Model):
    organization = models.ForeignKey(Organization)
    ...

Now, you need to create a database migration and apply it:

$ python manage.py makemigrations
$ python manage.py migrate

Set default values

You can add default values by calling a method on the Hierarkey object specifying the key, the value and the type:

hierarkey.add_default('key', 'value', bool)

Access the settings storage

On an instance of your model, you can access the settings storage under the name you specified as the attribute_name further above.

You can read and write the values in the key-value store in three ways. First, by attribute access:

print(user.settings.theme)
user.settings.theme = 'dark'
del user.settings.theme

Note

Attribute access is unsupported for key starting with an underscore.

Second, by item access:

print(user.settings['theme'])
user.settings['theme'] = 'dark'
del user.settings['theme']

And third, using explicit methods:

print(user.settings.get('theme'))
user.settings.set('theme', 'dark')
user.settings.delete('theme')

All changes are written to the database instantly, while values are read eagerly and are being cached.

Deserialization will only be automatically performed for keys that have a default value specified in code. If you want to deserialize other keys, you need to use the explicit getter methods and specify the type yourself:

user.settings.get('theme', as_type=int)

To access the global settings, you can instantiate the global settings class you defined before:

GlobalSettings().settings.get(…)

Next steps

You can now continue reading either about Forms or in the API Reference.