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 thisHierarkey
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.
- 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
-
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
- value – Serialized 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 thisHierarkey
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 specifyingas_type
. If the key does not have a harcdoded default type, omittingas_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 thebinary_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.
-