Forem: Water Run

Introducing RunOnce: A Frictionless Tool for Running Disposable Scripts

Water Run — Fri, 20 Mar 2026 01:31:50 +0000

Writing a script used to take half a day — and once written, it would be reused again and again. Back then, the overhead of creating a new file, naming it, and finding a place to store it was negligible compared to the time spent writing the code itself. Things are fundamentally different now.

While LLMs may still struggle with large-scale engineering codebases, a focused, single-purpose script of a few dozen to a few hundred lines is something any reasonably capable model can produce effortlessly. Need to aggregate statistics from a directory? Write a script. Remove image backgrounds? Write a script. Even manipulate an Excel file — write a script. Custom code has never been this cheap to produce, and its lifecycle has shrunk to a single use. So much so that the combined effort of creating a file, running it, and deleting it afterward may actually exceed the effort of writing the script itself. Wouldn't it be ideal to simply open an editor, paste the code, hit run, and be done with it?

Introducing RunOnce — a tool designed precisely for running these disposable, one-off scripts with minimal friction.

RunOnce is available on the Microsoft Store as a free download. Built on the standard WinUI 3 framework, it integrates seamlessly with Windows 11.

Upon installation, a new entry — "Run Code Here" — will appear in your right-click context menu. For example, suppose you need a script to generate various asset images from a logo. Simply right-click in the target directory, select "Run Code Here," and an editor will open. Right-click in the blank area to paste your code, then press Ctrl+Enter. Done.

It really is that straightforward. RunOnce automatically detects the programming language, invokes the appropriate runtime, executes the script, and cleans up any temporary files upon completion. The only prerequisite is that the corresponding language runtime is installed on your system.

In practice, most LLM-generated scripts are written in Python, whose extensive ecosystem of third-party libraries makes it the ideal choice for quick, ad-hoc tasks. That said, RunOnce also supports automatic detection and execution of Lua, Batch (.bat), PowerShell, Nim, and Go, catering to a range of preferences and requirements.

An editor must be editable — and RunOnce honors that principle. The built-in editor provides basic syntax highlighting for quick review and minor edits, such as adjusting input_file or output_file values. It is intentionally minimal: if more substantial changes are needed, it is almost always faster and more reliable to simply ask the LLM to regenerate the script.

RunOnce also supports passing command-line arguments to scripts, should your use case require it — though scripts that accept parameters tend to be less "disposable" by nature, as parameterization often implies the intent to run them more than once.

One important consideration concerns file path handling. By default, RunOnce operates in "Ensure Cleanup" mode, placing temporary script files in the system's temporary directory. Even if cleanup fails due to an unexpected error, the residual files remain out of sight. This mode works well for the vast majority of scripts.

However, if your script contains statements that resolve the script's own path — such as os.path.abspath(__file__) in Python — you should switch to "Ensure Compatibility" mode. In this mode, the temporary file is placed in a more accessible location. Do ensure the terminal closes normally after execution; otherwise, the temporary file may not be cleaned up automatically and will require manual deletion.

RunOnce is open source under the GPL v3 license, available on GitHub at GitHub - Water-Run/RunOnce: 一次运行 -- 随时随地的运行大模型生成的"一次性"程序. · GitHub. If you find the project useful, a ⭐ Star on GitHub would be greatly appreciated.

tiny tool to package your code for LLM prompts: pmc(pack-my-code)

Water Run — Sun, 08 Mar 2026 09:40:50 +0000

As code-focused large language models support ever-longer context windows (the recently released Claude Opus/Sonnet 4.6 and GPT 5.3 CodeX are big improvements; previously anything over ten thousand lines of context basically triggered “Alzheimer’s”), it’s becoming more common to just copy entire projects into a prompt and feed them to an LLM. Automated coding tools like OpenCode are token-hungry monsters; one big advantage of manual prompting is that you can curate a PLAN-BUILD flow yourself and save money. Manually copying code file by file is obviously tedious, and many nonstandard doc comments don’t include file hierarchy info, which can leave the model confused. There are already similar tools out there, but many are quite heavy. I wrote a lightweight, few-hundred-line binary tool called pmc (pack-my-code) that makes it easy to package your project’s code into a prompt. GitHub. You can download the binaries from Releases and add them to your PATH. It’s packaged with luainstaller.

Usage

It’s simple and intuitive.

Basic usage, in the directory you want to export:

pmc

Then press Ctrl+Shift+C. Of course, pmc also supports some slightly more advanced features. In fact, even in the default case above, it already does the following:

Equivalent to pmc . (the current working directory)
Respects .gitignore (requires a git environment)
Prints to the terminal instead of redirecting to a file
Does not output a tree structure
Does not output statistics
Wraps each file’s code in standard Markdown code blocks
Displays file paths relative to the execution directory
Does not additionally exclude or include only specific file types

These behaviors are configurable. Check the README for more usage details, or run with the -h flag after installation, including the special YAML mode. Overall it’s a very simple little tool, but at least for me it’s quite handy. :)

A Much Better Windows tree Command that Implemented in Rust (tree++)

Water Run — Tue, 13 Jan 2026 09:19:54 +0000

tree++: A Much Better Windows `tree` Command

As a 40-year-old software, the functionality of Windows' native tree command has essentially remained stuck in the 1980s:

PS C:\Users\linzh> tree /?
Graphically displays the folder structure of a drive or path.

TREE [drive:][path] [/F] [/A]

   /F   Display the names of the files in each folder.
   /A   Use ASCII instead of extended characters.

