csiapps 0.1.0__tar.gz

csiapps-0.1.0/.claude/launch.json

@@ -0,0 +1,17 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "example-app",
+      "runtimeExecutable": "uv",
+      "runtimeArgs": ["run", "shiny", "run", "--port", "8123", "examples/app.py"],
+      "port": 8123
+    },
+    {
+      "name": "docs",
+      "runtimeExecutable": "uv",
+      "runtimeArgs": ["run", "--group", "docs", "mkdocs", "serve", "-a", "localhost:8000"],
+      "port": 8000
+    }
+  ]
+}

csiapps-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install deps
+        run: uv sync --python ${{ matrix.python-version }}
+      - name: Lint
+        run: uv run ruff check .
+      - name: Test
+        run: uv run pytest

csiapps-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,19 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+
+# Needed for mkdocs gh-deploy to push the built site to the gh-pages branch.
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      - name: Build and deploy docs
+        run: uv run --group docs mkdocs gh-deploy --force

csiapps-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Environments
+.venv/
+venv/
+.env
+
+# Docs / build output
+site/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# uv
+uv.lock
+
+# OS
+.DS_Store

csiapps-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 csiapps authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

csiapps-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: csiapps
+Version: 0.1.0
+Summary: Helper functions and utilities for CSI data warehouse ingestion and Shiny web applications (Python port of the csiapps R package).
+Project-URL: Homepage, https://github.com/CSIOntario/csiapps-py
+Project-URL: Issues, https://github.com/CSIOntario/csiapps-py/issues
+Author: Kyu Min Shim
+Author-email: David Awosoga <dawosoga@csiontario.ca>
+License: MIT License
+        
+        Copyright (c) 2026 csiapps authors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: csi,csiontario,oauth2,shiny,warehouse
+Requires-Python: >=3.10
+Requires-Dist: faker>=25
+Requires-Dist: httpx>=0.27
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: shiny>=1.0
+Description-Content-Type: text/markdown
+
+# csiapps (Python)
+
+Python port of the CSIO [`csiapps`](https://github.com/CSIOntario/csiapps) R
+package. Helper functions and utilities for CSI data warehouse ingestion and
+[Shiny for Python](https://shiny.posit.co/py/) web applications.
+
+Full feature parity with the R package: the API client (`make_request`,
+`fetch_*`), the local sandbox (schema → ingest → retrieve, plus a dummy
+registration registry), and the Shiny app wrappers (`ui_wrapper`,
+`server_wrapper`). **Sandbox mode is on by default** so nothing hits production
+by accident.
+
+## Installation
+
+```bash
+pip install csiapps
+```
+
+## Quickstart
+
+```python
+import csiapps
+
+csiapps.register_sandbox_schema("demo", {
+    "type": "object", "required": ["id"],
+    "properties": {"id": {"type": "string"}},
+})
+csiapps.make_request("api/warehouse/ingestion/primary/", method="POST",
+    body={"source": "demo", "records": [{"id": "a1"}], "subject_field": "id"})
+page = csiapps.make_request("api/warehouse/data-records", query={"source_uuid": "demo"})
+print(page["count"])   # 1
+```
+
+See the [cross-language documentation](https://csiontario.github.io/csiapps-py/)
+(R and Python side by side, plus a [parity checklist](https://csiontario.github.io/csiapps-py/parity/))
+and the runnable [`examples/`](examples/) (`warehouse_ingest.py`, `app.py`).
+
+## Development
+
+Uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync                        # install deps + dev tools
+uv run pytest                  # run tests
+uv run ruff check .            # lint
+uv run --group docs mkdocs serve   # preview docs
+uv build                       # build sdist + wheel
+```

csiapps-0.1.0/PORTING_PLAN.md

@@ -0,0 +1,184 @@
+# csiapps: R → Python porting plan
+
+Port of the CSIO [`csiapps`](https://github.com/CSIOntario/csiapps) R package to
+Python, with full feature parity. Target web framework for the app-wrapper
+layer: **[Shiny for Python](https://shiny.posit.co/py/)** (chosen because it is a
+near-1:1 match for the R Shiny wrapper).
+
+## The package is three layers
+
+| Layer | R source | Nature | Port difficulty |
+|---|---|---|---|
+| **API client** | `R/utils.R` | HTTP + OAuth2 PKCE + JSON, pure logic | Mechanical |
+| **Sandbox** | `R/sandbox.R` | In-memory warehouse emulation, JSON-schema validation, dummy data registry | Mechanical (two dep swaps) |
+| **App wrapper** | `R/shiny.R` | Shiny UI/server wrapper, navbar/footer chrome, in-app OAuth redirect | Mechanical *because* target is Shiny for Python |
+
+## Repository decision
+
+Separate repo (`csiapps-py`, publishing package `csiapps` to PyPI) rather than a
+monorepo or mixing into the R repo. R packaging artifacts (`DESCRIPTION`,
+`NAMESPACE`, `man/`, roxygen, pkgdown) don't coexist cleanly with
+`pyproject.toml`/pytest/ruff. The two implementations stay in sync via the
+**shared REST API contract + JSON schemas**, not shared code.
+
+## Dependency mapping
+
+Most R deps collapse to Python stdlib.
+
+| R dependency | Used for | Python replacement |
+|---|---|---|
+| `httr2` | HTTP requests, retries, pagination | `httpx` |
+| `httr2` OAuth2 PKCE helpers | auth flow | **stdlib** `secrets` + `hashlib.sha256` + `base64.urlsafe_b64encode` |
+| `jsonlite` | JSON parse/serialize | **stdlib** `json` |
+| `openssl` | base64, `rand_bytes` | **stdlib** `base64`, `secrets` |
+| `jsonvalidate` (Ajv) | sandbox schema validation | `jsonschema` |
+| `babynames` | random dummy athlete names | `faker` |
+| `shiny` / `shinyjs` | app wrapper | `shiny` (Shiny for Python); `shinyjs` → custom-message JS handler |
+
+Runtime deps: `httpx`, `jsonschema`, `faker`, `shiny`. Everything else is stdlib.
+
+## Function map (mirrors the R `NAMESPACE`)
+
+All exported functions carry over; names stay `snake_case`.
+
+**config.py** — `set_institute`, `is_sandbox_mode`. R uses a `package_state`
+environment + `options(csiapps.sandbox=)` + `CSIAPPS_ENV`. Python: module-level
+state object + `CSIAPPS_ENV` env var. Do **not** build a Config class — mirror
+the R global.
+
+**auth.py** — `check_secrets`, PKCE helpers (`pkce_state_encode/decode`,
+base64url), `exchange_code_for_token`. All stdlib, ~30 lines of PKCE.
+
+**client.py** — `make_request` (with `paginate`, `sandbox` dispatch),
+`fetch_org_options`, `fetch_profiles` (auto-paginate), `fetch_profile`.
+Two-tier token resolution `.current_token()`: per-session token first, then
+`CSIAPPS_ACCESS_TOKEN` env var.
+
+**sandbox.py** — `register_sandbox_schema`, `clear_sandbox`, `browse_sandbox`,
+`create_sport_org`, `create_profile`, plus the internal request router
+(`data-sources/{uuid}`, `ingestion/primary`, `data-records`) and
+`sandbox_ingest`. Keep **read-time** subject resolution so athletes registered
+after ingestion backfill.
+
+**app.py** — `ui_wrapper`, `server_wrapper`, navbar/footer/CSS chrome, sandbox
+banner, `/me` load, logout re-seed. (`global_wrapper` was ported then dropped in
+the ponytail audit — a no-op in Python; module scope covers the R use case.)
+
+### Shiny R → Shiny for Python
+
+| R (Shiny) | Python (Shiny for Python) |
+|---|---|
+| `reactiveVal(NULL)` | `reactive.value(None)` |
+| `observe({...})` | `@reactive.effect` |
+| `observeEvent(x(), {...})` | `@reactive.effect` + `@reactive.event(x)` |
+| `renderUI` / `uiOutput` | `@render.ui` / `ui.output_ui` |
+| `tags$div`, `HTML`, `tagList`, `fluidPage` | `ui.tags.div`, `ui.HTML`, `ui.TagList`, `ui.page_fluid` |
+| `session$sendCustomMessage(...)` | `session.send_custom_message` |
+| `getDefaultReactiveDomain()` | `shiny.session.get_current_session()` |
+| `parseQueryString(session$clientData$url_search)` | `session.clientdata.url_search()` |
+
+Two gotchas:
+
+* **`shinyjs` has no Python port.** Only used for
+  `runjs("window.location.href = ...")`. Replace with the same custom-message
+  handler the redirect already uses — no dependency; `useShinyjs()` drops out.
+* **Per-session token** (`session$userData$csiapps_token`): implemented as a
+  `WeakKeyDictionary` keyed on the Shiny session (`client.set_session_token`),
+  read back by `client.current_token()` via `shiny.session.get_current_session()`,
+  falling back to `CSIAPPS_ACCESS_TOKEN`. (A `contextvar`, tried in phase 3, does
+  **not** work: Shiny reactive contexts don't propagate it across effects.)
+
+## Verification strategy
+
+The R package's `testthat` suite is the spec. Port each test to `pytest`
+alongside the module it covers:
+
+| R test | Python |
+|---|---|
+| `tests/testthat/test-sandbox.R` | `tests/test_sandbox.py` |
+| `tests/testthat/test-sandbox-wrapper.R` | `tests/test_sandbox_wrapper.py` |
+| `tests/testthat/test-sandbox-registry.R` | `tests/test_sandbox_registry.py` |
+| `tests/testthat/test-sandbox-mode.R` | `tests/test_sandbox_mode.py` |
+
+## Phases
+
+- [x] **Phase 1 — Scaffold.** New repo, `pyproject.toml` (uv/hatchling), CI
+  (pytest + ruff), package skeleton, this plan.
+- [x] **Phase 2 — config + auth.** `config.py` (set_institute, is_sandbox_mode,
+  set_sandbox_mode, URL helpers) + `auth.py` (PKCE stdlib, token exchange,
+  check_secrets). Ported the `is_sandbox_mode` portion of `test-sandbox-mode.R`
+  plus PKCE round-trip / token-exchange / check_secrets tests (16 passing).
+- [x] **Phase 3 — client.** `client.py`: `make_request` (retry + pagination),
+  `fetch_org_options`, `fetch_profiles` (auto-paginate), `fetch_profile`, and
+  per-session `current_token()` (contextvar → `CSIAPPS_ACCESS_TOKEN`). Sandbox
+  branches delegate to `csiapps.sandbox` internals (lazy import) landing in
+  phase 4. HTTP paths tested with `respx` (27 passing).
+
+  > **Phase 4 must provide these in `sandbox.py`:** `_make_sandbox_request(...)`,
+  > `_sandbox_org_options()`, `_sandbox_profiles(sport_org_id)`,
+  > `_sandbox_profile(profile_id)` — the delegation targets `client.py` calls.
+  > `flatten_record` (R internal, unexported, uncalled within the package) was
+  > **skipped**; add it only if a consuming app actually needs it.
+- [x] **Phase 4 — sandbox.** `sandbox.py`: request router, ingest + Draft-7
+  `jsonschema` validation, dummy sport-org/athlete registry (`faker` names),
+  read-time subject resolution, and the four `_sandbox_*` delegation functions
+  `client.py` calls. Ported `test-sandbox.R`, `test-sandbox-registry.R`, the
+  `make_request` routing + `fetch_*` sandbox cases (69 passing total). Validator
+  wording adapted Ajv→jsonschema ("too short" vs "fewer than 10 characters").
+  `flatten_record` and its test remain skipped (see phase 3 note).
+- [x] **Phase 5 — app wrapper.** `app.py` (Shiny for Python): `ui_wrapper`
+  (navbar/footer/chrome, sandbox banner, auth-status), `server_wrapper` (OAuth2
+  PKCE login + simulated sandbox login, per-session token, `/me` load, logout),
+  `global_wrapper`. `shinyjs` dropped (replaced by a `csip_reset`
+  custom-message handler); message-sending effects are `async`. Ported the
+  `ui_wrapper`/`server_wrapper`/`global_wrapper` cases from
+  `test-sandbox-wrapper.R` (77 passing); the deep `testServer` reactive cases
+  have no simple Shiny-for-Python equivalent, so sandbox-seed + auth-status
+  logic is covered via extracted pure helpers, and a real `App` is smoke-built.
+  Phase 3's token mechanism was corrected here (contextvar → session
+  `WeakKeyDictionary`).
+- [x] **Phase 6 — docs + packaging.** mkdocs-material + mkdocstrings site
+  (`mkdocs.yml`, `docs/`), runnable `examples/` (`warehouse_ingest.py`,
+  `app.py`), README quickstart. `uv build` produces sdist + wheel; wheel
+  verified to install and import in a clean venv.
+  **PyPI publish is intentionally NOT done here** — it is an outward-facing
+  release and requires credentials the assistant cannot handle. Publish with
+  `uv publish` (or `twine upload dist/*`) when ready.
+
+Phases 1–4 are framework-independent and safe to build in any order after 1.
+
+## Dashboard dogfooding findings (fixed)
+
+Building a real Shiny for Python dashboard against the package surfaced three
+issues from common workflows, all fixed:
+
+1. **`fetch_org_options` shape** — returned R's `[{"label","value"}]`, which
+   crashed `ui.input_select` (`TypeError: unhashable type: 'dict'`). Now returns
+   a `{value: label}` dict that feeds `input_select(choices=...)` directly.
+   Deliberate divergence from R (whose shape suited `selectInput`).
+2. **No path from nested results to a table** — `fetch_profiles` returns deeply
+   nested dicts; `render.DataGrid` rejected them ("Unsupported dataframe type").
+   Added `flatten_profile` producing scalar rows; docs show wrapping in a
+   pandas/polars frame (kept out of package deps).
+3. **Fixed-bottom footer overlapped content** — the R wrapper's
+   `padding-bottom: 80px` was dropped in the port; restored in `ui_wrapper`.
+
+## Ponytail audit cleanup
+
+Repo-wide over-engineering pass, all applied: dropped `global_wrapper` (no-op in
+Python) and `flatten_record` (no caller; only `flatten_profile` is used); deleted
+`config.clear_token` (dead) and `tests/test_smoke.py` (redundant vs 78 real
+tests); hoisted the duplicated `_message` helper into `config`; inlined the
+`_rmtree` wrapper to `shutil.rmtree`. ~55 lines removed, no dep changes.
+
+## Parity caveats carried over from R
+
+* **Validation parity is approximate.** Sandbox ingestion validates against the
+  JSON Schema with `jsonschema` (Python) where R used Ajv via `jsonvalidate`.
+  Validators differ on edge cases (e.g. `format` keyword enforcement), and the
+  real server enforces things the schema can't (subject resolution against
+  registered profiles, duplicate/dataset handling, token permissions). A green
+  sandbox run is **necessary but not sufficient** for production acceptance.
+* **Subject linkage** is emulated only for athletes registered with
+  `create_profile()`, resolved at read time; unresolved → `subject = None`
+  (production would reject).

csiapps-0.1.0/README.md

@@ -0,0 +1,48 @@
+# csiapps (Python)
+
+Python port of the CSIO [`csiapps`](https://github.com/CSIOntario/csiapps) R
+package. Helper functions and utilities for CSI data warehouse ingestion and
+[Shiny for Python](https://shiny.posit.co/py/) web applications.
+
+Full feature parity with the R package: the API client (`make_request`,
+`fetch_*`), the local sandbox (schema → ingest → retrieve, plus a dummy
+registration registry), and the Shiny app wrappers (`ui_wrapper`,
+`server_wrapper`). **Sandbox mode is on by default** so nothing hits production
+by accident.
+
+## Installation
+
+```bash
+pip install csiapps
+```
+
+## Quickstart
+
+```python
+import csiapps
+
+csiapps.register_sandbox_schema("demo", {
+    "type": "object", "required": ["id"],
+    "properties": {"id": {"type": "string"}},
+})
+csiapps.make_request("api/warehouse/ingestion/primary/", method="POST",
+    body={"source": "demo", "records": [{"id": "a1"}], "subject_field": "id"})
+page = csiapps.make_request("api/warehouse/data-records", query={"source_uuid": "demo"})
+print(page["count"])   # 1
+```
+
+See the [cross-language documentation](https://csiontario.github.io/csiapps-py/)
+(R and Python side by side, plus a [parity checklist](https://csiontario.github.io/csiapps-py/parity/))
+and the runnable [`examples/`](examples/) (`warehouse_ingest.py`, `app.py`).
+
+## Development
+
+Uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync                        # install deps + dev tools
+uv run pytest                  # run tests
+uv run ruff check .            # lint
+uv run --group docs mkdocs serve   # preview docs
+uv build                       # build sdist + wheel
+```

csiapps-0.1.0/docs/api.md

@@ -0,0 +1,37 @@
+# Python API reference
+
+Everything exported from the top-level `csiapps` Python package. For the R
+package, see the [R reference](https://csiontario.github.io/csiapps/reference/)
+(pkgdown); for how the two map onto each other, see the
+[parity checklist](parity.md).
+
+## Configuration
+
+::: csiapps.config.set_institute
+::: csiapps.config.is_sandbox_mode
+::: csiapps.config.set_sandbox_mode
+
+## Authentication
+
+::: csiapps.auth.check_secrets
+
+## Client
+
+::: csiapps.client.make_request
+::: csiapps.client.fetch_org_options
+::: csiapps.client.fetch_profiles
+::: csiapps.client.fetch_profile
+::: csiapps.client.flatten_profile
+
+## Sandbox
+
+::: csiapps.sandbox.register_sandbox_schema
+::: csiapps.sandbox.create_sport_org
+::: csiapps.sandbox.create_profile
+::: csiapps.sandbox.clear_sandbox
+::: csiapps.sandbox.browse_sandbox
+
+## App wrappers
+
+::: csiapps.app.ui_wrapper
+::: csiapps.app.server_wrapper

csiapps-0.1.0/docs/index.md

@@ -0,0 +1,78 @@
+# csiapps
+
+Helper functions and utilities for CSI data warehouse ingestion and
+[Shiny](https://shiny.posit.co/) web applications. `csiapps` ships as **two
+packages with full feature parity** — one for R, one for Python — so a team can
+work in either language against the same CSIAPPS warehouse and registration API.
+
+This site documents **both**: every tutorial shows the R and the Python code
+side by side. Pick your language with the tabs and it stays selected across the
+whole page.
+
+The library has three layers:
+
+- **API client** — `make_request`, `fetch_org_options`, `fetch_profiles`,
+  `fetch_profile`, with OAuth2 PKCE auth.
+- **Sandbox** — a local, in-memory emulation of the warehouse and registration
+  API so you can develop the full schema → ingest → retrieve workflow with no
+  network and no credentials. **Sandbox mode is on by default.**
+- **App wrapper** — `ui_wrapper` / `server_wrapper` add a consistent CSI
+  navbar/footer and handle authentication for a Shiny app.
+
+## Installation
+
+=== "R"
+
+    ```r
+    # install.packages("remotes")
+    remotes::install_github("CSIOntario/csiapps")
+    ```
+
+=== "Python"
+
+    ```bash
+    pip install csiapps
+    ```
+
+## Sandbox mode is the default
+
+Every call routes to the local sandbox until you explicitly turn it off, so you
+never hit the production warehouse by accident:
+
+=== "R"
+
+    ```r
+    library(csiapps)
+
+    is_sandbox_mode()   # TRUE
+
+    # Turn it off for deployment:
+    options(csiapps.sandbox = FALSE)   # or set CSIAPPS_ENV=production
+    ```
+
+=== "Python"
+
+    ```python
+    import csiapps
+
+    csiapps.is_sandbox_mode()   # True
+
+    # Turn it off for deployment:
+    csiapps.set_sandbox_mode(False)          # or set CSIAPPS_ENV=production
+    ```
+
+## Where to go next
+
+- **[Shiny apps](shiny-apps.md)** — wrap an app's UI and server with CSIAPPS
+  authentication and chrome.
+- **[REST API](rest-api.md)** — `make_request` and the registration helpers.
+- **[Sandbox mode](sandbox.md)** — the full local warehouse/registration
+  workflow.
+- **[Parity checklist](parity.md)** — how each R function maps to its Python
+  equivalent.
+
+## Function reference
+
+- **Python:** [Python reference](api.md) (on this site).
+- **R:** [R reference](https://csiontario.github.io/csiapps/reference/)
+  (pkgdown).

csiapps-0.1.0/docs/parity.md

@@ -0,0 +1,85 @@
+# Parity checklist
+
+This page is a translation guide for the operational parity between the R and
+Python versions of `csiapps`. Each row is a capability; the R and Python columns
+give the function(s) that provide it. An empty cell marks a capability that
+exists in only one language (see the notes below for why).
+
+The two packages have **full feature parity** — every capability is available in
+both — with two exceptions that are intentional and explained under
+[Intentional divergences](#intentional-divergences).
+
+## Configuration
+
+| Capability | R | Python |
+|---|---|---|
+| Set the target institute | `set_institute()` | `set_institute()` |
+| Check whether sandbox mode is on | `is_sandbox_mode()` | `is_sandbox_mode()` |
+| Force sandbox mode on/off | `options(csiapps.sandbox = )` | `set_sandbox_mode()` |
+| Check auth environment / secrets | `check_secrets()` | `check_secrets()` |
+
+## REST API client
+
+| Capability | R | Python |
+|---|---|---|
+| Authenticated request to any endpoint | `make_request()` | `make_request()` |
+| Fetch organisation options | `fetch_org_options()` | `fetch_org_options()` |
+| Fetch profiles (auto-paginating) | `fetch_profiles()` | `fetch_profiles()` |
+| Fetch a single profile by id | `fetch_profile()` | `fetch_profile()` |
+| Flatten a profile into a table row |  | `flatten_profile()` |
+
+## Sandbox
+
+| Capability | R | Python |
+|---|---|---|
+| Register a JSON schema for a source | `register_sandbox_schema()` | `register_sandbox_schema()` |
+| Create a dummy sport organization | `create_sport_org()` | `create_sport_org()` |
+| Create dummy athlete profiles | `create_profile()` | `create_profile()` |
+| Clear sandbox state | `clear_sandbox()` | `clear_sandbox()` |
+| Open the sandbox payload folder | `browse_sandbox()` | `browse_sandbox()` |
+
+## Shiny app wrappers
+
+| Capability | R | Python |
+|---|---|---|
+| Wrap app UI (navbar/footer/auth status) | `ui_wrapper()` | `ui_wrapper()` |
+| Wrap app server (OAuth2 / sandbox login) | `server_wrapper()` | `server_wrapper()` |
+| Make globals visible to the server | `global_wrapper()` |  |
+
+## Intentional divergences
+
+These are the only differences in the public surface, and each exists for a
+concrete reason:
+
+- **`global_wrapper()` is R-only.** It evaluates a code block in R's global
+  environment so top-level objects are reachable from the `server` function — an
+  R Shiny scoping concern. In Shiny for Python a module-level assignment is
+  already captured by the server closure, so no equivalent is needed.
+- **`flatten_profile()` is Python-only.** Shiny for Python's `render.data_frame`
+  rejects the nested dicts `fetch_profiles()` returns, so this helper flattens
+  one profile into scalar fields for a table. R users flatten inline with
+  `data.frame()` / `do.call(rbind, ...)`, so no dedicated helper ships in R.
+
+Beyond the public surface, a few behaviours differ by language idiom or as a
+deliberate hardening — same capability, adapted shape:
+
+- **Sandbox toggle mechanism.** R uses the `csiapps.sandbox` **option**
+  (`options(csiapps.sandbox = FALSE)`); Python has no options system, so it uses
+  the `set_sandbox_mode()` function. Both also respect `CSIAPPS_ENV=production`.
+- **`fetch_org_options()` return shape.** R returns `label`/`value` pairs for
+  `selectInput()`; Python returns a `{value: label}` dict for
+  `ui.input_select(choices = )`. Same data, framework-native shape.
+- **`fetch_profile()` argument order.** R is `fetch_profile(token, profile_id)`;
+  Python puts the required argument first: `fetch_profile(profile_id, token)`.
+  Equivalent when called by keyword.
+- **Schema validator engine.** Sandbox ingestion validates with Ajv (via
+  `jsonvalidate`) in R and `jsonschema` (Draft 7) in Python. Error wording and
+  some `format`-keyword edge cases differ.
+- **`fetch_profiles()` pagination guard.** The Python port adds a `max_pages`
+  bound with cycle detection and a truncation warning; the R version paginates
+  until the API stops returning a `next` link. Python is a hardened superset.
+
+## Function reference
+
+- **R:** [R reference](https://csiontario.github.io/csiapps/reference/) (pkgdown)
+- **Python:** [Python reference](api.md) (on this site)