Home

Caution

This wiki is no longer maintained. Please go to the official docs website instead -> https://boss-1s.github.io/key_multivalue_storage

Docs branch: click here

Docs folder on semver1.4.x: click here

Docs folder on docs: click here

Warning

Anything below this message is no longer maintained. Please take caution when reading this old information. :/

Welcome to the key_multivalue_storage wiki!

Warning

If you are reading this from the wiki instead of the official docs page, please note that links here will most likely not work.

JSON storage wrapper and editor. Created with love by Boss_1s.

Once upon a time, this was just a small project to solve a problem: the over-steep learning curve for scratchattach's database functionality. Now, I have decided to make it a library, something with humble beginnings with big hopes in its future.

It is strongly recommended to learn Python before using kms. The best environment to learn in is CPython 3.12 for this library.

Please do note that throughout this repository, the library key-multivalue-storage may also be referred to as its repo/package name (key_multivalue_storage) or its abbreviation (kms).

Documentation

• Documentation
• Storage
• Loading
• Editing
• Deleting

Resources

• Versioning, Release, and Security
• Info on kms-semver2.0
• PyPi Package Page

Contributor Resources

• [Structure of the library]
• Contributor Guidelines
• Changelog
• Development Help
• Roadmap
• Issues
• Pull Requests

You can contribute to this open-source project by forking this repo, making changes, then opening a pull request. Be sure to read through the guidelines!

Installation

Install with pip:

pip install -U key-multivalue-storage

Or, download the latest version of the .whl file here

You can also choose to download the development environment alongside the package:

pip install -U key-multivalue-storage[dev]

The development package contains both Pylint and Griffe.

Basic Usage

• 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")

• You can change certain global settings for each Storage instance.

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 i.e.
# Storage.store()

• Loading a stored object by a top level key and loading all the top level keys of a JSON file:

>>> Storage.Load.by_key("database.json", "my_top_level_key")
Storage(top_lv_key="my_top_level_key", key_value_pairs=["mysubkey"="myvalue", "myothersk"="anotherval"])
>>> Storage.Load.keys("database.json")
["my_top_level_key"]

Tip

See more about loading here.

• Editing a subkey's name and value within the JSON file:

>>> Storage.Edit.propkey("database.json", # file_path
                         "my_top_level_key", # top_lv_key
                         "mysubkey", # oldpropkey
                         "newkey" # newpropkey
                         noexist_ok = True # Creates a new subkey with the new subkey name if the old subkey name did not exist
                        )
>>> Storage.Load.values("database.json", "my_top_level_key", keys=True, raw=False)
["newkey: myvalue", "myothersk: anotherval"]
>>> Storage.Edit.propval("database.json", # file_path
                         "my_top_level_key", # top_lv_key
                         "myothersk", # propkey
                         "wow!" # newval
                        )
>>> Storage.Load.values("database.json", "my_top_level_key", keys=True, raw=False)
["newkey: myvalue", "myothersk: wow!"]

Tip

See more about editing here.

• Deleting a subkey-value pair within the JSON file:

>>> Storage.Delete.by_propkey("database.json", # file_path
                              "my_top_level_key", # top_level_key
                              "myothersk" # property_key
                             )
>>> Storage.Load.values("database.json", "my_top_level_key", keys=True, raw=False)
["newkey: myvalue"]

Tip

See more about deleting here.

• Adding and subtracting two Storage instances:

>>> # Adding instances combines the two instances, as long as the top level key is the same.
>>> addStorage = Storage("combine", sk1="val1") + Storage("combine", sk2="val2")
>>> print(addStorage)
Storage(top_lv_key="combine", key_value_pairs=["sk1"="val1", "sk2"="val2"])
>>> # Subtracting instances remove any exact same key-value pairs from the two instances, as long as the top level key is the same.
>>> subStorage = Storage("combine", sk1="val1", sk2="val2") - Storage("combine", sk2="val2")
>>> print(addStorage)
Storage(top_lv_key="combine", key_value_pairs=["sk1"="val1"])

Tip

See more about special functions here.

---

Tip

All kms features are documented in the documentation.

---

Thanks for using kms! ❤