The functionality of the only two parameters /F and /A is clearly insufficient. As a tool extremely useful for describing project architecture and writing prompts in today's LLM era, a tree command without even directory exclusion functionality becomes directly unusable when facing modern project build systems with target, node_modules, .vs, etc.

Additionally, it's not particularly fast.

Therefore, over the past half month, I implemented this project with Claude Opus 4.5: tree++: A Much Better Windows tree Command.

And yes, it's written in Rust :-)

Links:

GitHub

What Makes It Better

More Features: Covers basically all commonly used functions, including advanced features like output to file

Quick reference of tree++ supported parameters:

Option Set (Equivalent Forms)	Description
`--help` `-h` `/?`	Show help information
`--version` `-v` `/V`	Show version information
`--ascii` `-a` `/A`	Draw the tree using ASCII characters
`--files` `-f` `/F`	Show files
`--full-path` `-p` `/FP`	Show full paths
`--human-readable` `-H` `/HR`	Show file sizes in human-readable form
`--no-indent` `-i` `/NI`	Do not show tree connector lines
`--reverse` `-r` `/R`	Sort in reverse order
`--size` `-s` `/S`	Show file size (bytes)
`--date` `-d` `/DT`	Show last modified date
`--exclude` `-I` `/X`	Exclude matching files
`--level` `-L` `/L`	Limit recursion depth
`--include` `-m` `/M`	Show only matching files
`--disk-usage` `-u` `/DU`	Show cumulative directory size
`--report` `-e` `/RP`	Show trailing summary statistics
`--prune` `-P` `/P`	Prune empty directories
`--no-win-banner` `-N` `/NB`	Hide the Windows-native tree banner output
`--silent` `-l` `/SI`	Silent terminal output (use with `output`)
`--output` `-o` `/O`	Output results to a file (`.txt`, `.json`, `.yml`, `.toml`)
`--batch` `-b` `/B`	Use batch mode
`--thread` `-t` `/T`	Number of scan threads (batch mode, default 8)
`--gitignore` `-g` `/G`	Honor `.gitignore`

Parameters support traditional DOS style, Unix short, and Unix long forms, primarily for compatibility with the original tree command style

Faster: The Rust implementation itself is considerably faster than the old COM-based original; abandoning real-time streaming output (commonly used when outputting to files) allows multi-threaded mode to be even many times faster

Performance comparison (using C:\Windows as an example):

Type	Time (`ms`)	Multiplier
`tree /f` (Windows Native)	`20721.90`	`1.00x`
`treepp /f`	`7467.99`	`2.77x`
`treepp /f /nb`	`7392.34`	`2.80x`
`treepp /f /nb /b`	`3226.38`	`6.42x`
`treepp /f /nb /b /t 1`	`9123.00`	`2.27x`
`treepp /f /nb /b /t 2`	`5767.71`	`3.59x`
`treepp /f /nb /b /t 4`	`3948.73`	`5.25x`
`treepp /f /nb /b /t 8`	`3166.81`	`6.54x`
`treepp /f /nb /b /t 16`	`2704.67`	`7.66x`

On this basis, tree++ is fully compatible with the original tree (diff-level output consistency): identical valid commands (excluding failed commands and help commands) produce identical results. This includes boilerplate information (opening volume information, ending no-subfolders information), the original quirky DOS-style paths, tree structure representation, and the behavior of the native /F and /A parameters, etc.

Quick Start

Installation

Download from GitHub Release:

Extract, place in a suitable path, and add to environment variables.

Open Windows Terminal and run treepp /v. If you see the corresponding output, installation is complete.

PS C:\Users\linzh> treepp /v
tree++ version 0.1.0

A much better Windows tree command.

author: WaterRun
link: https://github.com/Water-Run/treepp

Usage

Refer to documentation: Options Documentation

Some simple examples:

Basic usage: tree and treepp /f, behaving identically to native

PS D:\data\temp\tempDir> # tree++
PS D:\data\temp\tempDir> treepp
Folder PATH listing for volume Storage
Volume serial number is 26E9-52C1
D:.
└─Tempdir
PS D:\data\temp\tempDir> treepp /f
Folder PATH listing for volume Storage
Volume serial number is 26E9-52C1
D:.
│  TEMP_FILE.txt
│
└─Tempdir
        tempfile.txt

PS D:\data\temp\tempDir> # Native Windows tree
PS D:\data\temp\tempDir> tree
Folder PATH listing for volume Storage
Volume serial number is 26E9-52C1
D:.
└─Tempdir
PS D:\data\temp\tempDir> tree /f
Folder PATH listing for volume Storage
Volume serial number is 26E9-52C1
D:.
│  TEMP_FILE.txt
│
└─Tempdir
        tempfile.txt

PS D:\data\temp\tempDir> # Diff-level identical output

Exclude code, output desired information: Using tree++ project directory as example

PS D:\data\Rust\tree++> # Honor .gitignore and exclude .git and .release directories
PS D:\data\Rust\tree++> treepp /f /g /x .git /x .release
Folder PATH listing for volume Storage
Volume serial number is 26E9-52C1
D:.
│  .gitignore
│  Cargo.lock
│  Cargo.toml
│  LICENSE
│  OPTIONS-zh.md
│  OPTIONS.md
│  README-zh.md
│  README.md
│
├─prompts
│      编码规范.md
│
├─src
│      cli.rs
│      config.rs
│      error.rs
│      main.rs
│      output.rs
│      render.rs
│      scan.rs
│
└─tests
        compatibility_test.rs
        functional_test.rs
        performance_test.rs

