API Reference

Everything not listed on this page is considered a private API and should not be called from outside.

Model definition

class hierarkey.models.Hierarkey(attribute_name)

The Hierarkey object represents one complete key-value store hierarchy. It can have one global and multiple object-level storages attached and holds default values as well as custom type serialization info.

Parameters:attribute_name – The name for the attribute on the model instances that will allow access to the storage, e.g. settings.
add(cache_namespace: str = None, parent_field: str = None) → type

Decorator. Attaches a global key-value store to a Django model.

Parameters:
  • cache_namespace – Optional. A custom namespace used for caching. By default this is constructed from the name of the class this is applied to and the attribute_name of this Hierarkey object.
  • parent_field – Optional. The name of a field of this model that refers to the parent in the hierarchy. This must be a ForeignKey field.
add_default(key: str, value: Optional[str], default_type: type = <class 'str'>) → None

Adds a default value and a default type for a key.

Parameters:
  • key – Key
  • valueSerialized default value, i.e. a string or None.
  • default_type – The type to deserialize values for this key to, defaults to str.
add_type(type: type, serialize: Callable[[Any], str], unserialize: Callable[[str], Any]) → None

Adds serialization support for a new type.

Parameters:
  • type – The type to add support for.
  • serialize – A callable that takes an object of type type and returns a string.
  • unserialize – A callable that takes a string and returns an object of type type.
set_global(cache_namespace: str = None) → type

Decorator. Attaches the global key-value store of this hierarchy to an object.

Parameters:cache_namespace – Optional. A custom namespace used for caching. By default this is constructed from the name of the class this is applied to and the attribute_name of this Hierarkey object.
class hierarkey.models.GlobalSettingsBase

Base class for objects with a global settings storage attached. This class does not add any functionality, it only makes global settings behave more consistent to object-level settings.

Storage access

class hierarkey.proxy.HierarkeyProxy

If you add a hierarkey storage to a model, the model will get a new attribute (e.g. settings) containing a key-value store that is managed by this class.

This class allows access to settings via attribute access, item access or using the documented methods. You should not instantiate this class yourself.

delete(key: str) → None

Deletes a setting from this object’s storage.

The write to the database is performed immediately and the cache in the cache backend is flushed. The cache within this object will be updated correctly.

flush() → None

Discards both the state within this object as well as the cache in Django’s cache backend.

freeze() → dict

Returns a dictionary of all settings set for this object, including any values of its parents or hardcoded defaults.

get(key: str, default=None, as_type: type = None, binary_file: bool = False)

Get a setting specified by key. Normally, settings are strings, but if you put non-strings into the settings object, you can request deserialization by specifying as_type. If the key does not have a harcdoded default type, omitting as_type always will get you a string.

If the setting with the specified name does not exist on this object, any parent object up to the global settings layer (if configured) will be queried. If still no value is found, a default value set in ths source code will be returned if one exists. If not, the value of the default argument of this method will be returned instead.

If you receive a File object, it will already be opened. You can specify the binary_file flag to indicate that it should be opened in binary mode.

set(key: str, value: Any) → None

Stores a setting in the database and connects it to its object.

The write to the database is performed immediately and the cache in the cache backend is flushed. The cache within this object will be updated correctly.

Forms

class hierarkey.forms.HierarkeyForm(*args, obj, attribute_name, **kwargs)

This is a custom subclass of django.forms.Form that you can use to set values for any keys. See the Forms chapter of the documentation for more details.

get_new_filename(name: str) → str

Returns the file name to use based on the original filename of an uploaded file. By default, the file name is constructed as:

<model_name>-<attribute_name>/<primary_key>/<original_basename>.<random_nonce>.<extension>
save() → None

Saves all changed values to the database.