MiniS3 Tutorial

中文版

MiniS3 is a deterministic Python teaching implementation of core S3-style object-storage mechanisms: flat keys, versioning, listing, multipart composite ETags, conditional CAS, manually ticked lifecycle expiration, and crash-consistent local publication. It exposes a direct Python API rather than an HTTP/S3-compatible server.

Install

You need Python 3.12+ and uv.

git clone https://github.com/system-in-miniature/mini-s3.git
cd mini-s3
uv sync --dev

First experiment

uv run python labs/lab_versioning.py

The script writes two versions, creates a delete marker, shows that an ordinary GET now raises NoSuchKey, and then retrieves the retained first version by its version ID.

Reading path

Use the repository tour for the code layout, then read the concept mapping. Run all five labs before reading the differences chapter so that a successful local experiment is not mistaken for Amazon S3 compatibility.

The English README contains the complete M2 scope and minimal API example. The design history archive reflects construction-time plans; canonical docs and tests define current behavior.