PS D:\data\Rust\tree++>

Change style: Modify style, include size information, remove native boilerplate, etc. (accessing from Desktop)

PS C:\Users\linzh\Desktop> # Same base parameters, change style, access from Desktop
PS C:\Users\linzh\Desktop> treepp D:\data\Rust\tree++ /f /g /x .git /x .release /s /hr /nb /rp
D:\DATA\RUST\TREE++
│  .gitignore        1.7 KB
│  Cargo.lock        18.6 KB
│  Cargo.toml        798 B
│  LICENSE        35.0 KB
│  OPTIONS-zh.md        18.0 KB
│  OPTIONS.md        19.7 KB
│  README-zh.md        4.2 KB
│  README.md        4.6 KB
│
├─prompts
│      编码规范.md        8.6 KB
│
├─src
│      cli.rs        76.4 KB
│      config.rs        50.7 KB
│      error.rs        40.0 KB
│      main.rs        16.5 KB
│      output.rs        32.7 KB
│      render.rs        151.5 KB
│      scan.rs        92.3 KB
│
└─tests
        compatibility_test.rs        58.7 KB
        functional_test.rs        68.0 KB
        performance_test.rs        45.0 KB

3 directory, 19 files in 0.003s
PS C:\Users\linzh\Desktop>

Scan C:/Windows and output to file (silent terminal)

PS C:\Users\linzh\Desktop> # Default streaming output to text file
PS C:\Windows> treepp /f /o D:\txt_output.txt /si
PS C:\Users\linzh\Desktop> # Batch mode output to JSON, faster
PS C:\Windows> treepp /f /o D:\txt_output.json /b /si

If this project helps you, please give it a Star to show your support :-)
For any issues, feel free to submit an ISSUE

pptx2png: Convert your .pptx to .png images with one click

Water Run — Sun, 28 Dec 2025 05:11:50 +0000

`pptx2png`: Convert your `.pptx` to `.png` images with one click

GitHub

pptx2png is a Windows desktop application designed to export your .pptx slides as .png images with a single click. It is simple and straightforward:

Download

You can also use it as a Python library in your code. See:

PyPI

Example:

pip install pptx2png

import pptx2png


pptx2png.topng(
    pptx="your_presentation.pptx",
    output_dir="./output",
    slide_range=[1, 5],
    scale=2
)

pptx2png.whatis() # print info

luainstaller 2.0: Package Your .lua Scripts into Native Binaries

Water Run — Mon, 15 Dec 2025 07:36:44 +0000

There are two ways to package .lua scripts into binaries: the traditional srlua, which concatenates the Lua interpreter with the code, and the more modern luastatic, which performs real compilation. However, each of them has its own problems:

srlua
- Can only package a single .lua file
- Requires manual compilation
luastatic
- Requires a build environment
- Linux-only

luainstaller is an open-source Python library that wraps precompiled srlua and provides support for luastatic. It can be used as a command-line tool, a graphical application, or via a Python library API, and includes dependency analysis and a single-file packaging engine. It works out of the box on both Windows and Linux.

Usage is very simple. Suppose you have an entry script a.lua; a.lua depends on b.lua, b.lua depends on c.lua, and so on.
You do not need to manually compile srlua (or configure a luastatic environment), manually analyze dependencies, merge all code into a single .lua script (for srlua), and then invoke srlua or luastatic. You only need:

pip install luainstaller

Then

luainstaller build a.lua

And that’s it.
You do not even need to type commands in the terminal:

luainstaller-gui

This will launch a Tkinter-based graphical interface that includes the basic functionality.
luainstaller also supports more parameters and features, including a logging system (recorded using SimpSave), selectable engines, and more.

Refer to the detailed documentation on GitHub for complete usage instructions. If you find the project helpful, consider giving it a Star to show your support :-)

luainstaller: A Python Tool for Packaging Lua Scripts into Standalone Executables with Dependency Analysis

Water Run — Sat, 06 Dec 2025 14:42:13 +0000

`luainstaller`: Python Library for Packaging `.lua` into Binaries with Dependency Analysis

luainstaller is an open-source Python library that follows the LGPL license. It wraps luastatic and provides the capability to package .lua files into executables.

luainstaller can be used:

As a command-line tool
As a graphical tool
As a library imported into your projects

Due to limitations of luastatic itself, luainstaller can only be used on linux platforms; if you need to use it on Windows, consider wsl

Installation

luainstaller is published on pypi. Install it using pip:

pip install luainstaller

After installation, run in the terminal:

luainstaller

You should get the output:

luainstaller by WaterRun. Version 1.0.
Visit: https://github.com/Water-Run/luainstaller :-)

Prepare the luastatic environment: luarocks install luastatic

Getting Started Tutorial

The workflow of luainstaller is very simple:

Analyze the current environment and obtain dynamic libraries
Scan the entry script recursively to build dependency analysis (if automatic dependency analysis is not disabled)
Merge manually configured dependency scripts to generate the dependency list
Call luastatic to compile according to the dependency list and output to the specified directory

