handbook/docs/libraries.md

# Libraries

The shared `rethink-public` library suite. Before hand-rolling common
functionality — retry/backoff, logging setup, HTTP sessions, proxies, webhooks,
IMAP/mail, datastore/KV, crypto, `discord.py` helpers, timing/paths/masking
utilities — check here first and prefer an existing lib.

This list is pulled live from Gitea, so a new library in the org shows up on the
next page load — nothing here is rebuilt or version-pinned. Each entry links to
the repo, where the README and tags live.

## Install

Pin a tag in your dependencies — never an unpinned branch:

```
<lib> @ git+https://git.rethinkstudios.io/rethink-public/<lib>.git@<tag>
```

??? example "Using a library — install, import, go"

    Add it to your project's deps (e.g. `pyproject.toml`):

    ```toml
    [project]
    dependencies = [
        "aioweb @ git+https://git.rethinkstudios.io/rethink-public/aioweb.git@v0.3.1",
    ]
    ```

    Then use it — the README in each repo has the real surface; this is the shape:

    ```python
    import asyncio

    from aioweb import Session


    async def main() -> None:
        """fetch a page through the shared async http session"""
        async with Session() as web:
            resp = await web.get("https://example.test")
            print(resp.status, len(resp.content))


    asyncio.run(main())
    ```

    Need to bump a lib? Change the `@<tag>` and reinstall — versions live with the
    lib, not in these docs.

<div id="lib-list" markdown="0">
  <p class="lib-status">Loading libraries from Gitea…</p>
</div>

<script>
(function () {
  var API = "https://git.rethinkstudios.io/api/v1/orgs/rethink-public/repos?limit=50";
  var REPO_BASE = "https://git.rethinkstudios.io/rethink-public";
  var FALLBACK =
    'Could not load the live list. View the libraries directly at ' +
    '<a href="' + REPO_BASE + '">git.rethinkstudios.io/rethink-public</a>.';

  // Non-library repos to exclude from the render.
  var DENYLIST = ["handbook", ".profile", ".profile-private"];

  function isLibrary(repo) {
    if (!repo || !repo.name) return false;
    if (repo.name.charAt(0) === ".") return false;        // any dot-repo
    return DENYLIST.indexOf(repo.name) === -1;
  }

  function escapeHtml(s) {
    return String(s == null ? "" : s)
      .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
      .replace(/"/g, "&quot;");
  }

  function render(repos) {
    var libs = repos.filter(isLibrary).sort(function (a, b) {
      return a.name.localeCompare(b.name);
    });
    var el = document.getElementById("lib-list");
    if (!libs.length) {
      el.innerHTML = '<p class="lib-status">No libraries found. Browse the org at ' +
        '<a href="' + REPO_BASE + '">git.rethinkstudios.io/rethink-public</a>.</p>';
      return;
    }
    var rows = libs.map(function (r) {
      var url = r.html_url || (REPO_BASE + "/" + r.name);
      var desc = r.description ? escapeHtml(r.description) : "<em>No description.</em>";
      var lang = r.language
        ? '<span class="rt-lang">' + escapeHtml(r.language) + "</span>"
        : '<span class="rt-lang rt-lang--none">—</span>';
      return '<tr><td><a href="' + escapeHtml(url) + '"><code>' +
        escapeHtml(r.name) + "</code></a></td><td>" + desc +
        "</td><td>" + lang + "</td></tr>";
    }).join("");
    el.innerHTML =
      '<div class="rt-lib-table"><table>' +
      "<thead><tr><th>Library</th><th>What it does</th><th>Language</th></tr></thead>" +
      "<tbody>" + rows + "</tbody></table></div>";
  }

  function fail() {
    document.getElementById("lib-list").innerHTML =
      '<p class="lib-status">' + FALLBACK + '</p>';
  }

  try {
    fetch(API, { headers: { "Accept": "application/json" } })
      .then(function (resp) {
        if (!resp.ok) throw new Error("HTTP " + resp.status);
        return resp.json();
      })
      .then(function (data) {
        if (!Array.isArray(data)) throw new Error("unexpected response");
        render(data);
      })
      .catch(fail);
  } catch (e) {
    fail();
  }
})();
</script>

!!! info "If the live list is empty or stale"
    The fetch runs in your browser against the Gitea API and needs the org repos
    to be readable unauthenticated (they are — it's a public org) and CORS to
    allow the docs domain. If the list won't load, browse the org directly at
    [git.rethinkstudios.io/rethink-public](https://git.rethinkstudios.io/rethink-public).
    The fallback for a disabled live fetch is a webhook rebuild — a push to any
    `rethink-public` repo triggers a site rebuild.