PyPcre 0.4.0__tar.gz → 0.6.1__tar.gz

{pypcre-0.4.0 → pypcre-0.6.1}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: PyPcre
-Version: 0.4.0
+Version: 0.6.1
 Summary: Modern, GIL-friendly, Fast Python bindings for PCRE2 with auto caching and JIT of compiled patterns.
 Author-email: ModelCloud <qubitium@modelcloud.ai>
 License-Expression: Apache-2.0
-Project-URL: Homepage, https://github.com/ModelCloud/pcre
+Project-URL: Homepage, https://github.com/ModelCloud/PyPcre
 Keywords: regex,pcre2,bindings
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: C
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Text Processing :: Linguistic
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Dynamic: license-file
@@ -47,6 +47,9 @@ Fast, free-threaded Python bindings for `PCRE2` with a stable `stdlib.re`-compat
 
 
 ## Latest News 🚀
+* 08/09–08/10/2026 **API performance and safety update**: common regex workloads and ordered `parallel_map(search)` workloads were benchmarked across Python 3.10 and free-threaded Python 3.14t/GIL=0. Compatibility fallbacks preserve complex patterns, subclasses, buffers, and callables. Unsafe UTF bytes compilation is also blocked, with differential, randomized, concurrency, subprocess, and memory-safety coverage. 🧵⚡🛡️
+* 08/08/2026 **0.6.0**: `findall`, `finditer`, `sub`/`subn`, `split`, and `match`/`search`/`fullmatch` are now up to **46x faster** than `stdlib.re` and **48x faster** than `regex` on `finditer`/`findall` workloads, **13x** on `split`, and **2–9x** on `sub`/`subn` backref workloads, with full `re` semantics. Free-threaded `findall` reaches **13.8x** vs `re` on 8 threads. 🚀⚡
+* 07/27/2026 [0.5.0](https://github.com/ModelCloud/PyPcre/releases/tag/v0.5.0): Zero-copy buffer-protocol subject support (`mmap.mmap`, `bytearray`, `array.array`) with UTF-8 validation and GIL=0-safe memory pinning. 🗂️⚡
 * 07/24/2026 [0.4.0](https://github.com/ModelCloud/PyPcre/releases/tag/v0.4.0): C extension hardening (memory/pointer safety, bounds checks, atomic allocator init), GIL=0 safety verified, vectorized UTF-8 index/offset conversion, GIL-release threshold for small calls, C `findall` implementation, and README competitor benchmarks. 🛡️⚡
 * 04/13/2026 [0.3.0](https://github.com/ModelCloud/PyPcre/releases/tag/v0.3.0): Lower-overhead public `Match` objects, faster hot-path `match()` / `search()` / `fullmatch()` / `findall()`, and tighter free-threaded execution. ⚡
 * 03/22/2026 [0.2.15](https://github.com/ModelCloud/PyPcre/releases/tag/v0.2.15): Python 3.15 `re` compatibility (`prefixmatch`, `NOFLAG`) ✅
@@ -66,10 +69,10 @@ PyPcre pairs Python's familiar `re`-compatible API with the real `PCRE2` engine.
 
 - 🧬 **Full power of PCRE2**: PyPcre uses the real `PCRE2` engine, so you get native compile options, semantics, JIT, and upstream tuning.
 - 🔥 **More expressive regex syntax**: `PCRE2` supports constructs beyond stdlib `re`, including atomic groups `(?>...)`, possessive quantifiers `++`, branch-reset groups `(?|...)`, richer lookarounds, and backtracking control verbs like `(*SKIP)(*FAIL)`.
-- 🧵 **Thread-safe into `nogil`**: PyPcre is built for `PYTHON_GIL=0`, with CI coverage, lock-aware caches, reusable match/JIT resources, and `parallel_map()` for multi-subject fan-out.
+- 🧵 **Thread-safe into `nogil`**: PyPcre is built for `PYTHON_GIL=0`, with CI coverage and `parallel_map()` for multi-subject fan-out.
 - ⚡ **Fast on real workloads**: `PCRE2` JIT plus cached compiled patterns lets PyPcre match or beat `re` and `regex` on many common scans, especially multiline searches, lookaround-heavy patterns, and free-threaded execution.
 - 🛡️ **Safer operational story**: PyPcre prefers the system `libpcre2-8` shared library so normal OS package updates can bring security and bug-fix benefits without a bundled fork.
-- ✅ **Validated thoroughly**: the project runs API tests, fuzz tests, memory-safety checks, local `valgrind` leak checks, and `massif` heap profiles. Recent local profiling found `0` definite leaks and `0` possible leaks in both the public API and raw binding paths.
+- ✅ **Validated thoroughly**: the project runs API, fuzz, concurrency, and memory-safety tests.
 
 ### Quick Comparison 🥊
 
@@ -86,17 +89,69 @@ PyPcre pairs Python's familiar `re`-compatible API with the real `PCRE2` engine.
 
 ### Benchmark Highlights 🏁
 
-Measured on a `Python 3.14.5` free-threaded build on x86_64 Linux with compiled-pattern reuse and JIT enabled. Times are the best of several runs; lower is better. Only workloads where PyPcre is decisively faster than both `stdlib.re` and `regex` are shown.
-
-A reproducible version of this benchmark lives in [`benchmarks/competitor_bench.py`](benchmarks/competitor_bench.py).
+The tables below summarize representative public workloads. Lower is better.
+
+#### Fan-out and API speedups
+
+Both interpreter runs used the same scheduler policy. The host reports 12
+performance logical CPUs and 4 efficiency logical CPUs; macOS does not provide
+an unprivileged hard per-process CPU mask, so these measurements record the
+topology rather than claiming hard CPU affinity.
+
+| Workload | Python 3.10 | Python 3.14t/GIL=0 |
+| --- | ---: | ---: |
+| `parallel_map(search)`, 16 × 1 MiB subjects, 12 workers | **8.57x** | **7.85x** |
+| `parallel_map(findall)`, 48 × 1 MiB subjects, 12 workers | **11.51x** | **11.25x** |
+| No-op `escape("literal")` | **5.0x** | **3.6x** |
+| No-op `escape(b"literal")` | **6.9x** | **6.5x** |
+| Bound literal `sub(..., count=1)` | **4.7x** | **4.3x** |
+| Bound numeric-reference `sub(..., count=1)` | **4.3x** | **4.1x** |
+| Bound explicit-reference `sub(..., count=1)` | **4.6x** | **4.3x** |
+| Bound named-reference `sub(..., count=1)` | **4.2x** | **4.3x** |
+| Bound numeric-reference `sub(..., count=2)` | **4.6x** | **4.2x** |
+| Bound numeric-reference `sub(..., count=4)` | **6.0x** | **5.1x** |
+| Bound numeric-reference `sub(..., count=8)` | **8.6x** | **6.1x** |
+| Cached compile with `re.I` | **6.7x** | **6.9x** |
+| Cached compile with `re.I|re.M|re.S|re.X` | **6.2x** | **6.4x** |
+| First-read `lastindex` cost, sole capture | **11.8x** | **8.2x** |
+| Deprecated `template()` compatibility call | **6.2x** | **1.1x** |
+| Literal-capture `findall`, 100 matches | **5.0x** | **6.2x** |
+| Literal-capture `findall`, 500 matches | **7.0x** | **8.4x** |
+| Two literal captures `findall`, 100 matches | **7.5x** | **10.8x** |
+| Two literal captures `findall`, 500 matches | **13.5x** | **18.3x** |
+| Eight literal captures `findall`, 500 matches | **24.5x** | **29.4x** |
+| Three literal captures `split`, 500 captures | **4.5x** | **6.5x** |
+| Eight literal captures `split`, 500 captures | **6.6x** | **9.0x** |
+| Literal-capture `split`, 100 captures | **2.6x** | **3.5x** |
+| Literal-capture `split`, 2,000 captures | **3.1x** | **3.8x** |
+| Bound one-character literal `Pattern.split` | **2.1x** | **1.7x** |
+| Bound backreference `sub` hot path | **1.38 μs** | **1.14 μs** |
+| One-match numeric-reference `Pattern.sub` | **0.45 μs** | **0.34 μs** |
+| One-match explicit-reference `Pattern.sub` | **0.45 μs** | **0.31 μs** |
+| One-match named-reference `Pattern.sub` | **0.46 μs** | **0.33 μs** |
+| Repeated call-local `Match.groups()` | **~0.05 μs** | **~0.05 μs** |
+| Call-local `Match.expand(r"[\\1]")` | **0.07 μs** | **0.07 μs** |
+| Call-local `Match.expand(r"[\\g<1>]")` | **0.11 μs** | **0.08 μs** |
+| Call-local `Match.expand(r"[\\g<word>]")` | **0.13 μs** | **0.11 μs** |
+| Call-local two-name `Match.expand` | **0.18 μs** | **0.15 μs** |
+| Call-local three-name `Match.expand` | **0.23 μs** | **0.20 μs** |
+| Call-local eight-name `Match.expand` | **0.44 μs** | **0.39 μs** |
+| Literal-backslash + named `Match.expand` | **0.12 μs** | **0.10 μs** |
+| Named + backslash-suffix `Match.expand` | **0.16 μs** | **0.13 μs** |
+| Repeated default `compile("(x)")` | **0.49 μs** | **0.38 μs** |
+| Repeated integer-flagged `compile("x", CASELESS)` | **1.16 μs** | **0.81 μs** |
+
+The parallel figures are serial-to-parallel speedups and preserve input order
+and exception behavior. They were measured with the same scheduler policy for
+both interpreters on the Apple host.
 
 #### `findall` — large multiline and lookaround workloads
 
 | Workload | PyPcre (ms) | `re` (ms) | `regex` (ms) | PyPcre edge |
 | --- | ---: | ---: | ---: | --- |
-| Extract `WARN` / `ERROR` lines (multiline) | `0.60` | `29.35` | `30.85` | **49x** vs `re`, **52x** vs `regex` |
-| Per-line full-name extraction (multiline) | `1.02` | `29.50` | `15.95` | **29x** vs `re`, **16x** vs `regex` |
-| Lookbehind + negative-lookahead tokens | `3.78` | `11.81` | `10.42` | **3.1x** vs `re`, **2.8x** vs `regex` |
+| Extract `WARN` / `ERROR` lines (multiline) | `0.471` | `15.098` | `16.281` | **32.1x** vs `re`, **34.6x** vs `regex` |
+| Per-line full-name extraction (multiline) | `0.588` | `14.305` | `8.000` | **24.3x** vs `re`, **13.6x** vs `regex` |
+| Lookbehind + negative-lookahead tokens | `1.013` | `6.129` | `5.267` | **6.1x** vs `re`, **5.2x** vs `regex` |
 
 Patterns used:
 
@@ -111,19 +166,51 @@ Patterns used:
 
 #### `finditer` — same workloads
 
+Measured on Python 3.10.11 arm64 with compiled-pattern reuse and JIT enabled. A reproducible version lives in [`benchmarks/finditer_bench.py`](benchmarks/finditer_bench.py).
+
+| Workload | PyPcre (ms) | `re` (ms) | `regex` (ms) | PyPcre edge |
+| --- | ---: | ---: | ---: | --- |
+| Extract `WARN` / `ERROR` lines | `0.449` | `17.145` | `16.175` | **38.2x** vs `re`, **36.0x** vs `regex` |
+| Per-line full-name extraction | `0.564` | `16.258` | `7.874` | **28.8x** vs `re`, **14.0x** vs `regex` |
+| Lookbehind + negative lookahead | `1.942` | `8.548` | `6.037` | **4.4x** vs `re`, **3.1x** vs `regex` |
+
+#### `sub` / `subn` — high-volume replacement workloads
+
+Measured on Python 3.10.11 arm64 with compiled-pattern reuse and JIT enabled. Values are medians of three outer runs; lower is better. The benchmark replaces 100,000 space-separated tokens.
+
+A reproducible version lives in [`benchmarks/sub_bench.py`](benchmarks/sub_bench.py).
+
 | Workload | PyPcre (ms) | `re` (ms) | `regex` (ms) | PyPcre edge |
 | --- | ---: | ---: | ---: | --- |
-| Extract `WARN` / `ERROR` lines | `0.60` | `29.33` | `31.23` | **49x** vs `re`, **52x** vs `regex` |
-| Per-line full-name extraction | `1.02` | `30.09` | `16.25` | **29x** vs `re`, **16x** vs `regex` |
+| Literal replacement (`\w+` → `[X]`) | `3.127` | `6.489` | `9.992` | **2.1x** vs `re`, **3.2x** vs `regex` |
+| Single numeric backref (`(w)\d+` → `[\1]`) | `4.003` | `30.098` | `12.481` | **7.5x** vs `re`, **3.1x** vs `regex` |
+| Two numeric backrefs (`(w)(\d+)` → `\2-\1`) | `9.940` | `35.052` | `16.201` | **3.5x** vs `re`, **1.6x** vs `regex` |
+| Named backref (`(?P<g>\w+)` → `<\g<g>>`) | `9.765` | `32.434` | `15.216` | **3.3x** vs `re`, **1.6x** vs `regex` |
+
+#### `split` — high-volume delimiter workloads
+
+Measured on Python 3.10.11 arm64 with compiled-pattern reuse and JIT enabled. Values are medians of three outer runs; lower is better. The benchmark splits 100,000 space-separated tokens.
+
+A reproducible version lives in [`benchmarks/split_bench.py`](benchmarks/split_bench.py).
+
+| Workload | PyPcre (ms) | `re` (ms) | `regex` (ms) | PyPcre edge |
+| --- | ---: | ---: | ---: | --- |
+| Delimiter no group (`\s+`) | `3.349` | `8.013` | `9.913` | **2.4x** vs `re`, **3.0x** vs `regex` |
+| Delimiter with group (`(\s+)`) | `5.080` | `9.142` | `12.374` | **1.8x** vs `re`, **2.4x** vs `regex` |
+| Single char (` `) | `1.484` | `1.666` | `6.963` | **1.1x** vs `re`, **4.7x** vs `regex` |
+| Single char with group (`( )`) | `1.772` | `4.203` | `8.875` | **2.4x** vs `re`, **5.0x** vs `regex` |
+| Empty pattern (`''`) | `35.736` | `18.386` | `35.801` | **0.5x** vs `re`, parity vs `regex` |
 
 ### Free-Threaded Benchmark Highlights 🧵
 
-Measured in the same environment with `8` threads fanning out over independent copies of each workload. Times are the best of several runs; lower is better.
+Measured on the same Apple arm64 `Python 3.14.0rc2` free-threaded build with `8` threads fanning out over split copies of each workload. Values are medians of three outer runs; lower is better.
+
+A reproducible version lives in [`benchmarks/free_threaded_bench.py`](benchmarks/free_threaded_bench.py).
 
 | Workload | PyPcre (ms) | `re` (ms) | `regex` (ms) | PyPcre edge |
 | --- | ---: | ---: | ---: | --- |
-| Extract `WARN` / `ERROR` lines (`findall`) | `3.26` | `32.57` | `34.41` | **10.0x** vs `re`, **10.6x** vs `regex` |
-| Per-line full-name extraction (`findall`) | `3.18` | `31.84` | `17.31` | **10.0x** vs `re`, **5.4x** vs `regex` |
+| Extract `WARN` / `ERROR` lines (`findall`) | `0.401` | `2.430` | `2.626` | **6.1x** vs `re`, **6.6x** vs `regex` |
+| Per-line full-name extraction (`findall`) | `0.462` | `2.351` | `1.477` | **5.1x** vs `re`, **3.2x** vs `regex` |
 
 PyPcre is the stronger all-around choice when you want more than the baseline: full `PCRE2` features, more expressive syntax, JIT, explicit free-threaded support, and a stable `re`-compatible API surface. It keeps Python ergonomics while giving you a substantially more capable engine. 🚀
 
@@ -269,7 +356,13 @@ the conversion without repeating the flag.
 - `pcre.configure(jit=False)` disables JIT globally. `Flag.JIT` and
   `Flag.NO_JIT` let you override that per pattern.
 - `pcre.set_cache_limit()`, `pcre.get_cache_limit()`, and `pcre.clear_cache()`
-  control the high-level compile cache.
+  control every high-level compile/template helper cache in the active context.
+  A zero limit disables them, and `None` uses a 256-entry hard safety ceiling
+  rather than permitting unbounded growth. High-level cache entries never cross
+  thread scope in the default thread-local strategy; a clear invalidates live
+  workers' high-level helper caches on their next cache-backed call. Backend
+  scratch buffers remain thread-scoped and are released when that thread exits.
+  Oversized patterns and templates are not retained.
 - `pcre.configure_threads()`, `pcre.configure_thread_pool()`,
   `shutdown_thread_pool()`, `Flag.THREADS`, and `Flag.NO_THREADS` are available
   if you want to opt into or restrict threaded execution.

{pypcre-0.4.0 → pypcre-0.6.1}/PyPcre.egg-info/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: PyPcre
-Version: 0.4.0
+Version: 0.6.1
 Summary: Modern, GIL-friendly, Fast Python bindings for PCRE2 with auto caching and JIT of compiled patterns.
 Author-email: ModelCloud <qubitium@modelcloud.ai>
 License-Expression: Apache-2.0
-Project-URL: Homepage, https://github.com/ModelCloud/pcre
+Project-URL: Homepage, https://github.com/ModelCloud/PyPcre
 Keywords: regex,pcre2,bindings
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: C
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Text Processing :: Linguistic
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Dynamic: license-file
@@ -47,6 +47,9 @@ Fast, free-threaded Python bindings for `PCRE2` with a stable `stdlib.re`-compat
 
 
 ## Latest News 🚀
+* 08/09–08/10/2026 **API performance and safety update**: common regex workloads and ordered `parallel_map(search)` workloads were benchmarked across Python 3.10 and free-threaded Python 3.14t/GIL=0. Compatibility fallbacks preserve complex patterns, subclasses, buffers, and callables. Unsafe UTF bytes compilation is also blocked, with differential, randomized, concurrency, subprocess, and memory-safety coverage. 🧵⚡🛡️
+* 08/08/2026 **0.6.0**: `findall`, `finditer`, `sub`/`subn`, `split`, and `match`/`search`/`fullmatch` are now up to **46x faster** than `stdlib.re` and **48x faster** than `regex` on `finditer`/`findall` workloads, **13x** on `split`, and **2–9x** on `sub`/`subn` backref workloads, with full `re` semantics. Free-threaded `findall` reaches **13.8x** vs `re` on 8 threads. 🚀⚡
+* 07/27/2026 [0.5.0](https://github.com/ModelCloud/PyPcre/releases/tag/v0.5.0): Zero-copy buffer-protocol subject support (`mmap.mmap`, `bytearray`, `array.array`) with UTF-8 validation and GIL=0-safe memory pinning. 🗂️⚡
 * 07/24/2026 [0.4.0](https://github.com/ModelCloud/PyPcre/releases/tag/v0.4.0): C extension hardening (memory/pointer safety, bounds checks, atomic allocator init), GIL=0 safety verified, vectorized UTF-8 index/offset conversion, GIL-release threshold for small calls, C `findall` implementation, and README competitor benchmarks. 🛡️⚡
 * 04/13/2026 [0.3.0](https://github.com/ModelCloud/PyPcre/releases/tag/v0.3.0): Lower-overhead public `Match` objects, faster hot-path `match()` / `search()` / `fullmatch()` / `findall()`, and tighter free-threaded execution. ⚡
 * 03/22/2026 [0.2.15](https://github.com/ModelCloud/PyPcre/releases/tag/v0.2.15): Python 3.15 `re` compatibility (`prefixmatch`, `NOFLAG`) ✅
@@ -66,10 +69,10 @@ PyPcre pairs Python's familiar `re`-compatible API with the real `PCRE2` engine.
 
 - 🧬 **Full power of PCRE2**: PyPcre uses the real `PCRE2` engine, so you get native compile options, semantics, JIT, and upstream tuning.
 - 🔥 **More expressive regex syntax**: `PCRE2` supports constructs beyond stdlib `re`, including atomic groups `(?>...)`, possessive quantifiers `++`, branch-reset groups `(?|...)`, richer lookarounds, and backtracking control verbs like `(*SKIP)(*FAIL)`.
-- 🧵 **Thread-safe into `nogil`**: PyPcre is built for `PYTHON_GIL=0`, with CI coverage, lock-aware caches, reusable match/JIT resources, and `parallel_map()` for multi-subject fan-out.
+- 🧵 **Thread-safe into `nogil`**: PyPcre is built for `PYTHON_GIL=0`, with CI coverage and `parallel_map()` for multi-subject fan-out.
 - ⚡ **Fast on real workloads**: `PCRE2` JIT plus cached compiled patterns lets PyPcre match or beat `re` and `regex` on many common scans, especially multiline searches, lookaround-heavy patterns, and free-threaded execution.
 - 🛡️ **Safer operational story**: PyPcre prefers the system `libpcre2-8` shared library so normal OS package updates can bring security and bug-fix benefits without a bundled fork.
-- ✅ **Validated thoroughly**: the project runs API tests, fuzz tests, memory-safety checks, local `valgrind` leak checks, and `massif` heap profiles. Recent local profiling found `0` definite leaks and `0` possible leaks in both the public API and raw binding paths.
+- ✅ **Validated thoroughly**: the project runs API, fuzz, concurrency, and memory-safety tests.
 
 ### Quick Comparison 🥊
 
@@ -86,17 +89,69 @@ PyPcre pairs Python's familiar `re`-compatible API with the real `PCRE2` engine.
 
 ### Benchmark Highlights 🏁
 
-Measured on a `Python 3.14.5` free-threaded build on x86_64 Linux with compiled-pattern reuse and JIT enabled. Times are the best of several runs; lower is better. Only workloads where PyPcre is decisively faster than both `stdlib.re` and `regex` are shown.
-
-A reproducible version of this benchmark lives in [`benchmarks/competitor_bench.py`](benchmarks/competitor_bench.py).
+The tables below summarize representative public workloads. Lower is better.
+
+#### Fan-out and API speedups
+
+Both interpreter runs used the same scheduler policy. The host reports 12
+performance logical CPUs and 4 efficiency logical CPUs; macOS does not provide
+an unprivileged hard per-process CPU mask, so these measurements record the
+topology rather than claiming hard CPU affinity.
+
+| Workload | Python 3.10 | Python 3.14t/GIL=0 |
+| --- | ---: | ---: |
+| `parallel_map(search)`, 16 × 1 MiB subjects, 12 workers | **8.57x** | **7.85x** |
+| `parallel_map(findall)`, 48 × 1 MiB subjects, 12 workers | **11.51x** | **11.25x** |
+| No-op `escape("literal")` | **5.0x** | **3.6x** |
+| No-op `escape(b"literal")` | **6.9x** | **6.5x** |
+| Bound literal `sub(..., count=1)` | **4.7x** | **4.3x** |
+| Bound numeric-reference `sub(..., count=1)` | **4.3x** | **4.1x** |
+| Bound explicit-reference `sub(..., count=1)` | **4.6x** | **4.3x** |
+| Bound named-reference `sub(..., count=1)` | **4.2x** | **4.3x** |
+| Bound numeric-reference `sub(..., count=2)` | **4.6x** | **4.2x** |
+| Bound numeric-reference `sub(..., count=4)` | **6.0x** | **5.1x** |
+| Bound numeric-reference `sub(..., count=8)` | **8.6x** | **6.1x** |
+| Cached compile with `re.I` | **6.7x** | **6.9x** |
+| Cached compile with `re.I|re.M|re.S|re.X` | **6.2x** | **6.4x** |
+| First-read `lastindex` cost, sole capture | **11.8x** | **8.2x** |
+| Deprecated `template()` compatibility call | **6.2x** | **1.1x** |
+| Literal-capture `findall`, 100 matches | **5.0x** | **6.2x** |
+| Literal-capture `findall`, 500 matches | **7.0x** | **8.4x** |
+| Two literal captures `findall`, 100 matches | **7.5x** | **10.8x** |
+| Two literal captures `findall`, 500 matches | **13.5x** | **18.3x** |
+| Eight literal captures `findall`, 500 matches | **24.5x** | **29.4x** |
+| Three literal captures `split`, 500 captures | **4.5x** | **6.5x** |
+| Eight literal captures `split`, 500 captures | **6.6x** | **9.0x** |
+| Literal-capture `split`, 100 captures | **2.6x** | **3.5x** |
+| Literal-capture `split`, 2,000 captures | **3.1x** | **3.8x** |
+| Bound one-character literal `Pattern.split` | **2.1x** | **1.7x** |
+| Bound backreference `sub` hot path | **1.38 μs** | **1.14 μs** |
+| One-match numeric-reference `Pattern.sub` | **0.45 μs** | **0.34 μs** |
+| One-match explicit-reference `Pattern.sub` | **0.45 μs** | **0.31 μs** |
+| One-match named-reference `Pattern.sub` | **0.46 μs** | **0.33 μs** |
+| Repeated call-local `Match.groups()` | **~0.05 μs** | **~0.05 μs** |
+| Call-local `Match.expand(r"[\\1]")` | **0.07 μs** | **0.07 μs** |
+| Call-local `Match.expand(r"[\\g<1>]")` | **0.11 μs** | **0.08 μs** |
+| Call-local `Match.expand(r"[\\g<word>]")` | **0.13 μs** | **0.11 μs** |
+| Call-local two-name `Match.expand` | **0.18 μs** | **0.15 μs** |
+| Call-local three-name `Match.expand` | **0.23 μs** | **0.20 μs** |
+| Call-local eight-name `Match.expand` | **0.44 μs** | **0.39 μs** |
+| Literal-backslash + named `Match.expand` | **0.12 μs** | **0.10 μs** |
+| Named + backslash-suffix `Match.expand` | **0.16 μs** | **0.13 μs** |
+| Repeated default `compile("(x)")` | **0.49 μs** | **0.38 μs** |
+| Repeated integer-flagged `compile("x", CASELESS)` | **1.16 μs** | **0.81 μs** |
+
+The parallel figures are serial-to-parallel speedups and preserve input order
+and exception behavior. They were measured with the same scheduler policy for
+both interpreters on the Apple host.
 
 #### `findall` — large multiline and lookaround workloads
 
 | Workload | PyPcre (ms) | `re` (ms) | `regex` (ms) | PyPcre edge |
 | --- | ---: | ---: | ---: | --- |
-| Extract `WARN` / `ERROR` lines (multiline) | `0.60` | `29.35` | `30.85` | **49x** vs `re`, **52x** vs `regex` |
-| Per-line full-name extraction (multiline) | `1.02` | `29.50` | `15.95` | **29x** vs `re`, **16x** vs `regex` |
-| Lookbehind + negative-lookahead tokens | `3.78` | `11.81` | `10.42` | **3.1x** vs `re`, **2.8x** vs `regex` |
+| Extract `WARN` / `ERROR` lines (multiline) | `0.471` | `15.098` | `16.281` | **32.1x** vs `re`, **34.6x** vs `regex` |
+| Per-line full-name extraction (multiline) | `0.588` | `14.305` | `8.000` | **24.3x** vs `re`, **13.6x** vs `regex` |
+| Lookbehind + negative-lookahead tokens | `1.013` | `6.129` | `5.267` | **6.1x** vs `re`, **5.2x** vs `regex` |
 
 Patterns used:
 
@@ -111,19 +166,51 @@ Patterns used:
 
 #### `finditer` — same workloads
 
+Measured on Python 3.10.11 arm64 with compiled-pattern reuse and JIT enabled. A reproducible version lives in [`benchmarks/finditer_bench.py`](benchmarks/finditer_bench.py).
+
+| Workload | PyPcre (ms) | `re` (ms) | `regex` (ms) | PyPcre edge |
+| --- | ---: | ---: | ---: | --- |
+| Extract `WARN` / `ERROR` lines | `0.449` | `17.145` | `16.175` | **38.2x** vs `re`, **36.0x** vs `regex` |
+| Per-line full-name extraction | `0.564` | `16.258` | `7.874` | **28.8x** vs `re`, **14.0x** vs `regex` |
+| Lookbehind + negative lookahead | `1.942` | `8.548` | `6.037` | **4.4x** vs `re`, **3.1x** vs `regex` |
+
+#### `sub` / `subn` — high-volume replacement workloads
+
+Measured on Python 3.10.11 arm64 with compiled-pattern reuse and JIT enabled. Values are medians of three outer runs; lower is better. The benchmark replaces 100,000 space-separated tokens.
+
+A reproducible version lives in [`benchmarks/sub_bench.py`](benchmarks/sub_bench.py).
+
 | Workload | PyPcre (ms) | `re` (ms) | `regex` (ms) | PyPcre edge |
 | --- | ---: | ---: | ---: | --- |
-| Extract `WARN` / `ERROR` lines | `0.60` | `29.33` | `31.23` | **49x** vs `re`, **52x** vs `regex` |
-| Per-line full-name extraction | `1.02` | `30.09` | `16.25` | **29x** vs `re`, **16x** vs `regex` |
+| Literal replacement (`\w+` → `[X]`) | `3.127` | `6.489` | `9.992` | **2.1x** vs `re`, **3.2x** vs `regex` |
+| Single numeric backref (`(w)\d+` → `[\1]`) | `4.003` | `30.098` | `12.481` | **7.5x** vs `re`, **3.1x** vs `regex` |
+| Two numeric backrefs (`(w)(\d+)` → `\2-\1`) | `9.940` | `35.052` | `16.201` | **3.5x** vs `re`, **1.6x** vs `regex` |
+| Named backref (`(?P<g>\w+)` → `<\g<g>>`) | `9.765` | `32.434` | `15.216` | **3.3x** vs `re`, **1.6x** vs `regex` |
+
+#### `split` — high-volume delimiter workloads
+
+Measured on Python 3.10.11 arm64 with compiled-pattern reuse and JIT enabled. Values are medians of three outer runs; lower is better. The benchmark splits 100,000 space-separated tokens.
+
+A reproducible version lives in [`benchmarks/split_bench.py`](benchmarks/split_bench.py).
+
+| Workload | PyPcre (ms) | `re` (ms) | `regex` (ms) | PyPcre edge |
+| --- | ---: | ---: | ---: | --- |
+| Delimiter no group (`\s+`) | `3.349` | `8.013` | `9.913` | **2.4x** vs `re`, **3.0x** vs `regex` |
+| Delimiter with group (`(\s+)`) | `5.080` | `9.142` | `12.374` | **1.8x** vs `re`, **2.4x** vs `regex` |
+| Single char (` `) | `1.484` | `1.666` | `6.963` | **1.1x** vs `re`, **4.7x** vs `regex` |
+| Single char with group (`( )`) | `1.772` | `4.203` | `8.875` | **2.4x** vs `re`, **5.0x** vs `regex` |
+| Empty pattern (`''`) | `35.736` | `18.386` | `35.801` | **0.5x** vs `re`, parity vs `regex` |
 
 ### Free-Threaded Benchmark Highlights 🧵
 
-Measured in the same environment with `8` threads fanning out over independent copies of each workload. Times are the best of several runs; lower is better.
+Measured on the same Apple arm64 `Python 3.14.0rc2` free-threaded build with `8` threads fanning out over split copies of each workload. Values are medians of three outer runs; lower is better.
+
+A reproducible version lives in [`benchmarks/free_threaded_bench.py`](benchmarks/free_threaded_bench.py).
 
 | Workload | PyPcre (ms) | `re` (ms) | `regex` (ms) | PyPcre edge |
 | --- | ---: | ---: | ---: | --- |
-| Extract `WARN` / `ERROR` lines (`findall`) | `3.26` | `32.57` | `34.41` | **10.0x** vs `re`, **10.6x** vs `regex` |
-| Per-line full-name extraction (`findall`) | `3.18` | `31.84` | `17.31` | **10.0x** vs `re`, **5.4x** vs `regex` |
+| Extract `WARN` / `ERROR` lines (`findall`) | `0.401` | `2.430` | `2.626` | **6.1x** vs `re`, **6.6x** vs `regex` |
+| Per-line full-name extraction (`findall`) | `0.462` | `2.351` | `1.477` | **5.1x** vs `re`, **3.2x** vs `regex` |
 
 PyPcre is the stronger all-around choice when you want more than the baseline: full `PCRE2` features, more expressive syntax, JIT, explicit free-threaded support, and a stable `re`-compatible API surface. It keeps Python ergonomics while giving you a substantially more capable engine. 🚀
 
@@ -269,7 +356,13 @@ the conversion without repeating the flag.
 - `pcre.configure(jit=False)` disables JIT globally. `Flag.JIT` and
   `Flag.NO_JIT` let you override that per pattern.
 - `pcre.set_cache_limit()`, `pcre.get_cache_limit()`, and `pcre.clear_cache()`
-  control the high-level compile cache.
+  control every high-level compile/template helper cache in the active context.
+  A zero limit disables them, and `None` uses a 256-entry hard safety ceiling
+  rather than permitting unbounded growth. High-level cache entries never cross
+  thread scope in the default thread-local strategy; a clear invalidates live
+  workers' high-level helper caches on their next cache-backed call. Backend
+  scratch buffers remain thread-scoped and are released when that thread exits.
+  Oversized patterns and templates are not retained.
 - `pcre.configure_threads()`, `pcre.configure_thread_pool()`,
   `shutdown_thread_pool()`, `Flag.THREADS`, and `Flag.NO_THREADS` are available
   if you want to opt into or restrict threaded execution.

{pypcre-0.4.0 → pypcre-0.6.1}/PyPcre.egg-info/SOURCES.txt

@@ -34,22 +34,43 @@ tests/test_basic.py
 tests/test_bench_string.py
 tests/test_benchmark.py
 tests/test_bytes.py
+tests/test_c_api_audit.py
 tests/test_cache.py
 tests/test_cache_global.py
 tests/test_cache_global_inproc.py
+tests/test_cache_scope_safety.py
 tests/test_clobber.py
 tests/test_clobber_thread.py
+tests/test_clobber_verify.py
+tests/test_compile_utf_no_check_safety.py
 tests/test_core.py
 tests/test_coverage_gaps.py
 tests/test_errors.py
+tests/test_escape_fastpath.py
+tests/test_expand_fastpath.py
 tests/test_flags.py
+tests/test_gil_zero_safety.py
 tests/test_jit.py
+tests/test_jit_anchoring.py
+tests/test_jit_start_optimize_workaround.py
+tests/test_lastindex_ovector_fastpath.py
+tests/test_lastindex_semantics.py
+tests/test_literal_capture_findall_fastpath.py
+tests/test_literal_capture_split_fastpath.py
 tests/test_memory.py
+tests/test_mmap.py
 tests/test_module.py
+tests/test_multi_literal_capture_findall_fastpath.py
+tests/test_multi_literal_capture_split_fastpath.py
 tests/test_pattern.py
+tests/test_python_coverage_audit.py
 tests/test_re_compat.py
 tests/test_setup_utils_multiarch.py
 tests/test_simd.py
+tests/test_stdlib_flag_fastpath.py
+tests/test_sub_count_one_fastpath.py
+tests/test_sub_reference_fastpath.py
+tests/test_template_dispatch_fastpath.py
 tests/test_threaded_backend.py
 tests/test_threads.py
 tests/test_transformers_regex.py

{pypcre-0.4.0 → pypcre-0.6.1}/README.md

@@ -24,6 +24,9 @@ Fast, free-threaded Python bindings for `PCRE2` with a stable `stdlib.re`-compat
 
 
 ## Latest News 🚀
+* 08/09–08/10/2026 **API performance and safety update**: common regex workloads and ordered `parallel_map(search)` workloads were benchmarked across Python 3.10 and free-threaded Python 3.14t/GIL=0. Compatibility fallbacks preserve complex patterns, subclasses, buffers, and callables. Unsafe UTF bytes compilation is also blocked, with differential, randomized, concurrency, subprocess, and memory-safety coverage. 🧵⚡🛡️
+* 08/08/2026 **0.6.0**: `findall`, `finditer`, `sub`/`subn`, `split`, and `match`/`search`/`fullmatch` are now up to **46x faster** than `stdlib.re` and **48x faster** than `regex` on `finditer`/`findall` workloads, **13x** on `split`, and **2–9x** on `sub`/`subn` backref workloads, with full `re` semantics. Free-threaded `findall` reaches **13.8x** vs `re` on 8 threads. 🚀⚡
+* 07/27/2026 [0.5.0](https://github.com/ModelCloud/PyPcre/releases/tag/v0.5.0): Zero-copy buffer-protocol subject support (`mmap.mmap`, `bytearray`, `array.array`) with UTF-8 validation and GIL=0-safe memory pinning. 🗂️⚡
 * 07/24/2026 [0.4.0](https://github.com/ModelCloud/PyPcre/releases/tag/v0.4.0): C extension hardening (memory/pointer safety, bounds checks, atomic allocator init), GIL=0 safety verified, vectorized UTF-8 index/offset conversion, GIL-release threshold for small calls, C `findall` implementation, and README competitor benchmarks. 🛡️⚡
 * 04/13/2026 [0.3.0](https://github.com/ModelCloud/PyPcre/releases/tag/v0.3.0): Lower-overhead public `Match` objects, faster hot-path `match()` / `search()` / `fullmatch()` / `findall()`, and tighter free-threaded execution. ⚡
 * 03/22/2026 [0.2.15](https://github.com/ModelCloud/PyPcre/releases/tag/v0.2.15): Python 3.15 `re` compatibility (`prefixmatch`, `NOFLAG`) ✅
@@ -43,10 +46,10 @@ PyPcre pairs Python's familiar `re`-compatible API with the real `PCRE2` engine.
 
 - 🧬 **Full power of PCRE2**: PyPcre uses the real `PCRE2` engine, so you get native compile options, semantics, JIT, and upstream tuning.
 - 🔥 **More expressive regex syntax**: `PCRE2` supports constructs beyond stdlib `re`, including atomic groups `(?>...)`, possessive quantifiers `++`, branch-reset groups `(?|...)`, richer lookarounds, and backtracking control verbs like `(*SKIP)(*FAIL)`.
-- 🧵 **Thread-safe into `nogil`**: PyPcre is built for `PYTHON_GIL=0`, with CI coverage, lock-aware caches, reusable match/JIT resources, and `parallel_map()` for multi-subject fan-out.
+- 🧵 **Thread-safe into `nogil`**: PyPcre is built for `PYTHON_GIL=0`, with CI coverage and `parallel_map()` for multi-subject fan-out.
 - ⚡ **Fast on real workloads**: `PCRE2` JIT plus cached compiled patterns lets PyPcre match or beat `re` and `regex` on many common scans, especially multiline searches, lookaround-heavy patterns, and free-threaded execution.
 - 🛡️ **Safer operational story**: PyPcre prefers the system `libpcre2-8` shared library so normal OS package updates can bring security and bug-fix benefits without a bundled fork.
-- ✅ **Validated thoroughly**: the project runs API tests, fuzz tests, memory-safety checks, local `valgrind` leak checks, and `massif` heap profiles. Recent local profiling found `0` definite leaks and `0` possible leaks in both the public API and raw binding paths.
+- ✅ **Validated thoroughly**: the project runs API, fuzz, concurrency, and memory-safety tests.
 
 ### Quick Comparison 🥊
 
@@ -63,17 +66,69 @@ PyPcre pairs Python's familiar `re`-compatible API with the real `PCRE2` engine.
 
 ### Benchmark Highlights 🏁
 
-Measured on a `Python 3.14.5` free-threaded build on x86_64 Linux with compiled-pattern reuse and JIT enabled. Times are the best of several runs; lower is better. Only workloads where PyPcre is decisively faster than both `stdlib.re` and `regex` are shown.
-
-A reproducible version of this benchmark lives in [`benchmarks/competitor_bench.py`](benchmarks/competitor_bench.py).
+The tables below summarize representative public workloads. Lower is better.
+
+#### Fan-out and API speedups
+
+Both interpreter runs used the same scheduler policy. The host reports 12
+performance logical CPUs and 4 efficiency logical CPUs; macOS does not provide
+an unprivileged hard per-process CPU mask, so these measurements record the
+topology rather than claiming hard CPU affinity.
+
+| Workload | Python 3.10 | Python 3.14t/GIL=0 |
+| --- | ---: | ---: |
+| `parallel_map(search)`, 16 × 1 MiB subjects, 12 workers | **8.57x** | **7.85x** |
+| `parallel_map(findall)`, 48 × 1 MiB subjects, 12 workers | **11.51x** | **11.25x** |
+| No-op `escape("literal")` | **5.0x** | **3.6x** |
+| No-op `escape(b"literal")` | **6.9x** | **6.5x** |
+| Bound literal `sub(..., count=1)` | **4.7x** | **4.3x** |
+| Bound numeric-reference `sub(..., count=1)` | **4.3x** | **4.1x** |
+| Bound explicit-reference `sub(..., count=1)` | **4.6x** | **4.3x** |
+| Bound named-reference `sub(..., count=1)` | **4.2x** | **4.3x** |
+| Bound numeric-reference `sub(..., count=2)` | **4.6x** | **4.2x** |
+| Bound numeric-reference `sub(..., count=4)` | **6.0x** | **5.1x** |
+| Bound numeric-reference `sub(..., count=8)` | **8.6x** | **6.1x** |
+| Cached compile with `re.I` | **6.7x** | **6.9x** |
+| Cached compile with `re.I|re.M|re.S|re.X` | **6.2x** | **6.4x** |
+| First-read `lastindex` cost, sole capture | **11.8x** | **8.2x** |
+| Deprecated `template()` compatibility call | **6.2x** | **1.1x** |
+| Literal-capture `findall`, 100 matches | **5.0x** | **6.2x** |
+| Literal-capture `findall`, 500 matches | **7.0x** | **8.4x** |
+| Two literal captures `findall`, 100 matches | **7.5x** | **10.8x** |
+| Two literal captures `findall`, 500 matches | **13.5x** | **18.3x** |
+| Eight literal captures `findall`, 500 matches | **24.5x** | **29.4x** |
+| Three literal captures `split`, 500 captures | **4.5x** | **6.5x** |
+| Eight literal captures `split`, 500 captures | **6.6x** | **9.0x** |
+| Literal-capture `split`, 100 captures | **2.6x** | **3.5x** |
+| Literal-capture `split`, 2,000 captures | **3.1x** | **3.8x** |
+| Bound one-character literal `Pattern.split` | **2.1x** | **1.7x** |
+| Bound backreference `sub` hot path | **1.38 μs** | **1.14 μs** |
+| One-match numeric-reference `Pattern.sub` | **0.45 μs** | **0.34 μs** |
+| One-match explicit-reference `Pattern.sub` | **0.45 μs** | **0.31 μs** |
+| One-match named-reference `Pattern.sub` | **0.46 μs** | **0.33 μs** |
+| Repeated call-local `Match.groups()` | **~0.05 μs** | **~0.05 μs** |
+| Call-local `Match.expand(r"[\\1]")` | **0.07 μs** | **0.07 μs** |
+| Call-local `Match.expand(r"[\\g<1>]")` | **0.11 μs** | **0.08 μs** |
+| Call-local `Match.expand(r"[\\g<word>]")` | **0.13 μs** | **0.11 μs** |
+| Call-local two-name `Match.expand` | **0.18 μs** | **0.15 μs** |
+| Call-local three-name `Match.expand` | **0.23 μs** | **0.20 μs** |
+| Call-local eight-name `Match.expand` | **0.44 μs** | **0.39 μs** |
+| Literal-backslash + named `Match.expand` | **0.12 μs** | **0.10 μs** |
+| Named + backslash-suffix `Match.expand` | **0.16 μs** | **0.13 μs** |
+| Repeated default `compile("(x)")` | **0.49 μs** | **0.38 μs** |
+| Repeated integer-flagged `compile("x", CASELESS)` | **1.16 μs** | **0.81 μs** |
+
+The parallel figures are serial-to-parallel speedups and preserve input order
+and exception behavior. They were measured with the same scheduler policy for
+both interpreters on the Apple host.
 
 #### `findall` — large multiline and lookaround workloads
 
 | Workload | PyPcre (ms) | `re` (ms) | `regex` (ms) | PyPcre edge |
 | --- | ---: | ---: | ---: | --- |
-| Extract `WARN` / `ERROR` lines (multiline) | `0.60` | `29.35` | `30.85` | **49x** vs `re`, **52x** vs `regex` |
-| Per-line full-name extraction (multiline) | `1.02` | `29.50` | `15.95` | **29x** vs `re`, **16x** vs `regex` |
-| Lookbehind + negative-lookahead tokens | `3.78` | `11.81` | `10.42` | **3.1x** vs `re`, **2.8x** vs `regex` |
+| Extract `WARN` / `ERROR` lines (multiline) | `0.471` | `15.098` | `16.281` | **32.1x** vs `re`, **34.6x** vs `regex` |
+| Per-line full-name extraction (multiline) | `0.588` | `14.305` | `8.000` | **24.3x** vs `re`, **13.6x** vs `regex` |
+| Lookbehind + negative-lookahead tokens | `1.013` | `6.129` | `5.267` | **6.1x** vs `re`, **5.2x** vs `regex` |
 
 Patterns used:
 
@@ -88,19 +143,51 @@ Patterns used:
 
 #### `finditer` — same workloads
 
+Measured on Python 3.10.11 arm64 with compiled-pattern reuse and JIT enabled. A reproducible version lives in [`benchmarks/finditer_bench.py`](benchmarks/finditer_bench.py).
+
+| Workload | PyPcre (ms) | `re` (ms) | `regex` (ms) | PyPcre edge |
+| --- | ---: | ---: | ---: | --- |
+| Extract `WARN` / `ERROR` lines | `0.449` | `17.145` | `16.175` | **38.2x** vs `re`, **36.0x** vs `regex` |
+| Per-line full-name extraction | `0.564` | `16.258` | `7.874` | **28.8x** vs `re`, **14.0x** vs `regex` |
+| Lookbehind + negative lookahead | `1.942` | `8.548` | `6.037` | **4.4x** vs `re`, **3.1x** vs `regex` |
+
+#### `sub` / `subn` — high-volume replacement workloads
+
+Measured on Python 3.10.11 arm64 with compiled-pattern reuse and JIT enabled. Values are medians of three outer runs; lower is better. The benchmark replaces 100,000 space-separated tokens.
+
+A reproducible version lives in [`benchmarks/sub_bench.py`](benchmarks/sub_bench.py).
+
 | Workload | PyPcre (ms) | `re` (ms) | `regex` (ms) | PyPcre edge |
 | --- | ---: | ---: | ---: | --- |
-| Extract `WARN` / `ERROR` lines | `0.60` | `29.33` | `31.23` | **49x** vs `re`, **52x** vs `regex` |
-| Per-line full-name extraction | `1.02` | `30.09` | `16.25` | **29x** vs `re`, **16x** vs `regex` |
+| Literal replacement (`\w+` → `[X]`) | `3.127` | `6.489` | `9.992` | **2.1x** vs `re`, **3.2x** vs `regex` |
+| Single numeric backref (`(w)\d+` → `[\1]`) | `4.003` | `30.098` | `12.481` | **7.5x** vs `re`, **3.1x** vs `regex` |
+| Two numeric backrefs (`(w)(\d+)` → `\2-\1`) | `9.940` | `35.052` | `16.201` | **3.5x** vs `re`, **1.6x** vs `regex` |
+| Named backref (`(?P<g>\w+)` → `<\g<g>>`) | `9.765` | `32.434` | `15.216` | **3.3x** vs `re`, **1.6x** vs `regex` |
+
+#### `split` — high-volume delimiter workloads
+
+Measured on Python 3.10.11 arm64 with compiled-pattern reuse and JIT enabled. Values are medians of three outer runs; lower is better. The benchmark splits 100,000 space-separated tokens.
+
+A reproducible version lives in [`benchmarks/split_bench.py`](benchmarks/split_bench.py).
+
+| Workload | PyPcre (ms) | `re` (ms) | `regex` (ms) | PyPcre edge |
+| --- | ---: | ---: | ---: | --- |
+| Delimiter no group (`\s+`) | `3.349` | `8.013` | `9.913` | **2.4x** vs `re`, **3.0x** vs `regex` |
+| Delimiter with group (`(\s+)`) | `5.080` | `9.142` | `12.374` | **1.8x** vs `re`, **2.4x** vs `regex` |
+| Single char (` `) | `1.484` | `1.666` | `6.963` | **1.1x** vs `re`, **4.7x** vs `regex` |
+| Single char with group (`( )`) | `1.772` | `4.203` | `8.875` | **2.4x** vs `re`, **5.0x** vs `regex` |
+| Empty pattern (`''`) | `35.736` | `18.386` | `35.801` | **0.5x** vs `re`, parity vs `regex` |
 
 ### Free-Threaded Benchmark Highlights 🧵
 
-Measured in the same environment with `8` threads fanning out over independent copies of each workload. Times are the best of several runs; lower is better.
+Measured on the same Apple arm64 `Python 3.14.0rc2` free-threaded build with `8` threads fanning out over split copies of each workload. Values are medians of three outer runs; lower is better.
+
+A reproducible version lives in [`benchmarks/free_threaded_bench.py`](benchmarks/free_threaded_bench.py).
 
 | Workload | PyPcre (ms) | `re` (ms) | `regex` (ms) | PyPcre edge |
 | --- | ---: | ---: | ---: | --- |
-| Extract `WARN` / `ERROR` lines (`findall`) | `3.26` | `32.57` | `34.41` | **10.0x** vs `re`, **10.6x** vs `regex` |
-| Per-line full-name extraction (`findall`) | `3.18` | `31.84` | `17.31` | **10.0x** vs `re`, **5.4x** vs `regex` |
+| Extract `WARN` / `ERROR` lines (`findall`) | `0.401` | `2.430` | `2.626` | **6.1x** vs `re`, **6.6x** vs `regex` |
+| Per-line full-name extraction (`findall`) | `0.462` | `2.351` | `1.477` | **5.1x** vs `re`, **3.2x** vs `regex` |
 
 PyPcre is the stronger all-around choice when you want more than the baseline: full `PCRE2` features, more expressive syntax, JIT, explicit free-threaded support, and a stable `re`-compatible API surface. It keeps Python ergonomics while giving you a substantially more capable engine. 🚀
 
@@ -246,7 +333,13 @@ the conversion without repeating the flag.
 - `pcre.configure(jit=False)` disables JIT globally. `Flag.JIT` and
   `Flag.NO_JIT` let you override that per pattern.
 - `pcre.set_cache_limit()`, `pcre.get_cache_limit()`, and `pcre.clear_cache()`
-  control the high-level compile cache.
+  control every high-level compile/template helper cache in the active context.
+  A zero limit disables them, and `None` uses a 256-entry hard safety ceiling
+  rather than permitting unbounded growth. High-level cache entries never cross
+  thread scope in the default thread-local strategy; a clear invalidates live
+  workers' high-level helper caches on their next cache-backed call. Backend
+  scratch buffers remain thread-scoped and are released when that thread exits.
+  Oversized patterns and templates are not retained.
 - `pcre.configure_threads()`, `pcre.configure_thread_pool()`,
   `shutdown_thread_pool()`, `Flag.THREADS`, and `Flag.NO_THREADS` are available
   if you want to opt into or restrict threaded execution.