As shown:

                    {Environment Analysis}
                         |
                  test.lua <Entry Script>
                         |
                 {Automatic Dependency Analysis}
                         |
        ┌───────────────────────────────────┐
        |                                   |
        |        ┌──> require("utils/log")  |
        |        |          │               |
        |        |     utils/log.lua        |
        |        |          │               |
        |        |     require("utils/time")|
        |        |          │               |
        |        |     utils/time.lua       |
        |        |                          |
        |        |                          |
        |        └──> require("core/init")  |
        |                   │               |
        |            core/init.lua          |
        |            core/config.lua        |
        |            core/db.lua            |
        |                                   |
        └───────────────────────────────────┘
                         |
               (Manual Dependency Configuration)
                         |
                  extra/plugin.lua
                         |
                         ↓
                    <Dependency List>
    -------------------------------------------------
    utils/log.lua
    utils/time.lua
    core/init.lua
    core/config.lua
    core/db.lua
    extra/plugin.lua
    -------------------------------------------------
                         ↓
             {Invoke luastatic Compile Command}

luastatic test.lua utils/log.lua utils/time.lua core/init.lua core/config.lua core/db.lua extra/plugin.lua /usr/lib64/liblua.so -o test.exe

About Automatic Dependency Analysis

luainstaller has limited automatic dependency analysis capability. The engine matches require statements in the following forms, performs recursive searching, and obtains the dependency list:

require '{pkg_name}'
require "{pkg_name}"
require('pkg_name')
require("pkg_name")
require([[pkg_name]])

Imports using pcall are also treated as equivalent to require imports

Other forms will cause errors, including dynamic dependencies. In such cases, you should disable automatic dependency analysis and manually add the required dependencies.

Using as a Graphical Tool

The simplest way to use it is through the GUI.
luainstaller provides a graphical interface implemented with Tkinter. After installation, enter in the terminal:

luainstaller-gui

This will launch it.

The GUI interface only includes basic features

Using as a Command-Line Tool

The primary way to use luainstaller is as a command-line tool. Simply enter in the terminal:

luainstaller

Or luainstaller-cli, both are equivalent

Command Set

Get Help

luainstaller help

This will output usage help.

Get Logs

luainstaller logs [-limit <limit number>] [-asc]

This will output the operation logs stored by luainstaller.

Parameters:

limit: The number of outputs to limit, a positive integer
asc: In chronological order (default is reverse order)

The logging system uses SimpSave

Dependency Analysis

luainstaller analyze <entry script> [-max <max dependencies>] [--detail]

This will perform dependency analysis and output the analysis list.

Parameters:

max: Maximum dependency tree limit, a positive integer
detail: Detailed runtime output

By default, analyzes up to 36 dependencies

Execute Compilation

luainstaller build <entry script> [-require <dependent .lua scripts>] [-max <max dependencies>] [-output <output binary path>] [--manual] [--detail]

Parameters:

entry script: The corresponding entry script, starting point of dependency analysis
require: Dependent scripts, if the corresponding script has been automatically analyzed by the analysis engine, it will be skipped. Multiple scripts separated by commas
max: Maximum dependency tree limit, a positive integer. By default, analyzes up to 36
output: Specifies the output binary path, defaults to an executable file with the same name as the .lua in the current directory, automatically adding .exe suffix on Windows platform
manual: Do not perform dependency analysis, directly compile the entry script unless forcibly specified using -require
detail: Detailed runtime output

Examples:

luainstaller hello_world.lua

Compiles hello_world.lua into an executable hello_world (Linux) or hello_world.exe (Windows) in the same directory.

luainstaller a.lua -require b.lua,c.lua --manual

Packages a.lua together with dependencies b.lua and c.lua into a binary without automatic dependency analysis. The behavior is completely consistent with using luastatic directly.

luainstaller test.lua -max 100 -output ../myProgram --detail

Analyzes test.lua with up to 100 dependency items, packages it into the myProgram binary in the parent directory, and displays detailed compilation information.

Using as a Library

luainstaller can also be imported as a library into your scripts:

import luainstaller

And provides a functional API.

API Reference

`get_logs()`

Get logs

def get_logs(limit: int | None = None,
             _range: range | None = None,
             desc: bool = True) -> list[dict[str, Any]]:
    r"""
    Returns luainstaller logs.

    :param limit: Return number limit, None means no limit
    :param _range: Return range limit, None means no limit
    :param desc: Whether to return in reverse order
    :return list[dict[str, Any]]: List of log dictionaries
    """

Example:

import luainstaller

log_1: dict = luainstaller.get_logs()  # Get all logs in reverse order
log_2: dict = luainstaller.get_logs(limit=100, _range=range(128, 256), desc=False)  # Get up to 100 logs in order, within the range of 128 to 256

`analyze()`

