Enhancement: Refactor file-per-step examples into true Git histories

[WSHAPER]

Problem Description

Currently, many examples are provided as a flat list of numbered files, where each file represents a single step in a tutorial.

While this shows the progression, it has some significant drawbacks for users trying to learn from the code:

1. Understanding Changes Adds Friction: To see what changed between "Step 1" and "Step 2," a user must manually diff the two files (e.g., diff 01_starting_point.py 02_functions_not_class.py). This is cumbersome and not possible on the GitHub web UI or mobile devices.

2. No Context (The "Why"): The reason for the change is lost. The commit history for all files is a single, unhelpful message.

3. Cluttered Repository: This pattern adds a large number of top-level files to the repository for what is essentially a single example.

Current Structure (Before)

The current file list for a single example looks something like this, with an uninformative commit history:

Name	Last commit message
...
01_starting_point.py	Added pythonic code example
02_functions_not_class.py	Added pythonic code example
03_use_context_manager.py	Added pythonic code example
04_use_eafp.py	Added pythonic code example
05_add_type_hints.py	Added pythonic code example
05_use_dataclass.py	Added pythonic code example
06_use_pathlib.py	Added pythonic code example
07_add_helpers.py	Added pythonic code example
08_add_logging.py	Added pythonic code example
10_final.py	Added pythonic code example
pyproject.toml	Added pythonic code example

Proposed Solution

I suggest refactoring each example (like the "pythonic" one above) into its own self-contained directory. This directory would contain the final code, but its true value would be in its Git history.

Each "step" (01_..., 02_...) would become a single, well-messaged commit.

This could be implemented in two primary ways:

1. (Simple) A single directory within this repo (e.g., examples/pythonic-refactor/) that contains the code. We would then build its history with clear, step-by-step commits.

2. (Advanced/Submodules) Each example becomes its own repository and is included here as a Git submodule.

Either approach achieves the goal. The key is to move the "steps" from filenames into the Git commit log.

Proposed Structure (After)

The file list would be much cleaner. All the numbered files would be gone, replaced by a single entry.

Name	Last commit message
...
examples/pythonic-refactor	Feat: Add pythonic refactor example
pyproject.toml	Added pythonic code example

Core Benefit: A Step-by-Step History

This change would transform the examples from static snapshots into interactive, step-by-step tutorials.

A user could cd into the example directory (or just view its history on the GitHub UI) and see a clear, logical progression of changes. This is especially valuable on mobile or web where running a diff command is not an option.

An ideal git log for the example directory would look like this:

$ git log --oneline --reverse

d0e1f2a (HEAD -> main) Step 1: Initial starting point for the script
c9d0e1f Step 2: Refactor from a class to standalone functions
b8c9d0e Step 3: Use a context manager for resource handling
a7b8c9d Step 4: Use EAFP (Easier to Ask for Forgiveness)
f6a7b8c Step 5: Add type hints for clarity
e5f6a7b Step 6: Use dataclass for data structures
d4e5f6a Step 7: Use pathlib instead of os.path
c3d4e5f Step 8: Add helper functions
b2c3d4e Step 9: Add logging for better introspection
a1b2c3d Step 10: Final cleanup and main function

With this structure, a user can:

• Read the commit messages to understand the "why" of each step.
• Click on any commit hash in the GitHub UI to see the exact diff of what changed for that step.
• git checkout <hash> locally to run the code at any point in its evolution.

This would be a massive improvement to the learning experience. Thanks for considering it!

[WSHAPER]

Just to add to this, I'm really passionate about this idea as I believe it would make the examples much more accessible and educational.

If you're open to this approach, I'd be happy to help contribute by refactoring one or two of the existing examples into this new commit-based format. Please let me know what you think!