chore: Update docs for slightly better UX.

Author: SirStig

README.md

@@ -6,7 +6,7 @@
 [![Tests](https://github.com/sirstig/yokedcache/actions/workflows/test.yml/badge.svg)](https://github.com/sirstig/yokedcache/actions/workflows/test.yml)
 [![Coverage](https://codecov.io/gh/sirstig/yokedcache/branch/main/graph/badge.svg)](https://codecov.io/gh/sirstig/yokedcache)
 
-Async-first caching with the **same API** across backends: in-process memory (default install), Redis, Memcached, disk, and SQLite. Tag and pattern invalidation, optional Starlette HTTP middleware, and production metrics—usable from FastAPI, Starlette, Django async code, workers, or plain `asyncio`.
+Async-first caching with the **same API** across backends: in-process memory (default install), Redis, Memcached, disk, and SQLite. Tag and pattern invalidation, optional Starlette HTTP middleware, and production metrics—use `await` in FastAPI, Starlette, Django async views, workers, or plain `asyncio`. **Sync code** is welcome too: `get_sync` / `set_sync` (and friends) or `@cached` on a normal `def`—same async-backed implementation, not a separate Redis client.
 
 **[Documentation](https://sirstig.github.io/yokedcache/)** · **[Changelog](https://sirstig.github.io/yokedcache/changelog.html)** · **[PyPI](https://pypi.org/project/yokedcache/)** · **[Issues](https://github.com/sirstig/yokedcache/issues)**
 
@@ -16,7 +16,7 @@ Async-first caching with the **same API** across backends: in-process memory (de
 
 - **Invalidation** — Tags, patterns, and workflows that keep cache and writes aligned
 - **Backends** — Memory (no extra deps), Redis, Memcached, disk, SQLite; per-prefix routing
-- **Framework-agnostic core** — `YokedCache` and decorators work in any asyncio context; FastAPI helpers are optional
+- **Framework-agnostic core** — async API in any asyncio context; sync helpers for scripts and blocking functions; FastAPI helpers optional
 - **HTTP** — ETag / `Cache-Control` middleware (`yokedcache[web]` / Starlette)
 - **Resilience** — Circuit breaker, retries, stale-if-error style patterns
 - **Observability** — Prometheus, StatsD, OpenTelemetry (optional extras)
@@ -71,6 +71,22 @@ asyncio.run(main())
 
 For Redis in production: `pip install "yokedcache[redis]"`, set `redis_url` (or env `YOKEDCACHE_REDIS_URL`), then `connect()` as usual.
 
+### Sync code
+
+Prefer `await` inside apps that already run an event loop. For scripts or blocking call stacks, connect once, then use `*_sync`:
+
+```python
+import asyncio
+from yokedcache import YokedCache
+from yokedcache.config import CacheConfig
+
+cache = YokedCache(CacheConfig())
+asyncio.run(cache.connect())
+cache.set_sync("user:1", {"name": "Ada"}, ttl=60)
+print(cache.get_sync("user:1"))
+asyncio.run(cache.disconnect())
+```
+
 ## FastAPI example
 
 Install FastAPI in your app (`pip install fastapi` or use `yokedcache[full]`).

pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 [project]
 name = "yokedcache"
 dynamic = ["version"]
-description = "Async multi-backend cache (memory, Redis, Memcached, disk, SQLite) with tag invalidation, optional HTTP middleware, and production metrics"
+description = "Async-first multi-backend cache (memory, Redis, Memcached, disk, SQLite); sync helpers for scripts; tag invalidation, optional HTTP middleware, metrics"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
@@ -17,6 +17,7 @@ authors = [
 ]
 keywords = [
     "async cache",
+    "sync helpers",
     "cache invalidation",
     "multi-backend cache",
     "redis",

scripts/build_docs_site.py

@@ -3,12 +3,14 @@
 
 from __future__ import annotations
 
+import json
 import os
 import re
 import shutil
 import sys
 from pathlib import Path
 from urllib.parse import urlparse
+from urllib.request import Request, urlopen
 
 import markdown
 from jinja2 import Environment, FileSystemLoader, select_autoescape
@@ -22,6 +24,8 @@
 OUT = ROOT / "site"
 INIT_PY = ROOT / "src" / "yokedcache" / "__init__.py"
 
+PYPI_PACKAGE = "yokedcache"
+
 SITE_URL = "https://sirstig.github.io/yokedcache"
 GITHUB_REPO = "https://github.com/sirstig/yokedcache"
 
@@ -77,6 +81,22 @@ def read_version() -> str:
     return m.group(1) if m else "0.0.0"
 
 
+def fetch_pypi_latest_version(timeout: float = 4.0) -> str | None:
+    url = f"https://pypi.org/pypi/{PYPI_PACKAGE}/json"
+    req = Request(url, headers={"User-Agent": "yokedcache-docs-build/1"})
+    try:
+        with urlopen(req, timeout=timeout) as resp:
+            data = json.load(resp)
+        ver = data.get("info", {}).get("version")
+        return ver if isinstance(ver, str) and ver else None
+    except OSError:
+        return None
+
+
+def resolve_public_version() -> str:
+    return fetch_pypi_latest_version() or read_version()
+
+
 def md_to_html_path(md_rel: str) -> str:
     return Path(md_rel).with_suffix(".html").as_posix()
 
@@ -206,7 +226,7 @@ def _skip_root_html(src: str, names: list[str]) -> set[str]:
         },
     )
 
-    version = read_version()
+    version = resolve_public_version()
 
     for _group_label, items in NAV:
         for _title, src in items:

site-src/assets/style.css

@@ -520,6 +520,19 @@ tbody tr:hover td { background: var(--glass); }
   margin: 0 auto;
 }
 
+.hero-meta {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-wrap: wrap;
+  gap: 0.6rem 1rem;
+  margin-bottom: 1.5rem;
+}
+
+.hero-meta .hero-eyebrow { margin-bottom: 0; }
+
+.hero-version { text-transform: none; letter-spacing: 0.02em; }
+
 .hero-eyebrow {
   display: inline-flex;
   align-items: center;

site-src/pages/core-concepts.md

@@ -367,7 +367,7 @@ logging.getLogger("yokedcache").setLevel(logging.INFO)
 
 - **Connection Pooling**: YokedCache maintains connection pools automatically
 - **Pool Sizing**: Configure `max_connections` based on concurrency needs
-- **Async Operations**: Use async/await consistently for best performance
+- **Async vs sync**: Prefer async/await in hot paths and inside frameworks; `*_sync` is fine for scripts and low-volume blocking code
 
 ### Batch Operations
 

site-src/pages/getting-started.md

@@ -1,12 +1,12 @@
 ---
 title: Getting Started with YokedCache
-description: Install YokedCache, choose a cache backend (memory or Redis), and use the same async API across FastAPI, Starlette, or plain asyncio.
-keywords: yokedcache, installation, async cache, redis, memcached, multi-backend
+description: Install YokedCache, pick a backend (memory or Redis), and use the async-first API—or sync helpers—in FastAPI, scripts, or asyncio.
+keywords: yokedcache, installation, async cache, sync helpers, redis, memcached, multi-backend
 ---
 
 # Getting Started with YokedCache
 
-Install the package, pick a **backend** (in-process memory by default, or Redis for production), and use one async API everywhere. Invalidation, tags, and patterns work the same no matter which store you use.
+Install the package, pick a **backend** (in-process memory by default, or Redis for production). The main methods are async (`await cache.get(...)`). Invalidation, tags, and patterns work the same on every store. If you are in sync-only code, use `get_sync` / `set_sync` or `@cached` on a plain function—same implementation underneath.
 
 ## Installation
 
@@ -105,6 +105,24 @@ With `yokedcache[redis]` and Redis running:
 yokedcache ping
 ```
 
+## Using from sync code
+
+Prefer `await` when you already have an event loop (for example inside FastAPI). **`_sync` methods are for blocking contexts**—do not use them from inside a running loop; use `await cache.get(...)` there instead.
+
+```python
+import asyncio
+from yokedcache import YokedCache
+from yokedcache.config import CacheConfig
+
+cache = YokedCache(CacheConfig())
+asyncio.run(cache.connect())
+cache.set_sync("user:1", {"name": "Ada"}, ttl=60)
+print(cache.get_sync("user:1"))
+asyncio.run(cache.disconnect())
+```
+
+You can also put `@cached` on a normal `def`; it will use the sync cache path automatically.
+
 ## Your First Cache
 
 Let's start with a simple example that demonstrates core caching concepts.

site-src/pages/performance.md

@@ -25,3 +25,8 @@
 
 - Reuse a single `YokedCache` instance; avoid reconnecting per request.
 - Use pipeline where appropriate (handled internally for set/tag ops).
+
+## Sync helpers
+
+- `get_sync` / `set_sync` / `delete_sync` / `exists_sync` each run the async work via `asyncio.run`; reuse one cache instance, but avoid tight loops of many `*_sync` calls if throughput matters.
+- Prefer `await` inside apps that already have an event loop.

site-src/static/llms.txt

@@ -1,10 +1,11 @@
 # yokedcache
 
-> MIT-licensed async Python cache: same API for in-process memory, Redis, Memcached, disk, and SQLite; tag/pattern invalidation; optional Starlette HTTP middleware and metrics.
+> MIT-licensed Python cache: async-first, same API for in-process memory, Redis, Memcached, disk, and SQLite; sync helpers (`*_sync`, `@cached` on plain functions); tag/pattern invalidation; optional Starlette HTTP middleware and metrics.
 
 ## Summary
 
 - Package: yokedcache (PyPI). **Python 3.10+** (CI: 3.10–3.14). Plain `pip install yokedcache` uses **embedded memory** when `redis` is not installed (1.0.1+). Add `yokedcache[redis]` for Redis, `yokedcache[web]` for HTTP middleware, `yokedcache[full]` for the full optional stack.
+- **Async-first** (`await` for `get` / `set` / `connect`). **Sync-friendly**: `get_sync` / `set_sync` / `delete_sync` / `exists_sync` and `@cached` on a normal `def` use the same async-backed implementation—not a separate blocking Redis client.
 - Docs: https://sirstig.github.io/yokedcache/
 - API (HTML): https://sirstig.github.io/yokedcache/api/
 - Changelog: https://sirstig.github.io/yokedcache/changelog.html

site-src/templates/index.html.jinja2

@@ -3,8 +3,8 @@
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>YokedCache — Async multi-backend cache for Python</title>
-  <meta name="description" content="Async Python cache with the same API across memory, Redis, Memcached, disk, and SQLite. Tag invalidation, optional Starlette HTTP caching, metrics, and FastAPI-friendly helpers. MIT licensed.">
+  <title>YokedCache — Multi-backend Python cache (async-first)</title>
+  <meta name="description" content="Async-first Python cache across memory, Redis, Memcached, disk, and SQLite. Sync helpers for scripts and plain functions. Tag invalidation, optional HTTP caching, metrics. MIT licensed.">
   <meta name="keywords" content="python, async cache, redis, memcached, sqlalchemy, caching, cache invalidation, starlette, fastapi, prometheus, yokedcache, Joshua Kac, Project Yoked">
   <meta name="author" content="Joshua Kac">
   <meta name="robots" content="index,follow">
@@ -15,15 +15,15 @@
   <meta property="og:type" content="website">
   <meta property="og:locale" content="en_US">
   <meta property="og:url" content="{{ home_canonical }}">
-  <meta property="og:title" content="YokedCache — Async multi-backend cache for Python">
-  <meta property="og:description" content="Async Python cache with the same API across memory, Redis, Memcached, disk, and SQLite. Tag invalidation, optional HTTP middleware, metrics. MIT licensed.">
+  <meta property="og:title" content="YokedCache — Multi-backend Python cache (async-first)">
+  <meta property="og:description" content="Async-first cache across memory, Redis, Memcached, disk, SQLite. Sync helpers when you need them. Invalidation, optional HTTP middleware, metrics. MIT licensed.">
   <meta property="og:image" content="{{ og_image_url }}">
   <meta property="og:image:width" content="1200">
   <meta property="og:image:height" content="630">
   <meta property="og:site_name" content="YokedCache">
   <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="YokedCache — Async multi-backend cache for Python">
-  <meta name="twitter:description" content="Same async API for memory, Redis, Memcached, disk, and SQLite. Invalidation, optional HTTP caching, observability. MIT licensed.">
+  <meta name="twitter:title" content="YokedCache — Multi-backend Python cache (async-first)">
+  <meta name="twitter:description" content="Async-first; sync helpers for scripts. Same API across memory, Redis, Memcached, disk, SQLite. Invalidation, HTTP caching, observability. MIT licensed.">
   <meta name="twitter:image" content="{{ og_image_url }}">
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
@@ -41,7 +41,7 @@
     "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" },
     "url": "{{ site_url }}",
     "downloadUrl": "https://pypi.org/project/yokedcache/",
-    "description": "Async multi-backend Python cache: memory, Redis, Memcached, disk, SQLite; tag invalidation; optional Starlette HTTP caching.",
+    "description": "Async-first multi-backend Python cache (memory, Redis, Memcached, disk, SQLite) with sync helpers; tag invalidation; optional Starlette HTTP caching.",
     "codeRepository": "{{ github_repo }}",
     "license": "https://opensource.org/licenses/MIT",
     "author": {
@@ -94,11 +94,14 @@
 
   <div class="landing">
     <section class="hero">
-      <div class="hero-eyebrow">Open source · MIT License</div>
-      <h1>One async cache API,<br>your choice of backend</h1>
+      <div class="hero-meta">
+        <div class="hero-eyebrow">Open source · MIT License</div>
+        <a class="header-badge hero-version" href="https://pypi.org/project/yokedcache/{{ version }}/" target="_blank" rel="noopener" title="Latest release on PyPI" aria-label="Latest release on PyPI, version {{ version }}">v{{ version }}</a>
+      </div>
+      <h1>One cache API,<br>your choice of backend</h1>
       <p class="hero-sub">
-        Memory, Redis, Memcached, disk, or SQLite — same invalidation and patterns.
-        Optional Starlette HTTP caching, FastAPI-ready decorators, metrics, and a small CLI.
+        Async-first across memory, Redis, Memcached, disk, and SQLite — same invalidation and patterns.
+        Sync helpers when you are not in an async app. Optional HTTP caching, FastAPI decorators, metrics, CLI.
       </p>
       <div class="install-pill">
         <span class="prompt">$</span>
@@ -134,8 +137,8 @@
       </div>
       <div class="feature-card">
         <div class="feature-icon">◇</div>
-        <h3>Async everywhere</h3>
-        <p>Use from FastAPI, Starlette, Django async views, workers, or plain <code>asyncio</code>. Optional dependency helpers for FastAPI.</p>
+        <h3>Fits async and sync</h3>
+        <p>Use <code>await</code> in FastAPI, Starlette, Django async, and workers. For blocking code, <code>get_sync</code> / <code>set_sync</code> or <code>@cached</code> on a normal function.</p>
       </div>
       <div class="feature-card">
         <div class="feature-icon">◇</div>

src/yokedcache/__init__.py

@@ -1,8 +1,9 @@
 """
-YokedCache — async caching with pluggable backends and tag-based invalidation.
+YokedCache — async-first caching with pluggable backends and tag-based invalidation.
 
-Core installs use an in-memory store unless you add optional extras (e.g. ``redis``,
-``web`` for Starlette HTTP middleware, ``memcached``, ``full``).
+Use ``await`` in apps; ``get_sync`` / ``set_sync`` and ``@cached`` on plain functions
+for sync code. Core installs use in-memory storage unless you add extras (``redis``,
+``web``, ``memcached``, ``full``, etc.).
 """
 
 __version__ = "1.0.1"