Execute dependency analysis (corresponds to CLI's luainstaller analyze)

def analyze(entry: str,
            max_deps: int = 36) -> list[str]:
    r"""
    Execute dependency analysis on the entry script.

    :param entry: Entry script path
    :param max_deps: Maximum recursive dependency count, default 36
    :return list[str]: List of dependency script paths obtained from analysis
    """

Example:

import luainstaller

deps_1: list = luainstaller.analyze("main.lua")  # Dependency analysis, analyzes up to 36 dependencies by default
deps_2: list = luainstaller.analyze("main.lua", max_deps=112)  # Execute dependency analysis, modify maximum dependency analysis count to 112

`build()`

Execute compilation (corresponds to CLI's luainstaller build)

def build(entry: str,
          requires: list[str] | None = None,
          max_deps: int = 36,
          output: str | None = None,
          manual: bool = False) -> str:
    r"""
    Execute script compilation.

    :param entry: Entry script
    :param requires: Manually specify dependency list; if empty, rely only on automatic analysis
    :param max_deps: Maximum dependency tree analysis count
    :param output: Output binary path, None uses default rule
    :param manual: Disable automatic dependency analysis
    :return str: Path of the generated executable file
    """

Example:

import luainstaller

# Simplest build method, automatically analyzes dependencies and generates an executable with the same name as the script
luainstaller.build("hello.lua")

# Manual mode: Disable automatic dependency analysis, compile only with scripts specified in requires
luainstaller.build("a.lua", requires=["b.lua", "c.lua"], manual=True)

SimpSave 10: A “ready-to-use” lightweight database, now supporting multiple engine options (including SQLite).

Water Run — Sun, 09 Nov 2025 10:06:25 +0000

How to persist data in Python?
The most standard method is naturally to use a database. However, for many scenarios such as simple scripts or student assignments, even something as lightweight as TinyDB might be too "heavy" and cumbersome.
SimpSave is a featherweight database with a functional minimalist API that is extremely easy to pick up (almost the simplest form of data persistence), featuring "read-and-use" capability (storage and retrieval preserve types, no need for type conversion), making it very suitable for use in such scenarios. SimpSave 10 brings multi-engine support, and support for SQLITE gives it a certain level of production-grade capability.
"Read-and-use" example:

import simpsave as ss
ss.write('key', [1, 2, 3])
print(ss.read('key1').append(4)) # [1, 2, 3, 4]

If the project helps you, please feel free to give it a Star on GitHub :)
https://github.com/Water-Run/SimpSave

SimpSave Version 10

Introduction

SimpSave is a Python featherweight key-value storage database for Python basic variables, leveraging Python's native powerful data structure support, "read-and-use", extremely easy to get started with, very suitable for use in various small scripts such as student assignments, or as configuration files, etc.
SimpSave 10 is a major upgrade, bringing optional engine capabilities: the engine wrapper for sqlite provides it with a usable level in some lightweight production environments (although the functional API has no connection pool mechanism); while for use in simple environments, optional dependencies can maintain the original zero-dependency minimalist characteristics.

Core Features

Extremely lightweight: Core code is concise and efficient, minimal installation has no dependencies
Extremely easy to get started: Functional API (read(), write(), etc.) is very intuitive, almost no learning curve, can be used directly

  import simpsave as ss
  ss.write('key1', 'value1')
  ss.read('key1')  # 'value1'

Read-and-use: Stored type and retrieved type remain consistent, no need for type judgment and conversion, further simplifying usage

  import simpsave as ss
  ss.write('key1', 1)
  type(ss.read('key1')).__name__  # 'int'
  ss.read('key1') + 1  # 2

Multi-engine support: From the dependency-free lightweight XML engine to the production-performance SQLITE engine. SimpSave automatically selects the engine based on file extension, no manual configuration needed

Installation

SimpSave is published on PyPI, install using pip:

pip install simpsave

Then, import it in your project:

import simpsave as ss  # commonly aliased as 'ss'

And you can start using it.

Optional Dependencies

SimpSave supports optional dependencies, which can be selected for installation based on actual needs:

pip install simpsave                # Install all dependencies
pip install simpsave[XML]           # Minimal: only includes XML engine (requires xml.etree)
pip install simpsave[INI]           # Includes XML and INI engines (no extra dependencies)
pip install simpsave[YML]           # Includes XML and YML engines (requires PyYAML)
pip install simpsave[TOML]          # Includes XML and TOML engines (requires tomli)
pip install simpsave[JSON]          # Includes XML and JSON engines (no extra dependencies)
pip install simpsave[SQLITE]        # Includes XML and SQLITE engines (requires sqlite3)

The SQLITE engine requires the SQLite environment to be deployed on the local machine in advance

Quick Start Example

The following code provides a quick start example for SimpSave:

import simpsave as ss

# Write data
ss.write('name', 'Alice')
ss.write('age', 25)
ss.write('scores', [90, 85, 92])

# Read data
print(ss.read('name'))     # Alice
print(ss.read('age'))      # 25
print(ss.read('scores'))   # [90, 85, 92]

# Check keys
print(ss.has('name'))      # True
print(ss.has('email'))     # False

# Delete key
ss.remove('age')
print(ss.has('age'))       # False

# Regex matching
ss.write('user_admin', True)
ss.write('user_guest', False)
print(ss.match(r'^user_'))  # {'user_admin': True, 'user_guest': False}

# Use different files (automatically select corresponding engine)
ss.write('theme', 'dark', file='config.yml')
print(ss.read('theme', file='config.yml'))  # dark

# Use :ss: mode (save to installation directory)
ss.write('键1', '值1', file=':ss:config.toml') # Use Chinese key names and TOML engine
print(ss.read('键1', file=':ss:config.toml'))  # 值1

# Delete files
ss.delete()
ss.delete(file='config.yml')

If you have some programming foundation, I believe SimpSave's extreme intuitiveness has already taught you its basic usage.

Engines

SimpSave 10 supports multiple storage engines, which can be selected based on actual needs. Engines are stored in the ss.ENGINE enumeration:

Engine Name	File Format	Dependencies	Description
`XML`	`.xml`	`xml.etree` (built-in)	Uses XML format for storage, lightweight and requires no extra dependencies
`INI`	`.ini`	`configparser` (built-in)	Uses INI format for storage, not fully compatible with `Unicode`
`YML`	`.yml`	`PyYAML`	Uses YAML format for storage
`TOML`	`.toml`	`tomli`	Uses TOML format for storage
`JSON`	`.json`	`json` (built-in)	Uses JSON format for storage
`SQLITE`	`.db`	`sqlite3` (built-in)	Uses SQLite database, has production-grade performance

Automatic Engine Selection

SimpSave automatically selects the appropriate engine based on the file extension of the file parameter:

import simpsave as ss

ss.write('key1', 'value1', file='data.yml')     # Automatically uses YML engine
ss.write('key2', 'value2', file='config.toml')  # Automatically uses TOML engine
ss.write('key3', 'value3', file='data.db')      # Automatically uses SQLITE engine

Principles

SimpSave uses key-value pairs to save Python's basic type data. Depending on the chosen engine, data will be stored in different formats.

By default, data is saved to the __ss__.xml file in the current working directory

`:ss:` Mode

As with the old version, SimpSave retains support for the unique :ss: path mode: if the file path starts with :ss: (such as :ss:config.json), the file will be saved in the SimpSave installation directory, thus ensuring cross-environment compatibility.

import simpsave as ss

ss.write('key1', 'value1', file=':ss:config.yml')  # Save to SimpSave installation directory
print(ss.read('key1', file=':ss:config.yml'))      # Read from installation directory

:ss: mode requires SimpSave to be installed via pip

Data Types

SimpSave fully supports Python's built-in basic types, including:

int
float
str
bool
list (including nested, items within nesting also need to be Python's basic type data, same below)
dict
tuple
None

When reading data, SimpSave automatically restores it to the original Python type, achieving "read-and-use".

API Reference

Writing Data

The write function is used to write key-value pairs to a specified file:

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

If the specified storage file does not exist, it will be created automatically.

Parameter Description

key: The key to be stored, must be a valid string
value: The value to be stored, supports Python basic types
file: The file path to write to, defaults to __ss__.xml, can use :ss: mode. The engine will be automatically selected based on the file extension

Return Value

Returns True if written successfully, returns False if failed.

Exceptions

ValueError: Value is not a Python basic type value
IOError: Write error
RuntimeError: Other runtime errors, such as selected engine not installed, etc.

Example

import simpsave as ss

ss.write('key1', 'Hello 世界')           # Write Unicode string
ss.write('key2', 3.14)                  # Write float
ss.write('key3', [1, 2, 3, '中文'])      # Write list containing Chinese
ss.write('key4', {'a': 1, 'b': 2})      # Write dictionary

# Use different engines
ss.write('config', 'value', file='settings.yml')   # Use YML engine
ss.write('data', 100, file='cache.db')             # Use SQLITE engine

If the file does not exist, SimpSave will create it automatically.

Reading Data

The read function is used to read data from a specified file:

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

Parameter Description

key: The key name to read.
file: The file path to read from, defaults to __ss__.xml.

Return Value

Returns the value corresponding to the specified key, automatically restored to the original type.
If the key does not exist, returns None.

Exceptions

IOError: Read error
RuntimeError: Other runtime errors, such as selected engine not installed, etc.

Example

import simpsave as ss

print(ss.read('key1'))  # Output: 'Hello 世界'
print(ss.read('key2'))  # Output: 3.14
print(ss.read('key3'))  # Output: [1, 2, 3, '中文']

# Read from different files
value = ss.read('config', file='settings.yml')

Checking if Key Exists

The has function is used to check if a certain key exists in the file:

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

Parameter Description

key: The key name to check.
file: The file path to check, defaults to __ss__.xml.

Return Value

Returns True if the key exists, returns False if it does not exist.

Exceptions

IOError: Read error
RuntimeError: Other runtime errors, such as selected engine not installed, etc.

Example

import simpsave as ss

print(ss.has('key1'))        # Output: True
print(ss.has('nonexistent')) # Output: False

Deleting Keys

The remove function is used to delete a key and its corresponding value from a file:

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

Parameter Description

key: The key name to delete.
file: The file path to operate on, defaults to __ss__.xml.

Return Value

Returns True if deleted successfully, returns False if failed.

Exceptions

IOError: Write error
RuntimeError: Other runtime errors, such as selected engine not installed, etc.

Example

import simpsave as ss

ss.remove('key1')  # Delete key 'key1'
print(ss.has('key1'))  # Output: False

Regex Matching Keys

The match function can match all keys that meet the conditions through regular expressions and return the corresponding key-value pairs:

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

Parameter Description

re: Regular expression string, used to match key names. Empty string means match all keys.
file: The file path to operate on, defaults to __ss__.xml.

Return Value

Returns a dictionary containing all matched key-value pairs.

Exceptions

IOError: Read error
RuntimeError: Other runtime errors, such as selected engine not installed, etc.

Example

import simpsave as ss

ss.write('user_name', 'Alice')
ss.write('user_age', 25)
ss.write('admin_name', 'Bob')

result = ss.match(r'^user_.*')  # Match all keys starting with 'user_'
print(result)  # Output: {'user_name': 'Alice', 'user_age': 25}

all_data = ss.match()  # Get all key-value pairs
print(all_data)

Deleting Files

The delete function can delete the entire storage file:

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

Parameter Description

file: The file path to delete, defaults to __ss__.xml.

Return Value

Returns True if deleted successfully, returns False if failed.

Exceptions

IOError: Delete error
RuntimeError: Other runtime errors, such as selected engine not installed, etc.

Example

import simpsave as ss

ss.delete()  # Delete the default save file
ss.delete(file='config.yml')  # Delete specified file

Exception Handling

SimpSave may throw the following exceptions during operation. Understanding these exceptions helps write more robust code.

Common Exception Types

`ValueError`

Thrown when the passed value is not a Python basic type.

Trigger Scenarios:

Attempting to store unsupported complex objects (such as custom class instances, functions, etc.)
The passed value exceeds the type range supported by the engine

Example:

import simpsave as ss

class CustomClass:
    pass

try:
    ss.write('key1', CustomClass())  # Throws ValueError
except ValueError as e:
    print(f"Error: {e}")

`IOError`

Thrown when file read/write operations fail.

Trigger Scenarios:

Insufficient file permissions
Insufficient disk space
File occupied by other processes
File path does not exist or is invalid

Example:

import simpsave as ss

try:
    ss.read('key1', file='/root/protected.db')  # May throw IOError
except IOError as e:
    print(f"File operation error: {e}")

`RuntimeError`

Other runtime errors, usually engine internal errors or configuration issues.

Trigger Scenarios:

Engine initialization failed
Data format corrupted
Dependency library missing or version incompatible

Example:

import simpsave as ss

try:
    ss.write('key1', 'value1', file='data.unknown')  # May throw RuntimeError
except RuntimeError as e:
    print(f"Runtime error: {e}")

Exception Handling Best Practices

It is recommended to use try-except statements to handle possible exceptions:

import simpsave as ss

# Safe write
try:
    ss.write('key1', 'value1')
except ValueError as e:
    print(f"Value type error: {e}")
except IOError as e:
    print(f"File write failed: {e}")
except RuntimeError as e:
    print(f"Runtime error: {e}")

# Safe read
try:
    value = ss.read('key1')
    if value is None:
        print("Key does not exist")
except IOError as e:
    print(f"File read failed: {e}")
except RuntimeError as e:
    print(f"Runtime error: {e}")

Practice Suggestions

When using non-SQLITE engines, control data volume and complexity;

Before reading data, use has or try-except statements for safe reading:

import simpsave as ss
value = 'default value'
if ss.has('key_1'):
    value = ss.read('key_1')
else:
    ss.write('key_1', 'default value')

- When unable to confirm whether the corresponding file exists, use `try-except` combined with initialization statements.

Learn more, visit GitHub

Bat-KV: Lightweight Key-Value Store for Windows Batch

Water Run — Sun, 21 Sep 2025 16:12:37 +0000

`Bat-KV`: An Ultra-Lightweight Database for Windows Batch (`.bat`)

Windows batch scripting is notoriously tricky, especially when it comes to persisting simple data.

Bat-KV is an open-source, single-file key-value database designed for .bat scripts. It provides the basic CRUD operations, wraps some simple APIs, and is quick to pick up.

If this project helps you, consider giving it a Star on GitHub.

GitHub

Bat-KV Basics

Storage Files

File Extension: .bkv (Batch Key-Value)
Format: One key-value pair per line, separated by a backslash \

  username\Alice
  age\25
  city\Beijing

Default Filename: _BATKV.bkv
Encoding: ANSI recommended for platform compatibility
Key Constraints:
- Only English letters, digits, and underscores allowed
- Maximum length of 36 characters
- Case-sensitive

Naming Conventions

Public Functions: Start with BKV., e.g., BKV.New, BKV.Fetch
Private Functions: Start with BKV.Private., not intended for external use
Internal Variables: Start with BKV.Inner., not intended for external access
Return Variables:
- BKV_STATUS: Execution result (OK / NotOK)
- BKV_RESULT: Data returned by queries (e.g., BKV.Fetch value)
- BKV_ERR: Error detail if failure occurs, in the format Bat-KV ERR: [message]

Download & Installation

Getting Bat-KV

Go to the GitHub Release page
Download Bat-KV.zip
Extract and locate the core file Bat-KV.bat

Importing

Local Use: Place Bat-KV.bat in the same directory as your batch script, call it directly
Relative Path: If the file is in a subdirectory or parent directory, prefix the path
Global Use: Add the directory containing Bat-KV.bat to your system PATH environment variable

Example:

REM Current directory
call Bat-KV.bat :BKV.New

REM Subdirectory
call lib\Bat-KV.bat :BKV.New "mydata.bkv"

REM Parent directory
call ..\Bat-KV.bat :BKV.Fetch "username"

Quick Start

A minimal example including creating a database, writing, reading, and deleting data:

@echo off

REM Create database
call Bat-KV.bat :BKV.New
echo Create status: %BKV_STATUS%

REM Insert data
call Bat-KV.bat :BKV.Append "name" "Alice"
call Bat-KV.bat :BKV.Append "age" "25"

REM Read data
call Bat-KV.bat :BKV.Fetch "name"
echo Name: %BKV_RESULT%

REM Check key existence
call Bat-KV.bat :BKV.Include "email"
if "%BKV_RESULT%"=="No" (
    call Bat-KV.bat :BKV.Append "email" "alice@example.com"
)

REM Delete data
call Bat-KV.bat :BKV.Remove "age"
echo Remove status: %BKV_STATUS%

pause

API Quick Reference

`BKV.New`

Create a new database file. Existing files are not overwritten.

call Bat-KV.bat :BKV.New "config.bkv"

`BKV.Append`

Insert or update a key-value pair.

call Bat-KV.bat :BKV.Append "username" "Alice"

`BKV.Fetch`

Read the value of a given key.

call Bat-KV.bat :BKV.Fetch "username"
echo User: %BKV_RESULT%

`BKV.Remove`

Remove a key-value pair. Returns success even if the key does not exist.

call Bat-KV.bat :BKV.Remove "username"

`BKV.Include`

Check if a key exists.

call Bat-KV.bat :BKV.Include "db_host"
if "%BKV_RESULT%"=="No" (
    call Bat-KV.bat :BKV.Append "db_host" "localhost"
)

Full Documentation

For complete documentation and example programs, refer to the GitHub main repository and the scripts attached to the Release.

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

Water Run — Thu, 07 Aug 2025 13:15:26 +0000

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.

luaToEXE: Compile Lua Scripts to Standalone Windows Executables

Water Run — Thu, 07 Aug 2025 13:03:13 +0000

Introduction

The standard method to compile a .lua file into a standalone .exe with a built-in interpreter and no environment dependencies is to use srlua. However, srlua itself has not been updated for over a decade and does not provide precompiled binaries. Many community-compiled versions of srlua overlook dependency issues, resulting in missing DLL errors when running the compiled program on a machine without a Lua environment. Thus, it is not truly ready-to-use.

luaToEXE is an open-source project that wraps srlua, aiming to provide a simple solution for compiling .lua files into .exe files with a built-in interpreter.

Features:

Easy to use
The compiled .exe has no dependencies (tested in Windows sandbox environments)
Supports multiple Lua versions

The project consists of two sub-projects:

lua-to-exe: A Python library that provides API functions for conversion and a graphical user interface
exelua: A command-line tool with both 32-bit and 64-bit versions

Links:

GitHub
PyPi

Tutorial: lua-to-exe

Install using pip install lua-to-exe

Import the package in your project with import lua_to_exe (note the underscore)
Graphical interface: Run lua_to_exe.gui() to launch the GUI
- Includes file selection for input .lua and output .exe, and a convert button
- Dropdown to select the Lua version (-32 means 32-bit, and so on)

API: Call the lua_to_exe() function
- lua_to_exe(lua_file, exe_file, lua_version='5.1.5-64'). The arguments are the input .lua file, the output .exe file, and an optional Lua version (default is 5.1.5-64)
- Call all_available() to get a dictionary of all available Lua versions

Tutorial: exelua

Download the appropriate version of exelua from the Release page

Extract and add the directory to your environment variables, then restart your computer. Make sure the srlua folder is in the same directory

In the Windows terminal, run exelua -v. If a version number is output, the installation was successful
Run exelua -h for usage help, and exelua -list (the first run may take some time) to list all available versions

Run exelua -c <input.lua> <output.exe> [-lua <version>] to perform the conversion. The parameters are: the input .lua file path, the output .exe file path, and the optional -lua (if you want to specify the Lua version) and the corresponding version. For example, to convert helloworld.lua to helloworld.exe, the command can be exelua -c helloworld.lua helloworld.exe, which uses the default 5.1.5-64/5.1.5-32 Lua interpreter version.

Star Request :-/

If this project has helped you, please consider giving it a Star :)

Forem: Water Run

Introducing RunOnce: A Frictionless Tool for Running Disposable Scripts

tiny tool to package your code for LLM prompts: pmc(pack-my-code)

Usage

A Much Better Windows tree Command that Implemented in Rust (tree++)

tree++: A Much Better Windows tree Command

What Makes It Better

Quick Start

Installation

Usage

pptx2png: Convert your .pptx to .png images with one click

pptx2png: Convert your .pptx to .png images with one click

luainstaller 2.0: Package Your .lua Scripts into Native Binaries

luainstaller: A Python Tool for Packaging Lua Scripts into Standalone Executables with Dependency Analysis

luainstaller: Python Library for Packaging .lua into Binaries with Dependency Analysis

Installation

Getting Started Tutorial

About Automatic Dependency Analysis

Using as a Graphical Tool

Using as a Command-Line Tool

Command Set

Get Help

Get Logs

Dependency Analysis

Execute Compilation

Using as a Library

API Reference

get_logs()

analyze()

build()

SimpSave 10: A “ready-to-use” lightweight database, now supporting multiple engine options (including SQLite).

SimpSave Version 10

Introduction

Core Features

Installation

Optional Dependencies

Quick Start Example

Engines

Automatic Engine Selection

Principles

:ss: Mode

Data Types

API Reference

Writing Data

Parameter Description

Return Value

Exceptions

Example

Reading Data

Parameter Description

Return Value

Exceptions

Example

Checking if Key Exists

Parameter Description

Return Value

Exceptions

Example

Deleting Keys

Parameter Description

Return Value

Exceptions

Example

Regex Matching Keys

Parameter Description

Return Value

Exceptions

Example

Deleting Files

Parameter Description

Return Value

Exceptions

Example

Exception Handling

Common Exception Types

ValueError

IOError

RuntimeError

Exception Handling Best Practices

Practice Suggestions

tree++: A Much Better Windows `tree` Command

`pptx2png`: Convert your `.pptx` to `.png` images with one click

`luainstaller`: Python Library for Packaging `.lua` into Binaries with Dependency Analysis

`get_logs()`

`analyze()`

`build()`

`:ss:` Mode

`ValueError`

`IOError`

`RuntimeError`

`Bat-KV`: An Ultra-Lightweight Database for Windows Batch (`.bat`)

`BKV.New`

`BKV.Append`

`BKV.Fetch`

`BKV.Remove`

`BKV.Include`

Example of a SimpSave `.yml` File