Home

Welcome to the key_multivalue_storage wiki!

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]
• [Storage Object Special Methods and Representations]

Resources

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

Contributor Resources

• [Structure of the library]
• Contributor Guidelines
• Changelog
• 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]

From kms-semver1.3 and onward, the development package will contain both Pylint and Griffe. Versions before that but after kms-semver1.2.2 will contain Pylint only.

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"]

[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!"]

[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"]

[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"])

[See more about special functions here.]

All kms features are documented in the [documentation].

Thanks for using kms!