From d429c259afa3a095a7282eb96f271fb898d6bf25 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 23 May 2026 20:12:19 +0000 Subject: [PATCH 1/4] README: move highlight tip block to the top. Combine the "NEW in 3.1" banner with the prettyfmt callout into a single [!TIP] block placed right after the intro, and remove the now-duplicate prettyfmt tip that was below Key Features. --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 19d74d1..344e253 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,15 @@ It is simply a few functions and tricks that have repeatedly shown value in vari projects. The goal is not to give a comprehensive suite of utilities but simply to complement the standard libraries and fill in a few gaps. -✨ **NEW:** **Version 3.1** adds `atomic_write_text()`/`atomic_write_bytes()`, exposes -`__version__`, and supports Python 3.10-3.14. ✨ +> [!TIP] +> +> ✨ **NEW:** **Version 3.1** adds `atomic_write_text()`/`atomic_write_bytes()`, exposes +> `__version__`, and supports Python 3.10-3.14. ✨ +> +> If you're using strif, you might also want to check out +> [prettyfmt](https://github.com/jlevy/prettyfmt), another small library built on strif +> that has some extra functions for pretty, human-readable outputs for objects, sizes, +> times and dates, etc. ## Key Features @@ -38,13 +45,6 @@ complement the standard libraries and fill in a few gaps. That's all! They are all quite simple. The libs are all small so see pydoc strings or code for full docs. -> [!TIP] -> -> If you're using strif, you might also want to check out -> [prettyfmt](https://github.com/jlevy/prettyfmt), another small library built on strif -> that has some extra functions for pretty, human-readable outputs for objects, sizes, -> times and dates, etc. - ## Using strif with LLM Agents Strif is handy for code that generates files, which is increasingly often AI agent code. From defdcdc4f3824d99c63e13ae539e471529b76716 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 23 May 2026 20:16:49 +0000 Subject: [PATCH 2/4] README: lead with agent value and a complete feature overview. Merge the agent-usage framing and the Key Features list into a single "Why Use strif (Especially with Coding Agents)" section placed before everything else. Leads with the value for coding agents and a ready-to-paste prompt, then gives a concise complete overview of every capability (atomic files, base36/timestamped ids, hashing, AtomicVar, string utils, quoting) so an agent can understand the whole library in one read. Dropped the human-oriented code example. --- README.md | 62 ++++++++++++++++++++++--------------------------------- 1 file changed, 25 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 344e253..4dc1205 100644 --- a/README.md +++ b/README.md @@ -17,54 +17,42 @@ complement the standard libraries and fill in a few gaps. > that has some extra functions for pretty, human-readable outputs for objects, sizes, > times and dates, etc. -## Key Features +## Why Use strif (Especially with Coding Agents) -- **Atomic file operations** with handling of parent directories and backups. - This is essential for thread safety and good hygiene so partial or corrupt outputs are - never present in final file locations, even in case a program crashes. +Strif is a simple way to get better Python out of coding agents. It's small enough that +once you tell an agent to use it, it adopts it consistently—so you can enforce good habits +like atomic file writes, sortable timestamped ids, and stable hashing instead of hoping +the agent reinvents them correctly each time. A prompt as simple as this is usually enough: + +> Run `uv add strif` and review its docs, then always use it for atomic file writes, +> timestamps and ids, and similar best practices from now on. + +The whole library (all zero-dependency): + +- **Atomic file operations** with parent-dir creation and optional backups, so an + interrupted or crashed run never leaves a partial or corrupt file in its final location. See `atomic_output_file()`, `atomic_write_text()`, `atomic_write_bytes()`, `copyfile_atomic()`. -- **Abbreviate and quote strings**, which is useful for logging a clean way. - See `abbrev_str()`, `single_line()`, `quote_if_needed()`. - -- **Random UIDs** that use **base 36** (for concise, case-insensitive ids) and **ISO - timestamped ids** (that are unique but also conveniently sort in order of creation). +- **Random and timestamped ids** in **base 36** (concise, case-insensitive, filename-safe), + including ISO-timestamped ids that sort by creation time. See `new_uid()`, `new_timestamped_uid()`. -- **File hashing** with consistent convenience methods for hex, base36, and base64 - formats. See `hash_string()`, `hash_file()`, `file_mtime_hash()`. +- **File and string hashing** with convenient hex, base36, and base64 outputs—good for + cache keys and dedup. See `hash_string()`, `hash_file()`, `file_mtime_hash()`. -- **An `AtomicVar` type** that is a convenient way to have an `RLock` on a variable and - remind yourself to always access the variable in a thread-safe way. +- **An `AtomicVar` type**: a thread-safe variable (an `RLock` around any value) that makes + correct concurrent access the easy path. -- **String utilities** for replacing or adding multiple substrings at once and for - validating and type checking very simple string templates. +- **String utilities** for replacing or inserting multiple substrings at once and for + validated, type-checked string templates. See `StringTemplate`, `replace_multiple()`, `insert_multiple()`. -That's all! They are all quite simple. -The libs are all small so see pydoc strings or code for full docs. - -## Using strif with LLM Agents - -Strif is handy for code that generates files, which is increasingly often AI agent code. - -- **Atomic writes for streamed or generated output.** If a generation is interrupted or - crashes mid-write, you never leave a truncated or corrupt file in its final location. - `atomic_write_text("out.md", content)` is a one-liner for the common case. - -- **Content hashing for caching and dedup.** Use `hash_file()` or `hash_string()` to key - a cache on file contents, or `file_mtime_hash()` for a fast (content-free) cache key. - -- **Sortable, readable run ids.** `new_timestamped_uid()` gives ids that sort by creation - time, which is convenient for logs and scratch directories. - -```python -from strif import atomic_write_text +- **Abbreviate and quote strings** for clean logging and display. + See `abbrev_str()`, `single_line()`, `quote_if_needed()`. -# Safe even if the process dies partway through writing: -atomic_write_text("some-dir/output.md", generated_text, make_parents=True) -``` +That's all! They are all quite simple and small, so see the pydoc strings or code for +full docs. ## Installation From cef7899ae2d60c0833ba8017977b049b0a355275 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 23 May 2026 20:22:18 +0000 Subject: [PATCH 3/4] README: add zero-dependencies / supply-chain security tip at top. --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 4dc1205..cbf0e40 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,12 @@ It is simply a few functions and tricks that have repeatedly shown value in vari projects. The goal is not to give a comprehensive suite of utilities but simply to complement the standard libraries and fill in a few gaps. +> [!TIP] +> +> Given the rapid rise of supply chain attacks on Python packages, it's worth noting this +> repository has **ZERO dependencies**. You can even have your agent review its security +> before you use it. + > [!TIP] > > ✨ **NEW:** **Version 3.1** adds `atomic_write_text()`/`atomic_write_bytes()`, exposes From 03328afa516a3b66cc80c72da6c75e3723b7b8ff Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 23 May 2026 21:00:38 +0000 Subject: [PATCH 4/4] README: swap tip order (NEW/prettyfmt first, supply-chain second). --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index cbf0e40..692460d 100644 --- a/README.md +++ b/README.md @@ -7,12 +7,6 @@ It is simply a few functions and tricks that have repeatedly shown value in vari projects. The goal is not to give a comprehensive suite of utilities but simply to complement the standard libraries and fill in a few gaps. -> [!TIP] -> -> Given the rapid rise of supply chain attacks on Python packages, it's worth noting this -> repository has **ZERO dependencies**. You can even have your agent review its security -> before you use it. - > [!TIP] > > ✨ **NEW:** **Version 3.1** adds `atomic_write_text()`/`atomic_write_bytes()`, exposes @@ -23,6 +17,12 @@ complement the standard libraries and fill in a few gaps. > that has some extra functions for pretty, human-readable outputs for objects, sizes, > times and dates, etc. +> [!TIP] +> +> Given the rapid rise of supply chain attacks on Python packages, it's worth noting this +> repository has **ZERO dependencies**. You can even have your agent review its security +> before you use it. + ## Why Use strif (Especially with Coding Agents) Strif is a simple way to get better Python out of coding agents. It's small enough that