simple_storage Documentation

Version: 1.1.0

Overview

simple_storage is a lightweight Python module that allows you to save and load data easily without dealing with file handling or JSON directly. It is designed to be beginner-friendly and safe, using human-readable JSON files.

Features

Save and load data in one line
Automatic storage folder creation
Human-readable JSON files
Safe defaults for non-existent data
Supports basic Python types: dict, list, str, int, float, bool, None
Self-test built-in for verification
Versioned for clarity and maintenance

Installation

Simply place simple_storage.py in the same folder as your Python script and import it:

from simple_storage import save, load, exists, delete

Basic Usage

Saving Data

save("settings", {"theme": "dark", "volume": 70})

This creates a file storage/settings.json with JSON content:

{
    "theme": "dark",
    "volume": 70
}

Loading Data

settings = load("settings")
print(settings)

If the file does not exist, it returns None by default. You can also provide a default:

settings = load("settings", default={})

Checking for Existence

if exists("settings"):
    print("Settings file found")

Deleting Data

delete("settings")

This removes the saved file from the storage folder.

Supported Data Types

You can store any JSON-safe Python types:

dict
list
str
int
float
bool
None

Unsupported types include functions, classes, Tkinter widgets, and custom objects.

How It Works

Each saved item becomes one JSON file in a folder called storage. The module uses json.dump to convert Python objects to text and json.load to read them back. The file paths are generated automatically:

storage/your_item_name.json

Example:

save("user_data", {"name": "Andrew", "score": 100})

This creates storage/user_data.json:

{
    "name": "Andrew",
    "score": 100
}

Self-Test

The module includes a built-in self-test. Run the module directly to test all main features:

python simple_storage.py

Output example:

Running simple_storage tests...
All tests passed successfully.

Versioning

Current version: 1.1.0

- Patch updates: 1.1.1, 1.1.2 etc. for small fixes - Minor updates: 1.2.0 for added features - Major updates: 2.0.0 for breaking changes

Example with Tkinter

from Tkinter_helper import Tkinter_helper
from simple_storage import save, load

gui = Tkinter_helper("Example", 400, 200)

_, name_var = gui.entry("name", default_text=load("name", ""))

def save_name():
    save("name", name_var.get())

gui.button("save", text="Save", action=save_name)

gui.root.mainloop()

This shows how user input can be saved and loaded seamlessly using simple_storage.

Design Goals

Beginner-friendly and easy to understand
Minimal code and simple API
Human-readable storage format
Safe defaults and error handling
Practical for small Python projects

License

Free to use for learning and personal projects.