Documentation - Home

Note

To use this library, you must have Python installed on your device.

Don’t have Python? Install it here: https://python.org/downloads

Installation

You can install kms with pip:

pip install key-multivalue-storage

Or, install it with uv:

uv add key-multivalue-storage

You can also install the dev extra. This extra provides Pylint and Griffe on the side, allowing for easier development and testing.

pip install key-multivalue-storage[dev]

Warning

This extra is only available on versions later than kms-v1.2.2/2026.05.06b.

Tip

No pip or uv? Install the wheel here: https://pypi.org/project/key-multivalue-storage/#files

Basic Usage

Tip

When importing just logic related to Storage (i.e. Storage, Load, Edit, Delete), the recommended import statement is:

from key_multivalue_storage import Storage # note the module name!

Otherwise, the main recommended import statement stands as:

import key_multivalue_storage as kms # note the module name!

Create a Storage object to prepare the data to be stored:

  from key_multivalue_storage import Storage # note the module name!
  my_db = Storage("my_top_level_key", mysubkey="myvalue", myothersk="anotherval")

To store the object, use Storage.store().
```
  my_db.store("database.json")
```

Load data from a JSON file back into a Storage object:

  my_db = Storage.Load.by_key("my_top_level_key")
  print(my_db)

Output:

{
   "my_top_level_key": {
       "mysubkey": "myvalue",
       "myothersk": "anotherval"
   }
}

Change global settings:

  Storage.indent = 4 #indent size of JSON files
  Storage.encode = True # Whether to encode stored values
  Storage.auto_delete_self = True
  # Whether to automatically release the object
  # from memory after certain operations

Structure of the Library

Note

Certain items that aren’t part of the public API and/or are part of repo systems like workflows are not shown here.

Tip

Click on a module, class, or method below to go straight to its documentation!

src/key_multivalue_storage/
- storage.py — main Storage class (core functionality)
  - Storage
    - __init__
    - store
    - keys
    - to_dict
- load.py — loading helpers (Load class)
  - Load
    - by_key
    - by_index
    - keys
    - values
- edit.py — editing helpers (Edit class)
  - Edit
- delete.py — deletion helpers (Delete class)
  - Delete
- utils/
  - exceptions.py — custom exceptions
    - KeyNotFoundError
    - NoInstantiationError
  - warnings.py — custom warning classes and private warning decorators
  - metadata.py
test/
- test-storage.py — Mainstream test targeting kms.storage
- test-load.py — Mainstream test targeting kms.load
- test-edit.py — Mainstream test targeting kms.edit
- test-delete.py — Mainstream test targeting kms.delete
- test-general.py — legacy, only used to ensure backwards compatibility
- test-meta.py — Mainstream test targeting kms.utils.metadata
- test-exceptions.py — Mainstream test targeting kms.utils.exceptions and kms.utils.warnings
- test-fix-*.py / test-feat-*.py — Targeted tests from PRs. Integrated into mainstream tests every minor update, starting from kms-semver1.4.x.

List of Current Deprecations

Important

Only public deprecations are included. Deprecations to private methods, modules, or logic are not included.

List of current deprecations, sorted by the version they were deprecated. All deprecations listed below will be formally removed in kms-semver2.0.0.

`kms-semver1.3.1`

Deprecated format specifiers .tuplef and .tuplet.
Attribute auto_delete_self and argument instant_delete of Storage.store() has been deprecated.

`kms-semver1.3.0`

All metadata variables from kms-semver1.2.2 were renamed. You can still use the old names, however they are no longer recommended for use and will display a DeprecationWarning warning.

Old name	New name
`VERSION`	`semver`
`DATE_VERSION`	`calver`
`LAST_UPDATE`	`last_update`

In Storage.Delete.by_propkey: the required argument top_level_key has been deprecated. Please use the renamed top_lv_key instead. This change was made to match with other methods with the same parameter.

Storage.Delete.by_propkey(_,top_lv_key='key')

All warnings and exceptions will no longer be under kms.Storage but rather be under just kms.

import key_multivalue_storage as kms

warnings.filterwarning(category=kms.Storage.DeleteWarning) # Old, will raise DeprecationWarning
warnings.filterwarning(category=kms.DeleteWarning) # New, will work properly

`kms-semver1.2.3`

All metadata variables from kms-semver1.2.2 were renamed. You can still use the old names, however they are no longer recommended for use and will display a DeprecationWarning warning.

Old name	New name
`VERSION`	`semver`
`DATE_VERSION`	`calver`
`LAST_UPDATE`	`last_update`

In Storage.Delete.by_propkey: the required argument top_level_key has been deprecated. Please use the renamed top_lv_key instead. This change was made to match with other methods with the same parameter.

Storage.Delete.by_propkey(_,top_lv_key='key')

`kms-semver1.2.0`

Keyword argument new of method Storage.Edit.propkey was deprecated in favor of the argument noexist_ok.

« Back to home