SimpSave: Minimalistic and Immediate Python Data Persistence for Student Projects and Lightweight Scripts

Introduction

How can we save data in Python programs?

Without a doubt, the standard approach is to use a database. For lightweight storage needs, Python even comes with built-in support for SQLite. However, for most of our student projects or simple scripts, we’re far from dealing with "big data"—the data volume is often just dozens, tens, or even just a few entries, which can truly be called "micro data." In such cases, not only is SQLite overkill, but even something as lightweight as TinyDB may not be "portable" enough.

Python’s native data structures are already powerful enough to handle many everyday use cases. If there were a simple and extremely easy-to-use (almost zero learning curve) key-value database, which also wrapped some common features (such as regex matching on keys, or easily accessing the same database across .py files in different directories), and allowed data types to be consistent between storage and retrieval so that data can be "used as soon as it’s read" (i.e., database operations and value operations become unified), wouldn’t that be wonderful?

For these reasons, the project SimpSave was created. If this project helps you, please consider giving it a star to show your support! :)

("Read-and-Use Immediately" Example)

Documentation (from README.md)

---

SimpSave 4.0

Introduction

SimpSave 4.0 is a lightweight Python library for simple and efficient data persistence, now upgraded to use .yml files for storage. This shift from .ini to .yml brings enhanced support for Unicode and complex data structures, removing the need for UTF-8 or escape-based conversions.

Features

• Extremely Simple: The whole project remains under 200 lines of code.
• Easy to Use: Minimal setup and a clean, intuitive API for fast integration.
• Flexible and Lightweight: Supports all Python basic types, including Unicode, with no external dependencies (except PyYAML).
• YAML Native: Full native Unicode and structure support—no more escapes or encoding tricks.

Compatible with SimpSave version 4.0.

---

Installation

SimpSave 4.0 is available on PyPI and can be installed with:

pip install simpsave

Note: SimpSave 4.0 requires the PyYAML library, which will be installed automatically via pip.

To use SimpSave in your project:

import simpsave as ss  # Typically aliased as 'ss'

---

Principle

SimpSave 4.0 stores Python basic type variables in .yml files using key-value pairs. By default, it saves data in a file named __ss__.yml located in the current working directory. You can also specify a custom file path if needed.

Unique Path Mode

Just as before, SimpSave supports a unique :ss: path mode. If your file path starts with :ss: (e.g., :ss:config.yml), the file will be stored in the SimpSave installation directory, ensuring compatibility across environments.

Note: The :ss: mode requires SimpSave to be installed via pip.

Example of a SimpSave .yml File

key1:
  value: Hello 世界
  type: str
key2:
  value: 3.14
  type: float
key3:
  value: [1, 2, 3, "中文", {"a": 1}]
  type: list

When you read the data, SimpSave automatically converts it back to its original type. SimpSave 4.0 fully supports Python's built-in types including list, dict, and Unicode strings.

---

Usage Guide

Writing Data

The write function stores key-value pairs in a specified .yml file:

def write(key: str, value: any, *, file: str | None = None) -> bool:
    ...

Parameters:

• key: The key under which the value will be stored. Must be a valid YAML key.
• value: The value to store. Must be a Python basic type (e.g., int, float, str, list, dict).
• file: The path of the .yml file to write to. Defaults to __ss__.yml. Can also use :ss: mode.

Return Value:

• Returns True if the write operation is successful, otherwise False.

Example:

import simpsave as ss
ss.write('key1', 'Hello 世界')      # Writes a Unicode string
ss.write('key2', 3.14)             # Writes a float
ss.write('key3', [1, 2, 3, '中文']) # Writes a list with Unicode

If the file does not exist, SimpSave creates it automatically.

---

Reading Data

The read function retrieves a value from a specified .yml file:

def read(key: str, *, file: str | None = None) -> any:
    ...

Parameters:

• key: The key to read from the file.
• file: The path of the .yml file to read from. Defaults to __ss__.yml.

Return Value:

• Returns the value stored under the specified key, automatically converted to its original type.

Example:

import simpsave as ss
print(ss.read('key1'))  # Outputs: 'Hello 世界'
print(ss.read('key2'))  # Outputs: 3.14

---

Additional Features

Checking Key Existence

The has function checks if a key exists in the .yml file:

def has(key: str, *, file: str | None = None) -> bool:
    ...

Example:

import simpsave as ss
print(ss.has('key1'))          # Outputs: True
print(ss.has('nonexistent'))   # Outputs: False

---

Removing Keys

The remove function deletes a key (and its value) from the .yml file:

def remove(key: str, *, file: str | None = None) -> bool:
    ...

Example:

import simpsave as ss
ss.remove('key1')  # Removes the key 'key1'

---

Regular Expression Matching

The match function retrieves all key-value pairs that match a given regular expression:

def match(re: str = "", *, file: str | None = None) -> dict[str, any]:
    ...

Example:

import simpsave as ss
result = ss.match(r'^key.*')  # Matches all keys starting with 'key'
print(result)  # Outputs: {'key2': 3.14, 'key3': [1, 2, 3, '中文']}

---

Deleting Files

The delete function deletes the entire .yml file:

def delete(*, file: str | None = None) -> bool:
    ...

Example:

import simpsave as ss
ss.delete(file='__ss__.yml')  # Deletes the default file

---

Summary

SimpSave 4.0 is a simple, flexible, and lightweight library for persisting Python's basic data types using .yml files. With its easy-to-use API, native Unicode support, and compatibility with all common data types, SimpSave is perfect for small-scale, low-complexity projects.

Explore more on GitHub.