Compare commits
15
Commits
f6752313be
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
 John Lancaster
|
d13ecd6718 | ||
|
John Lancaster
|
5cefca852d | ||
|
John Lancaster
|
78a489c690 | ||
|
John Lancaster
|
9312784c2f | ||
|
John Lancaster
|
09d2a4bcaf | ||
|
John Lancaster
|
86c7d54244 | ||
|
John Lancaster
|
f75b24705e | ||
|
John Lancaster
|
b87b1df642 | ||
|
John Lancaster
|
bf11b7865d | ||
|
John Lancaster
|
be579c347e | ||
|
John Lancaster
|
9eb4ccbc6e | ||
|
John Lancaster
|
bbaa84720c | ||
|
John Lancaster
|
b2ac4102f7 | ||
|
John Lancaster
|
fd5ce6f63b | ||
|
John Lancaster
|
783ecf421e |
@@ -18,8 +18,9 @@ from .mcp import create_mcp
|
||||
def create_app(settings: Settings | None = None) -> FastAPI:
|
||||
runtime_settings = settings if settings is not None else get_settings()
|
||||
docs_route = runtime_settings.mounts.docs.rstrip("/") or "/docs"
|
||||
mcp_route = runtime_settings.mounts.mcp.rstrip("/") or "/mcp"
|
||||
mcp_app = create_mcp().http_app(
|
||||
path="/",
|
||||
path=mcp_route,
|
||||
json_response=True,
|
||||
stateless_http=True,
|
||||
transport="http",
|
||||
@@ -46,7 +47,7 @@ def create_app(settings: Settings | None = None) -> FastAPI:
|
||||
include_in_schema=False,
|
||||
)
|
||||
|
||||
app.mount(runtime_settings.mounts.mcp, mcp_app, name="mcp")
|
||||
app.router.routes.extend(mcp_app.routes)
|
||||
return app
|
||||
|
||||
|
||||
|
||||
@@ -4,102 +4,40 @@ icon: lucide/library
|
||||
|
||||
# Architecture
|
||||
|
||||
## Overview
|
||||
Personal MCP is a small publishing service. Markdown is written once and made available in two ways:
|
||||
|
||||
The application combines a FastMCP server with a pre-built Zensical documentation site. Markdown under `src/personal_mcp/docs/` is the single authored content tree, while native FastMCP providers own skill and prompt discovery.
|
||||
1. as an MCP server for AI clients
|
||||
2. as a documentation website for people
|
||||
|
||||
The runtime has four content paths:
|
||||
|
||||
1. `SkillsDirectoryProvider` publishes native `skill://` resources from packaged skill directories.
|
||||
2. A custom prompt provider loads declarative prompt definitions from packaged Markdown.
|
||||
3. The general docs registry publishes non-skill Markdown through `resource://docs/{path*}`.
|
||||
4. FastAPI serves the pre-built `site/` directory.
|
||||
|
||||
There is no custom skill catalog, prompt catalog, or per-prompt Python module.
|
||||
|
||||
## Source Ownership
|
||||
|
||||
### Skills
|
||||
|
||||
Each skill owns one directory:
|
||||
|
||||
1. `src/personal_mcp/docs/skills/<skill-id>/SKILL.md`
|
||||
2. `src/personal_mcp/docs/skills/<skill-id>/<supporting-path>`
|
||||
|
||||
`SkillsDirectoryProvider` publishes:
|
||||
|
||||
1. `skill://<name>/SKILL.md`
|
||||
2. `skill://<name>/_manifest`
|
||||
3. `skill://<name>/{path*}`
|
||||
|
||||
The provider parses standard skill frontmatter and generates the manifest. The general docs registry excludes `skills/**`, so only the native provider owns this namespace.
|
||||
|
||||
### Prompts
|
||||
|
||||
Each prompt has one source: `src/personal_mcp/docs/prompts/<prompt-id>/PROMPT.md`. Its nested `prompt` frontmatter owns runtime metadata and argument declarations, while its body owns canonical prose.
|
||||
|
||||
The custom provider reads packaged Markdown with `importlib.resources`, validates metadata and exact placeholder-to-argument equality, and creates native FastMCP prompt objects. It rescans on each list and get request, so an editable deployment observes file additions, edits, and deletions without a restart.
|
||||
|
||||
FastMCP exposes prompts through native `prompts/list` and `prompts/get` operations.
|
||||
|
||||
### General Docs
|
||||
|
||||
The docs registry indexes packaged Markdown for `resource://docs/{path*}`. It rejects `skills/**` because skills are provider-owned. Prompt Markdown can remain visible as general documentation, but prompt invocation is owned by the native prompt provider.
|
||||
|
||||
## Runtime Composition
|
||||
## How It Fits Together
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Packaged Skill Directories] --> B[SkillsDirectoryProvider]
|
||||
C[Packaged Prompt Markdown] --> D[Markdown Prompt Provider]
|
||||
F[General Markdown] --> G[Docs Registry]
|
||||
B --> H[FastMCP Server]
|
||||
D --> H
|
||||
G --> H
|
||||
H --> K[MCP Transport]
|
||||
L[Zensical Site Output] --> M[FastAPI Static Mount]
|
||||
K --> M
|
||||
flowchart LR
|
||||
A[Markdown in src/personal_mcp/docs] --> B[MCP resources and prompts]
|
||||
A --> C[Documentation website]
|
||||
B --> D[AI clients]
|
||||
C --> E[Human readers]
|
||||
```
|
||||
|
||||
Server construction is lazy with respect to package import. Each application process creates its providers and docs snapshot when the server factory runs. Skills use startup discovery, while prompts are reloaded when a client lists or gets prompts.
|
||||
The running application has two routes:
|
||||
|
||||
## Packaging
|
||||
- `/mcp` is the MCP endpoint.
|
||||
- `/docs/` is the pre-built documentation site.
|
||||
|
||||
The regular directory `src/personal_mcp/docs/` is the only authored Markdown source. The `uv_build` backend includes it as package data beneath `personal_mcp/docs/` in built distributions.
|
||||
The root URL redirects to the website.
|
||||
|
||||
Runtime reads are package-relative:
|
||||
## Content Types
|
||||
|
||||
1. Prompt content and general docs use `importlib.resources` and `Traversable` APIs.
|
||||
2. `SkillsDirectoryProvider` receives the packaged `personal_mcp/docs/skills` filesystem path.
|
||||
3. No runtime content lookup depends on the current working directory.
|
||||
The server publishes three kinds of Markdown content:
|
||||
|
||||
## Public Contracts
|
||||
- **Skills** are reusable guidance that clients read as `skill://` resources.
|
||||
- **Prompts** are parameterized workflows that clients invoke as MCP prompts.
|
||||
- **Documentation** is available to clients through `resource://docs/...` and to people on the website.
|
||||
|
||||
The machine-facing surfaces are:
|
||||
FastMCP provides the MCP behavior. FastAPI hosts that server beside the static site, and Zensical builds the site from the same Markdown files.
|
||||
|
||||
1. Native skill resources under `skill://<name>/...`.
|
||||
2. Native MCP prompt list and get operations.
|
||||
3. `resource://docs/{path*}` for general Markdown.
|
||||
## Source Of Truth
|
||||
|
||||
Canonical contracts are documented in:
|
||||
All authored content lives under `src/personal_mcp/docs/`. The generated `src/personal_mcp/site/` directory is build output and should not be edited by hand.
|
||||
|
||||
1. [Prompt Contract](./contracts/prompt.md)
|
||||
2. [Skill Contract](./contracts/skill_contract.md)
|
||||
3. [Frontmatter Contract](./contracts/frontmatter.md)
|
||||
4. [URI Contract](./contracts/uris.md)
|
||||
|
||||
Only these canonical provider and protocol surfaces are registered.
|
||||
|
||||
## Static Documentation
|
||||
|
||||
Zensical builds `src/personal_mcp/docs/` into `src/personal_mcp/site/` before deployment. FastAPI mounts that immutable output in the same process that hosts FastMCP. Generated site files are deployment assets and are never an authored source.
|
||||
|
||||
## Validation
|
||||
|
||||
Changes are accepted only after:
|
||||
|
||||
1. focused provider and protocol tests
|
||||
2. Ruff and ty checks
|
||||
3. a Zensical build
|
||||
4. the full pytest suite
|
||||
5. an installed-wheel smoke test when packaging or provider paths change
|
||||
For exact file formats and URI rules, see the [content contracts](./contracts/index.md). For everyday changes, start with the [Authoring Guide](./authoring.md).
|
||||
|
||||
@@ -4,112 +4,60 @@ icon: lucide/pencil
|
||||
|
||||
# Authoring Guide
|
||||
|
||||
This page defines the practical workflow for maintaining skills, prompts, and project documentation in the package-native `src/personal_mcp/docs` source tree.
|
||||
|
||||
Primary references:
|
||||
|
||||
1. [Skill Contract](./contracts/skill_contract.md)
|
||||
2. [Prompt Contract](./contracts/prompt.md)
|
||||
3. [Frontmatter Contract](./contracts/frontmatter.md)
|
||||
4. [URI Contract](./contracts/uris.md)
|
||||
5. [Zensical documentation skill](./skills/zensical-docs/SKILL.md)
|
||||
All authored content lives under `src/personal_mcp/docs/`. The same files feed the MCP server and the documentation website.
|
||||
|
||||
## Source Tree Ownership
|
||||
|
||||
Edit content only under `src/personal_mcp/docs`. This directory is the canonical authored source for both MCP content and the documentation site.
|
||||
|
||||
The `uv_build` backend packages this tree under `personal_mcp/docs/`. The installed package therefore gives runtime providers package-relative content, while Zensical builds the human site directly from `src/personal_mcp/docs` as configured by `docs_dir` in the repository's `zensical.toml`.
|
||||
|
||||
Generated `src/personal_mcp/site/` content is a build artifact and must not be edited by hand.
|
||||
|
||||
## Content Layout
|
||||
|
||||
```text
|
||||
src/personal_mcp/docs/
|
||||
*.md
|
||||
contracts/
|
||||
*.md # General documentation
|
||||
prompts/<prompt-id>/
|
||||
PROMPT.md
|
||||
references/
|
||||
PROMPT.md # One MCP prompt
|
||||
skills/<skill-name>/
|
||||
SKILL.md
|
||||
references/
|
||||
SKILL.md # Main skill guidance
|
||||
references/ # Optional supporting material
|
||||
```
|
||||
|
||||
Keep skill and prompt files inside their owning directories. Relative links may cross sections, but content ownership should remain clear.
|
||||
Do not edit `src/personal_mcp/site/` by hand. It is generated by Zensical.
|
||||
|
||||
## Documentation Pages
|
||||
|
||||
Add general documentation as Markdown under `src/personal_mcp/docs/`. Use relative links between pages. Top-level pages need an `icon` in their frontmatter, and navigation changes belong in `zensical.toml`.
|
||||
|
||||
## Skill Authoring
|
||||
|
||||
A skill is discovered when a direct child of `src/personal_mcp/docs/skills/` contains `SKILL.md`.
|
||||
|
||||
Required frontmatter:
|
||||
Skills follow the [Agent Skills specification](https://agentskills.io/specification). Each skill is a directory containing a required `SKILL.md` file with YAML frontmatter and Markdown instructions:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <skill-name>
|
||||
description: <what the skill does and when to use it>
|
||||
description: <what this skill covers and when to use it>
|
||||
---
|
||||
```
|
||||
|
||||
Rules:
|
||||
The specification requires:
|
||||
|
||||
1. Use lowercase kebab-case for the directory and `name`.
|
||||
2. Keep `name` exactly equal to the directory name.
|
||||
3. Write a specific description because clients use it for discovery.
|
||||
4. Do not add `x-personal-mcp`, versions, tags, capabilities, or reference mappings.
|
||||
5. Put supporting material anywhere beneath the skill directory, normally under `references/`.
|
||||
6. Link supporting files from `SKILL.md` so humans and agents understand when to load them.
|
||||
1. `name` must match the directory name, contain 1-64 lowercase letters, numbers, or hyphens, and have no leading, trailing, or consecutive hyphens.
|
||||
2. `description` must contain 1-1024 characters and explain both what the skill does and when an agent should use it.
|
||||
3. The body of `SKILL.md` must contain the instructions an agent needs after selecting the skill.
|
||||
|
||||
FastMCP recursively scans every skill file and generates `skill://<name>/_manifest`. Supporting-resource identity is the real relative path, not a synthetic reference id.
|
||||
This repository adds two narrower conventions: names start with a letter, and frontmatter contains only the required `name` and `description`. The specification also defines optional `license`, `compatibility`, `metadata`, and experimental `allowed-tools` fields, but they are not part of this repository's current [Skill Contract](./contracts/skill_contract.md).
|
||||
|
||||
Recommended sequence:
|
||||
Write skills for progressive disclosure. Keep discovery information in the frontmatter, the main workflow in `SKILL.md`, and detailed material in focused files under `references/`. Link to supporting files with paths relative to the skill root, and avoid chains of references that require an agent to open several files before finding the useful content.
|
||||
|
||||
1. Draft or revise `SKILL.md` routing guidance.
|
||||
2. Add focused supporting files.
|
||||
3. Verify relative links.
|
||||
4. Run the provider tests and docs build.
|
||||
5. Restart running servers because production uses `reload=False`.
|
||||
The Agent Skills specification also permits `scripts/`, `assets/`, and other supporting directories. This project is primarily a guidance library, so prefer `references/` unless the skill genuinely needs executable or static resources.
|
||||
|
||||
[FastMCP's Skills Provider](https://gofastmcp.com/servers/providers/skills) publishes each compliant directory as MCP resources, including the main file, a generated manifest, and any supporting files. The specification's [`skills-ref` validator](https://github.com/agentskills/agentskills/tree/main/skills-ref) can validate an individual skill before the repository-wide checks run.
|
||||
|
||||
## Prompt Authoring
|
||||
|
||||
A prompt is one self-describing `src/personal_mcp/docs/prompts/<prompt-id>/PROMPT.md` file:
|
||||
A prompt is one `PROMPT.md` file under `src/personal_mcp/docs/prompts/<prompt-id>/`. Its `prompt` frontmatter describes the workflow and arguments; its Markdown body contains the instructions.
|
||||
|
||||
1. Create a lowercase kebab-case directory beneath `src/personal_mcp/docs/prompts/`.
|
||||
2. Add a nested `prompt` frontmatter mapping with version, description, tags, and ordered arguments.
|
||||
3. Give every argument a description and explicit required flag.
|
||||
4. Add `choices` only when a string argument accepts a fixed set of values.
|
||||
5. Use each argument exactly once or more as a `{{argument_name}}` placeholder in the body.
|
||||
6. Do not add a Python component, name field, metadata sidecar, or central catalog entry.
|
||||
Use each declared argument as a `{{placeholder}}` in the body. The server validates prompt metadata and placeholders when the prompt is discovered.
|
||||
|
||||
The custom provider rescans prompt documents during every native list and get request. Changes in an editable checkout are therefore visible on the next request without a process restart. Invalid metadata or placeholder drift fails that request with a configuration error.
|
||||
The [Prompt Contract](./contracts/prompt.md) and [Frontmatter Contract](./contracts/frontmatter.md) contain the exact schema.
|
||||
|
||||
## Frontmatter Safety
|
||||
|
||||
1. Quote scalar values containing `:`.
|
||||
2. Quote values with reserved YAML characters such as `#`, `{}`, `[]`, or leading `*`.
|
||||
3. Use block scalars for punctuation-heavy multiline text.
|
||||
4. Keep fields within the applicable skill or documentation contract.
|
||||
|
||||
## Writing Quality
|
||||
|
||||
1. Prefer focused sections and descriptive headings.
|
||||
2. Link feature-level claims to authoritative sources.
|
||||
3. Use relative links for internal pages.
|
||||
4. Keep code examples minimal and actionable.
|
||||
5. Avoid bare URLs in prose.
|
||||
6. Load only supporting material relevant to the immediate task.
|
||||
|
||||
## Copilot Routing
|
||||
|
||||
Active instructions should point directly to native main resources:
|
||||
|
||||
1. `skill://zensical-docs/SKILL.md`
|
||||
2. `skill://pytesting/SKILL.md`
|
||||
3. `skill://vscode-configuration/SKILL.md`
|
||||
|
||||
When deeper guidance is needed, read the selected skill's `_manifest` and fetch supporting files by their listed path.
|
||||
|
||||
## Validation Checklist
|
||||
## Validate Changes
|
||||
|
||||
```bash
|
||||
uv run zensical build
|
||||
@@ -118,13 +66,6 @@ uv run ty check
|
||||
uv run pytest
|
||||
```
|
||||
|
||||
For packaging changes, also build and inspect an installed wheel so provider path resolution is verified outside the editable checkout.
|
||||
Restart a running server after changing content so every surface reads the latest package data.
|
||||
|
||||
## Navigation
|
||||
|
||||
When adding or moving pages:
|
||||
|
||||
1. update `zensical.toml`
|
||||
2. keep top-level page icons in frontmatter
|
||||
3. rebuild the site
|
||||
4. verify internal links and navigation labels
|
||||
For detailed rules, see the [content contracts](./contracts/index.md). For writing and site features, use the [Zensical documentation skill](./skills/zensical-docs/SKILL.md).
|
||||
|
||||
@@ -2,129 +2,56 @@
|
||||
icon: lucide/bot
|
||||
---
|
||||
|
||||
# Copilot MCP Mechanics
|
||||
# Using With GitHub Copilot
|
||||
|
||||
## Purpose
|
||||
Once Personal MCP is configured as a VS Code MCP server, Copilot can use its resources, prompts, and read-only tools.
|
||||
|
||||
This page explains how GitHub Copilot in VS Code consumes native skill resources and prompts from `personal-mcp`.
|
||||
For general connection details, see [Using Personal MCP](./usage.md). For VS Code setup options, see [Add and manage MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
|
||||
|
||||
## Capability Lanes
|
||||
## Skills And Documentation
|
||||
|
||||
Copilot interacts with MCP servers through independently exposed lanes:
|
||||
Use **MCP: Browse Resources** to inspect the server's resources. Skills appear as `skill://<name>/SKILL.md`; general pages appear under `resource://docs/...`.
|
||||
|
||||
1. tools invoked during execution
|
||||
2. resources attached as read-only context
|
||||
3. server-provided prompts
|
||||
For a task that needs guidance:
|
||||
|
||||
This server publishes skills as native `skill://` resources, general docs as `resource://docs/{path*}` resources, and workflows as native MCP prompt objects. It intentionally publishes no compatibility tools that mirror resources or prompts.
|
||||
1. choose the skill whose description best matches the task
|
||||
2. read its main `SKILL.md`
|
||||
3. read `_manifest` only when supporting material is needed
|
||||
4. attach or read only the relevant supporting files
|
||||
|
||||
## VS Code Feature Coverage
|
||||
When the current chat surface supports MCP resource attachments, the same resources are available from **Add Context**.
|
||||
|
||||
The server uses every FastMCP feature that applies to its read-only guidance workload:
|
||||
## Prompts
|
||||
|
||||
| Feature | Usage |
|
||||
| --- | --- |
|
||||
| Server identity | The initialize response includes a stable name, usage instructions, and a self-contained icon for VS Code's MCP server UI. |
|
||||
| Tools | No tools are published for this documentation-only server surface. Resource and prompt operations stay on native MCP capabilities. |
|
||||
| Resources | Documentation and skills use native resources and wildcard resource templates with explicit Markdown MIME types. |
|
||||
| Prompts | Declarative workflows use native prompt objects with descriptions, display titles, typed arguments, and slash-command access. |
|
||||
| Argument completion | Prompt arguments with authored `choices` are returned through `completion/complete` as the user types. |
|
||||
Personal MCP prompts appear as `/<server>.<prompt>` chat commands. Select a command and fill in its arguments to start the workflow. Arguments with a fixed list of choices offer completion as you type.
|
||||
|
||||
[FastMCP server identity](https://gofastmcp.com/servers/server), [component icons](https://gofastmcp.com/servers/icons), [tool metadata](https://gofastmcp.com/servers/tools), and [argument completion](https://gofastmcp.com/servers/completions) define the implementation details. [VS Code's MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers) describes how tools, resources, prompts, and MCP Apps appear in the client.
|
||||
## Automatic Use
|
||||
|
||||
The following capabilities are conditional rather than useful by default:
|
||||
Copilot can use four fallback tools when the chat surface does not expose resources or prompts directly:
|
||||
|
||||
1. MCP Apps require an interactive tool result such as a form or visualization; this server returns guidance and structured resource data only.
|
||||
2. Sampling is appropriate only when server-side work must ask VS Code to run an LLM. The current server retrieves authored content and does not generate it.
|
||||
3. Elicitation is appropriate only when a running operation needs additional user input. Prompt arguments already collect all required input before execution.
|
||||
4. Progress, client logging, and background tasks require long-running operations. Current reads and prompt rendering are bounded local operations.
|
||||
5. Client roots matter only when server behavior depends on client filesystem roots. This server reads packaged content and never traverses a client workspace.
|
||||
6. `website_url` requires a canonical public deployment URL. None is configured, so the server does not advertise a guessed address.
|
||||
- `list_resources` and `read_resource`
|
||||
- `list_prompts` and `get_prompt`
|
||||
|
||||
Add one of these capabilities when a concrete workflow needs it, then cover its negotiated capability and protocol response in the HTTP MCP smoke tests. See the [FastMCP Apps overview](https://gofastmcp.com/apps/overview), [sampling](https://gofastmcp.com/servers/sampling), [elicitation](https://gofastmcp.com/servers/elicitation), [progress reporting](https://gofastmcp.com/servers/progress), and [MCP context](https://gofastmcp.com/servers/context) for the activation criteria.
|
||||
|
||||
## Native Skill Resources
|
||||
|
||||
For every skill, Copilot can discover:
|
||||
|
||||
1. `skill://<name>/SKILL.md`
|
||||
2. `skill://<name>/_manifest`
|
||||
3. `skill://<name>/{path*}` supporting-file template
|
||||
|
||||
The main resource description comes from `SKILL.md`. The manifest discloses supporting paths, sizes, and SHA256 hashes. Native resources remain the only skill content and discovery contract; the tools search or delegate to that same resource surface rather than maintaining a parallel catalog.
|
||||
|
||||
## Resource Picker Availability
|
||||
|
||||
`MCP Resources...` in Add Context requires both:
|
||||
|
||||
1. a connected server advertising resource capability
|
||||
2. a chat surface that exposes MCP resource attachment
|
||||
|
||||
A successful `resources/list` response does not guarantee the picker appears in every session type. Use `MCP: Browse Resources` to distinguish server availability from chat UI availability.
|
||||
|
||||
## Recommended Workflow
|
||||
|
||||
For autonomous agents:
|
||||
|
||||
1. browse native resources and compare skill descriptions
|
||||
2. read one relevant `skill://<name>/SKILL.md`
|
||||
3. read `_manifest` only if supporting detail may be needed
|
||||
4. read only selected supporting files
|
||||
|
||||
For manual context attachment, browse the server's resources and attach the same bounded set of files.
|
||||
|
||||
## Prompt Examples
|
||||
|
||||
Resource attachment:
|
||||
These tools access the same content as the native features. A repository instruction can guide Copilot toward the intended order:
|
||||
|
||||
```text
|
||||
Use the attached personal-mcp skill as guidance, then reconcile it with the repository before proposing changes.
|
||||
```
|
||||
|
||||
Direct loading:
|
||||
|
||||
```text
|
||||
Read skill://async-fastapi-sqlmodel/SKILL.md and apply only the sections relevant to this repository.
|
||||
```
|
||||
|
||||
Supporting material:
|
||||
|
||||
```text
|
||||
Read skill://pytesting/_manifest, select the one reference relevant to async test lifecycle, and use that file with the main skill instructions.
|
||||
```
|
||||
|
||||
## Repository Instruction Pattern
|
||||
|
||||
A repo-level instruction should name the native retrieval order and context budget:
|
||||
|
||||
```md
|
||||
When a task matches a personal-mcp skill:
|
||||
|
||||
1. Prefer an already attached native skill resource.
|
||||
2. Otherwise browse MCP resources and select one `skill://<name>/SKILL.md` by description.
|
||||
3. Read the selected skill and read `_manifest` only when supporting material is needed.
|
||||
4. Load at most two candidate main files and only the relevant supporting paths.
|
||||
5. Reconcile guidance with the current repository before editing.
|
||||
1. Prefer an attached skill resource, or browse resources and choose one by description.
|
||||
2. Read its main file and load supporting material only when needed.
|
||||
3. Reconcile the guidance with the current repository before editing.
|
||||
```
|
||||
|
||||
Instructions steer behavior but do not force VS Code to attach resources automatically.
|
||||
|
||||
## Prompt Objects
|
||||
|
||||
Prompts remain separate from skills. When the client supports MCP prompt APIs, use prompt listing and `get_prompt` for parameterized workflows. Each authored `PROMPT.md` is the complete source of truth for its metadata, arguments, and prose; changes are loaded on the next prompt request.
|
||||
Instructions guide resource use but do not force VS Code to attach resources automatically.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
1. Use `MCP: List Servers` to confirm the server is enabled.
|
||||
2. Use `MCP: Browse Resources` to confirm native skill resources exist.
|
||||
3. Confirm `Add Context > MCP Resources` lists server resources in the active chat surface.
|
||||
4. Restart the MCP server after changing skill files because production uses `reload=False`.
|
||||
5. Reload the VS Code window if the server is healthy but the resource or tool picker remains stale.
|
||||
2. Use `MCP: Browse Resources` to confirm resources are available.
|
||||
3. Restart the MCP server after changing its content.
|
||||
4. Reload the VS Code window if the server is healthy but the resource or tool list remains stale.
|
||||
|
||||
## Further Reading
|
||||
|
||||
1. [FastMCP Skills Provider](https://gofastmcp.com/servers/providers/skills)
|
||||
2. [Add and manage MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
|
||||
3. [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
|
||||
4. [Manage context for AI](https://code.visualstudio.com/docs/chat/copilot-chat-context)
|
||||
5. [Skill Usage Mechanics](./usage.md)
|
||||
1. [VS Code MCP configuration](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
|
||||
2. [Managing context in VS Code](https://code.visualstudio.com/docs/chat/copilot-chat-context)
|
||||
3. [Using Personal MCP](./usage.md)
|
||||
|
||||
@@ -4,45 +4,46 @@ icon: lucide/rocket
|
||||
|
||||
# Personal MCP
|
||||
|
||||
This project is a document library of software patterns, best practices, and structured references to external documentation. The same markdown files are published through two equivalent surfaces, so human-readable docs and MCP resources stay aligned.
|
||||
Personal MCP is a library of software development guidance for people and AI assistants. Content is written once in Markdown and published as both a documentation website and an MCP server.
|
||||
|
||||
## MCP Server
|
||||
## What It Provides
|
||||
|
||||
An [MCP server](https://modelcontextprotocol.io/docs/getting-started/intro) at `/mcp` provides context for AI systems. The markdown files are exposed as [resources](https://modelcontextprotocol.io/docs/learn/server-concepts#resources) and are structured to be easily consumed by [MCP clients](https://modelcontextprotocol.io/docs/learn/client-concepts), such as VS Code.
|
||||
- **Skills** provide focused guidance for development tasks.
|
||||
- **Prompts** provide reusable workflows with named inputs.
|
||||
- **Documentation** makes the same material easy to browse and maintain.
|
||||
|
||||
## Docs
|
||||
The HTTP service exposes the [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) endpoint at `/mcp` and the website at `/docs/`.
|
||||
|
||||
A website at `/docs` for humans to read and review.
|
||||
## Quick Start
|
||||
|
||||
## Quick start
|
||||
|
||||
Install dependencies first:
|
||||
Install dependencies, build the website, and start the server:
|
||||
|
||||
```bash
|
||||
uv sync
|
||||
uv run zensical build
|
||||
uv run personal-mcp --host 127.0.0.1 --port 8765
|
||||
```
|
||||
|
||||
Run the app locally with the static docs rebuilt first, using [Uvicorn factory mode](https://www.uvicorn.org/settings/#application):
|
||||
Then open `http://127.0.0.1:8765/docs/` or connect an MCP client to `http://127.0.0.1:8765/mcp`.
|
||||
|
||||
The MCP server can also run over standard input and output:
|
||||
|
||||
```bash
|
||||
uv run zensical build && uv run uvicorn personal_mcp.web.app:create_app --factory --host 127.0.0.1 --port 8765
|
||||
uv run mcp-stdio
|
||||
```
|
||||
|
||||
Build and run the Docker image with the same exposed port:
|
||||
For Docker:
|
||||
|
||||
```bash
|
||||
docker build -t personal-mcp . && docker run --rm -p 8765:8765 personal-mcp
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
When the server is running, the health check is available at `/healthz` and the generated docs are available at `/docs/`.
|
||||
## Read Next
|
||||
|
||||
## Architecture
|
||||
|
||||
- [Resource-First Pattern Module Architecture](./architecture.md)
|
||||
- [Contracts](./contracts/index.md)
|
||||
- [Content Contract](./contracts/index.md#content-contract)
|
||||
- [Frontmatter Contract](./contracts/frontmatter.md)
|
||||
- [URI Contract](./contracts/uris.md)
|
||||
- [Static Docs Hosting Pattern](./mcp_layout.md)
|
||||
- [Skill Usage Mechanics](./usage.md)
|
||||
- [Copilot MCP Mechanics](./copilot.md)
|
||||
- [Using Personal MCP](./usage.md)
|
||||
- [Authoring Guide](./authoring.md)
|
||||
- [Architecture](./architecture.md)
|
||||
- [Running the Server](./mcp_layout.md)
|
||||
- [Testing](./testing.md)
|
||||
- [Security](./securing.md)
|
||||
- [Content Contracts](./contracts/index.md)
|
||||
|
||||
@@ -2,92 +2,43 @@
|
||||
icon: lucide/server
|
||||
---
|
||||
|
||||
# Runtime And Static Docs Layout
|
||||
# Running The Server
|
||||
|
||||
## Purpose
|
||||
Personal MCP can run as an HTTP service or as a local stdio process.
|
||||
|
||||
The project serves native MCP content and a pre-built documentation site from one FastAPI process. Markdown is authored once under `src/personal_mcp/docs/`; runtime providers and Zensical consume that same package-owned tree for different purposes.
|
||||
## Local HTTP Server
|
||||
|
||||
## Repository Layout
|
||||
Build the website before starting the application:
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
treeView:
|
||||
rowIndent: 32
|
||||
lineThickness: 2
|
||||
---
|
||||
treeView-beta
|
||||
"project-root"
|
||||
"src/personal_mcp"
|
||||
"docs"
|
||||
"prompts/<prompt-id>/PROMPT.md"
|
||||
"skills/<skill-id>/SKILL.md"
|
||||
"skills/<skill-id>/<supporting-files>"
|
||||
"<general-pages>.md"
|
||||
"site"
|
||||
"static build output"
|
||||
"app.py"
|
||||
"mcp.py"
|
||||
"skills.py"
|
||||
"prompts/"
|
||||
"registry/"
|
||||
```bash
|
||||
uv sync
|
||||
uv run zensical build
|
||||
uv run personal-mcp --host 127.0.0.1 --port 8765
|
||||
```
|
||||
|
||||
Ownership rules:
|
||||
The server then provides:
|
||||
|
||||
1. `src/personal_mcp/docs/skills/` is owned exclusively by `SkillsDirectoryProvider` at runtime.
|
||||
2. Each file under `src/personal_mcp/docs/prompts/` owns its prompt metadata, argument schema, and prose.
|
||||
3. The docs registry owns only general Markdown resources and explicitly excludes skills.
|
||||
4. `src/personal_mcp/site/` is generated output.
|
||||
5. The deleted custom `catalog/` package is not part of the runtime.
|
||||
- `http://127.0.0.1:8765/docs/` for the website
|
||||
- `http://127.0.0.1:8765/mcp` for MCP clients
|
||||
|
||||
## Runtime Composition
|
||||
The host, port, log level, debug mode, and reload behavior can be set with command-line options or `PERSONAL_MCP_` environment variables.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Packaged Skills] --> B[SkillsDirectoryProvider]
|
||||
C[Packaged Prompt Markdown] --> D[Markdown Prompt Provider]
|
||||
E[Packaged Markdown] --> F[Docs Registry]
|
||||
B --> G[FastMCP]
|
||||
D --> G
|
||||
F --> G
|
||||
G --> H[MCP Transport]
|
||||
H --> K[FastAPI Application]
|
||||
L[Pre-built site] --> M[Static /docs Mount]
|
||||
K --> M
|
||||
## Local Stdio Server
|
||||
|
||||
For clients that manage the server process themselves:
|
||||
|
||||
```bash
|
||||
uv run mcp-stdio
|
||||
```
|
||||
|
||||
Runtime guarantees:
|
||||
This mode provides MCP only; it does not host the website.
|
||||
|
||||
1. Providers are installed before serving requests.
|
||||
2. Prompt discovery rescans authored files on each list and get request.
|
||||
3. Duplicate components fail according to FastMCP's configured duplicate policy.
|
||||
4. Skills and prompts use native FastMCP component surfaces.
|
||||
5. General docs path parsing rejects traversal, backslashes, non-Markdown paths, and the skill namespace.
|
||||
## Docker
|
||||
|
||||
## Build And Publish Flow
|
||||
The included Compose configuration builds the website into the image and publishes the service on port `8765`:
|
||||
|
||||
1. Author prompt definitions and prose under `src/personal_mcp/docs/prompts/`.
|
||||
2. Run `uv run zensical build` to produce `src/personal_mcp/site/`.
|
||||
3. Build the wheel, which packages the authored docs under `personal_mcp/docs/`.
|
||||
4. Start the app and serve MCP plus the static site.
|
||||
```bash
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
No runtime Markdown-to-HTML conversion occurs.
|
||||
|
||||
## Machine-Facing Mapping
|
||||
|
||||
1. `src/personal_mcp/docs/skills/<skill-id>/SKILL.md` maps to `skill://<skill-id>/SKILL.md`.
|
||||
2. Skill supporting files map to `skill://<skill-id>/<path>`.
|
||||
3. Declarative prompt documents map to native MCP prompt names.
|
||||
4. General `src/personal_mcp/docs/<path>.md` maps to `resource://docs/{path*}`.
|
||||
|
||||
The server publishes no tool projections of resources or prompts.
|
||||
|
||||
## Public Surface Policy
|
||||
|
||||
Canonical provider and protocol surfaces are the only public interfaces.
|
||||
|
||||
## Static Mount Expectations
|
||||
|
||||
The FastAPI app mounts the Zensical output, serves index and asset files, and returns a clear unavailable response when the static output is absent. The site directory is immutable for a given build and remains separate from packaged authored Markdown.
|
||||
For a remote deployment, place the service behind a reverse proxy and review the [security guidance](./securing.md).
|
||||
|
||||
@@ -2,138 +2,41 @@
|
||||
icon: lucide/shield-check
|
||||
---
|
||||
|
||||
# Securing Remote Access
|
||||
# Security
|
||||
|
||||
## Context
|
||||
## Public By Design
|
||||
|
||||
This project exposes two related surfaces from the same runtime:
|
||||
The application does not implement authentication. Its current purpose is to publish read-only guidance, so everything exposed through the server must be safe to make public.
|
||||
|
||||
1. a static documentation site under `/docs`
|
||||
2. a Streamable HTTP MCP endpoint under `/mcp`
|
||||
This includes:
|
||||
|
||||
The same Markdown content backs both surfaces. For the current project shape, the MCP server is resource-first and primarily exposes public skill and documentation text. It is not intended to expose secrets, private data, shell access, filesystem access, or tools with side effects.
|
||||
- the website under `/docs/`
|
||||
- resources and prompts under `/mcp`
|
||||
- the four read-only fallback tools
|
||||
|
||||
The expected deployment path is:
|
||||
Do not add secrets, private notes, credentials, or sensitive environment details to the authored content.
|
||||
|
||||
## Remote Deployment
|
||||
|
||||
Place the service behind a reverse proxy or tunnel rather than exposing the container directly. The edge can provide TLS, rate limiting, access logs, and optional authentication without adding those concerns to this small application.
|
||||
|
||||
A simple deployment is:
|
||||
|
||||
```text
|
||||
Public internet
|
||||
-> Cloudflare Tunnel
|
||||
-> Caddy
|
||||
-> personal-mcp container
|
||||
Internet -> reverse proxy or tunnel -> personal-mcp
|
||||
```
|
||||
|
||||
## Decision
|
||||
The website and MCP endpoint can remain public while they contain only public, read-only content. Use edge authentication if access should be limited.
|
||||
|
||||
For the current use case, heavy application-level authentication is not required.
|
||||
## When Authentication Becomes Required
|
||||
|
||||
The recommended posture is:
|
||||
|
||||
1. Keep the service behind Cloudflare Tunnel and Caddy.
|
||||
2. Do not expose the container port directly to the public internet.
|
||||
3. Treat everything exposed through MCP as publishable public documentation.
|
||||
4. Add stronger authentication only if the MCP surface later includes sensitive content or tools with meaningful side effects.
|
||||
|
||||
This keeps the deployment simple while preserving a clear upgrade path.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
### Leaving `/mcp` Public
|
||||
|
||||
This is acceptable if `/mcp` exposes only the same public Markdown already available through `/docs`.
|
||||
|
||||
Benefits:
|
||||
|
||||
1. lowest operational friction
|
||||
2. fewer compatibility issues with MCP clients
|
||||
3. no need to implement OAuth, mTLS, JWT validation, or custom auth middleware
|
||||
4. consistent with the project assumption that documentation content is public
|
||||
|
||||
Risks:
|
||||
|
||||
1. random scraping, probing, or fuzzing of a machine endpoint
|
||||
2. possible bandwidth or CPU nuisance traffic
|
||||
3. accidental future exposure if new tools or private resources are added
|
||||
4. less control over who can use the MCP endpoint
|
||||
|
||||
### Protecting `/mcp` With Cloudflare Access
|
||||
|
||||
Cloudflare Access can add a lightweight gate using GitHub, Google, one-time PIN, or service tokens.
|
||||
|
||||
Benefits:
|
||||
|
||||
1. reduces random internet traffic
|
||||
2. requires little app code
|
||||
3. works well for a small trusted team
|
||||
4. provides logs and centralized access control
|
||||
|
||||
Costs:
|
||||
|
||||
1. browser-based login may not work with all MCP clients
|
||||
2. non-browser MCP clients may need Cloudflare Access service tokens
|
||||
3. adds operational configuration for a low-sensitivity endpoint
|
||||
|
||||
### Using mTLS
|
||||
|
||||
mTLS is useful when both client and server environments are tightly controlled.
|
||||
|
||||
Benefits:
|
||||
|
||||
1. strong client identity
|
||||
2. good fit for service-to-service or private infrastructure
|
||||
3. can be used between Cloudflare, Caddy, and the backend if desired
|
||||
|
||||
Costs:
|
||||
|
||||
1. harder certificate provisioning and rotation
|
||||
2. weaker compatibility with normal MCP clients
|
||||
3. unnecessary for public documentation-only content
|
||||
|
||||
For this project, mTLS is not the primary recommendation.
|
||||
|
||||
## Practical Recommendation
|
||||
|
||||
Use a simple public-docs posture unless the endpoint changes.
|
||||
|
||||
Recommended current setup:
|
||||
|
||||
```text
|
||||
/docs public
|
||||
/mcp public or lightly protected
|
||||
```
|
||||
|
||||
If `/mcp` remains public, add only basic operational safeguards:
|
||||
|
||||
1. keep Cloudflare Tunnel and Caddy in front
|
||||
2. avoid publishing `8765` directly
|
||||
3. enable Cloudflare or Caddy rate limiting if traffic becomes noisy
|
||||
4. monitor logs for unusual request volume
|
||||
5. document that MCP resources must remain safe to publish
|
||||
|
||||
A slightly stricter setup is also reasonable:
|
||||
|
||||
```text
|
||||
/docs public
|
||||
/mcp Cloudflare Access or service token
|
||||
```
|
||||
|
||||
This is the best option if the team wants to reduce drive-by MCP traffic without adding auth code to the application.
|
||||
|
||||
## Upgrade Trigger
|
||||
|
||||
Add real authentication before introducing any MCP capability that can:
|
||||
Protect `/mcp` before adding any capability that can:
|
||||
|
||||
1. read non-public files
|
||||
2. access private notes or credentials
|
||||
3. call upstream APIs
|
||||
2. access private data or credentials
|
||||
3. call authenticated services
|
||||
4. mutate data
|
||||
5. run commands
|
||||
6. expose environment details
|
||||
7. perform expensive computation
|
||||
6. perform expensive work
|
||||
|
||||
At that point, prefer edge-level authentication first, such as Cloudflare Access, and consider proper OAuth 2.1 resource-server behavior only if broad public MCP client interoperability becomes a goal.
|
||||
|
||||
## Security Invariant
|
||||
|
||||
Everything exposed by the MCP server must be safe to publish publicly.
|
||||
|
||||
If that invariant stops being true, `/mcp` should be protected before the new capability is deployed.
|
||||
At that point, choose authentication based on the clients that need to connect. Edge authentication is the simplest option for a small trusted audience; standards-based MCP authorization is more appropriate when broad client interoperability is required.
|
||||
|
||||
@@ -0,0 +1,239 @@
|
||||
---
|
||||
name: cli-client
|
||||
description: 'Design, implement, review, or refine Python command-line clients for remote APIs. Use for command structure, automation-friendly input and output, configuration, authentication, HTTP transport, pagination, retries, errors and exit codes, state-changing operations, packaging, or CLI testing.'
|
||||
---
|
||||
|
||||
# Python API CLI Clients
|
||||
|
||||
Use this skill as a conceptual reference for command-line applications that operate remote services. Preserve established project conventions, but make the command surface predictable for people, scripts, CI jobs, and shell composition.
|
||||
|
||||
## Design Priorities
|
||||
|
||||
A good API CLI should be:
|
||||
|
||||
- **Task-oriented:** commands reflect user goals rather than HTTP endpoints or internal service classes.
|
||||
- **Predictable:** names, flags, defaults, output, errors, and exit statuses behave consistently.
|
||||
- **Composable:** successful data goes to stdout, diagnostics go to stderr, and machine-readable output is stable.
|
||||
- **Safe:** destructive operations are explicit, retries respect operation semantics, and secrets never enter output or logs.
|
||||
- **Layered:** command parsing, application behavior, API resources, transport, authentication, and persistence have distinct owners.
|
||||
- **Inspectable:** users can discover commands and effective configuration without reading source code.
|
||||
|
||||
Use the [Command Line Interface Guidelines](https://clig.dev/) as the general human-interface baseline. Prefer the target project's established command framework and HTTP library over introducing replacements without a concrete need.
|
||||
|
||||
## Command Model
|
||||
|
||||
Design the command tree around a small, consistent grammar:
|
||||
|
||||
```text
|
||||
mycli <resource> <action> [arguments] [options]
|
||||
mycli projects list --owner alice
|
||||
mycli projects get PROJECT_ID
|
||||
mycli projects create --name NAME
|
||||
mycli projects delete PROJECT_ID
|
||||
```
|
||||
|
||||
- Use nouns for resource groups and familiar verbs for actions.
|
||||
- Keep equivalent operations parallel across resources: `list`, `get`, `create`, `update`, and `delete` should not change meaning by command group.
|
||||
- Prefer explicit positional arguments for primary identities and named options for modifiers.
|
||||
- Reserve global options for behavior that applies consistently across commands, such as profile, endpoint, output format, verbosity, and non-interactive mode.
|
||||
- Give every command useful `--help` output with a one-line purpose, argument meaning, defaults, and behavior-changing caveats.
|
||||
- Avoid mirroring every server endpoint. Combine low-level calls when one user task requires them, and omit endpoints that do not form a coherent CLI operation.
|
||||
|
||||
Do not make users memorize hidden context. When a command depends on an active account, project, region, or profile, make that context discoverable and overridable.
|
||||
|
||||
## Responsibility Boundaries
|
||||
|
||||
Keep the command layer thin and dependencies directional:
|
||||
|
||||
```text
|
||||
entry point and bootstrap
|
||||
└── command groups
|
||||
└── application services
|
||||
└── API client and resources
|
||||
└── authenticated HTTP transport
|
||||
└── HTTP library
|
||||
|
||||
configuration ───────────────┘
|
||||
credentials ──> authentication
|
||||
renderers <──── command results
|
||||
```
|
||||
|
||||
| Layer | Owns | Avoid |
|
||||
| --- | --- | --- |
|
||||
| Entry point | Dependency construction, top-level exception mapping, process exit | Business logic and API calls |
|
||||
| Command | Parsing, prompts, presentation, command-specific orchestration | Raw HTTP details and credential refresh |
|
||||
| Application service | Multi-request use cases and domain decisions | Terminal formatting |
|
||||
| API resource | Endpoint paths, request parameters, and response models | CLI prompts and global process state |
|
||||
| Transport | Base URL, headers, serialization, timeouts, retries, and response decoding | Resource-specific business rules |
|
||||
| Authentication | Credential acquisition, storage, and renewal | API resource behavior |
|
||||
| Renderer | Human and machine-readable output | Network calls and state mutation |
|
||||
|
||||
Keep framework objects at the command boundary. Core operations should accept ordinary typed values and return structured results so they can be tested without invoking a subprocess.
|
||||
|
||||
## Input And Interaction
|
||||
|
||||
- Accept flags for every value that automation may need to provide. Prompts are an interactive convenience, not the only input path.
|
||||
- Prompt only when stdin and stderr are attached to a terminal and the user has not selected non-interactive mode.
|
||||
- In non-interactive mode, fail quickly with a specific missing-input error instead of waiting for input.
|
||||
- Read large request bodies from a file or stdin; avoid forcing structured documents into shell-escaped arguments.
|
||||
- Distinguish an omitted option from an explicit empty value when the API supports partial updates.
|
||||
- Validate syntax locally, but let the service remain authoritative for remote identities, permissions, and business rules.
|
||||
- Support `--` before pass-through values or positional arguments that can begin with a hyphen.
|
||||
|
||||
For destructive or difficult-to-reverse operations, state the target precisely and require confirmation in interactive sessions. Provide an explicit option such as `--yes` for automation; never silently infer consent merely because input is non-interactive.
|
||||
|
||||
## Output Contract
|
||||
|
||||
Treat output as a public interface.
|
||||
|
||||
- Write requested results to stdout and diagnostics, progress, warnings, and errors to stderr.
|
||||
- Make the default human output concise and scannable. Do not print the same result as both prose and a table.
|
||||
- Provide one stable machine-readable format, usually `--output json` or `--json`, for commands whose results are useful in automation.
|
||||
- Serialize machine output from typed result models rather than scraping human-formatted strings.
|
||||
- Keep machine-readable stdout clean: no progress bars, update notices, color codes, or explanatory prefixes.
|
||||
- Disable color and animated progress when the output stream is not a terminal or when the user requests it.
|
||||
- Use a pager only for interactive human output, and provide a consistent way to disable it.
|
||||
- Document whether list commands emit one aggregate value or a stream of records; do not switch shapes based on result count.
|
||||
|
||||
When adding fields, preserve existing machine-readable fields where practical. Treat renaming, removing, or changing the type of a field as a compatibility decision.
|
||||
|
||||
## Configuration Model
|
||||
|
||||
Use one documented precedence order:
|
||||
|
||||
```text
|
||||
command-line option > environment variable > selected profile/config file > built-in default
|
||||
```
|
||||
|
||||
- Resolve configuration once near startup and pass a validated settings object inward.
|
||||
- Keep endpoint, profile, timeout, output mode, and similar behavior visible through a config or diagnostics command.
|
||||
- Show provenance when troubleshooting precedence, but redact secret values.
|
||||
- Store configuration in platform-appropriate user directories rather than the current working directory unless project-local configuration is intentional.
|
||||
- Keep credentials behind a separate storage abstraction. A convenient config file is not automatically an acceptable secret store.
|
||||
- Validate incompatible options together and report the conflict in the user's vocabulary.
|
||||
|
||||
## HTTP And API Behavior
|
||||
|
||||
Centralize remote-call behavior in the transport or API client:
|
||||
|
||||
- Set explicit connect, read, write, and pool timeouts appropriate to the service.
|
||||
- Send a useful user agent containing the CLI name and version.
|
||||
- Map service errors into a small application error taxonomy before they reach commands.
|
||||
- Retry only transient failures, honor `Retry-After`, cap attempts and elapsed time, and add jitter where concurrent clients may synchronize.
|
||||
- Automatically retry state-changing requests only when they are demonstrably replay-safe, such as through an idempotency key accepted by the service.
|
||||
- Preserve server request or correlation IDs in verbose diagnostics without exposing sensitive response data.
|
||||
- Keep pagination in the API layer. Let commands choose whether to fetch one page, stream pages, or collect all results based on output and memory requirements.
|
||||
- Make cancellation responsive between requests and during long-running operations.
|
||||
|
||||
Do not leak raw HTTP-library exceptions as the normal user interface. Preserve the original exception as the cause for debugging while presenting a stable CLI-level error.
|
||||
|
||||
## Authentication
|
||||
|
||||
Choose authentication from the service contract and execution context. Keep credential acquisition and renewal out of command handlers and API resources.
|
||||
|
||||
For OAuth-protected APIs, load [OAuth 2.0 for installed CLI clients](./references/oauth.md). It covers public clients, Authorization Code with PKCE, loopback callbacks, device authorization, Authlib and HTTPX2 boundaries, protected token storage, synchronized refresh, scopes, discovery, and bounded authentication retries.
|
||||
|
||||
For API keys or static tokens:
|
||||
|
||||
- Accept them through an explicit credential provider such as an OS credential store, environment variable, or CI secret integration.
|
||||
- Define precedence when more than one provider is configured.
|
||||
- Never place credentials in command arguments by default because process listings and shell history may expose them.
|
||||
- Redact credentials and credential-like headers from errors, debug logs, traces, and support bundles.
|
||||
|
||||
For unattended workloads, use a service identity and grant intended for machines. Do not reuse a person's interactive credentials as automation identity.
|
||||
|
||||
## Errors And Exit Status
|
||||
|
||||
Keep a small documented taxonomy and map it once at the entry point:
|
||||
|
||||
| Category | User-facing behavior | Exit-status requirement |
|
||||
| --- | --- | --- |
|
||||
| Usage or validation | Explain the invalid input and show the nearest help hint | Stable nonzero status distinct from remote failure |
|
||||
| Authentication | Explain whether login or credential repair is required | Stable nonzero status |
|
||||
| Authorization | Identify the denied operation without claiming credentials are expired | Stable nonzero status |
|
||||
| Not found or conflict | Name the target and preserve actionable server context | Stable nonzero status if scripts branch on it |
|
||||
| Rate limit or transient service failure | Explain retryability and any known retry time | Stable nonzero status |
|
||||
| Unexpected failure | Concise message plus opt-in diagnostic detail | Generic nonzero status |
|
||||
|
||||
- Return zero only when the requested operation completed according to its contract.
|
||||
- Do not require scripts to parse prose to distinguish common failure categories.
|
||||
- Keep normal errors concise. Put tracebacks, request details, and internal context behind an explicit debug or verbose mode.
|
||||
- Handle interruption without a traceback by default and use the platform's conventional interrupted-process status.
|
||||
- Preserve partial-success information for batch operations and define whether partial success is a failing exit status.
|
||||
|
||||
## State-Changing Operations
|
||||
|
||||
- Display or return the identity of the affected resource.
|
||||
- Support a dry-run or plan mode when the service can accurately predict a consequential change.
|
||||
- Use idempotency keys for retried creates or actions when the API supports them.
|
||||
- Do not claim rollback if the remote API cannot provide it.
|
||||
- For batch changes, define ordering, concurrency limits, stop/continue behavior, and partial-failure reporting.
|
||||
- Keep local caches disposable unless their contents are explicitly part of the user contract.
|
||||
|
||||
## Concurrency And Async Boundaries
|
||||
|
||||
Use concurrency only where it improves a measured workflow such as independent page or resource retrieval. Bound concurrent requests to respect service and local limits.
|
||||
|
||||
Choose one owner for the event loop. Command handlers may call an async application boundary, but lower layers should not invoke nested event-loop runners. Keep synchronous and asynchronous APIs separate or adapt them in one explicit place.
|
||||
|
||||
## Suggested Package Shape
|
||||
|
||||
Adapt this shape to the project's size and existing conventions:
|
||||
|
||||
```text
|
||||
src/mycli/
|
||||
├── __main__.py
|
||||
├── cli.py
|
||||
├── config.py
|
||||
├── errors.py
|
||||
├── output.py
|
||||
├── api/
|
||||
│ ├── client.py
|
||||
│ ├── transport.py
|
||||
│ └── resources/
|
||||
└── auth/
|
||||
```
|
||||
|
||||
Small clients can combine modules while preserving the conceptual boundaries. Split code when a boundary has distinct dependencies, state, tests, or change cadence, not merely to reproduce the example tree.
|
||||
|
||||
## Design Sequence
|
||||
|
||||
1. Inventory the user tasks, execution environments, API capabilities, and existing project conventions.
|
||||
2. Define the command grammar, required inputs, destructive-operation policy, output modes, and exit-status contract before wiring endpoints.
|
||||
3. Define typed configuration and its precedence, including credential providers and active context.
|
||||
4. Establish API resource, transport, authentication, and error boundaries.
|
||||
5. Implement one vertical command path through parsing, service behavior, transport, rendering, and error mapping.
|
||||
6. Verify the path both in-process and as an installed subprocess before repeating the pattern.
|
||||
7. Add concurrency, retries, caching, rich presentation, and convenience prompts only where requirements justify them.
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- Unit-test command-independent services, API resources, renderers, configuration resolution, and error mapping directly.
|
||||
- Test command invocation with isolated environment variables, config directories, stdin, stdout, and stderr.
|
||||
- Assert exit status, stdout, and stderr independently.
|
||||
- Cover human and machine-readable output, including empty and multi-page results.
|
||||
- Use a mock transport for timeouts, malformed responses, pagination, rate limits, transient retries, and permanent failures.
|
||||
- Verify interactive confirmation and non-interactive refusal for destructive operations.
|
||||
- Test redaction with realistic secret shapes in headers, URLs, response bodies, and nested exceptions.
|
||||
- Add live-service tests only for behavior a local fake cannot represent, using isolated accounts and CI-managed credentials.
|
||||
- Build and install the distribution in a clean environment to verify the console entry point and runtime dependencies.
|
||||
|
||||
## Reference Map
|
||||
|
||||
| Topic | Load when | Reference |
|
||||
| --- | --- | --- |
|
||||
| Python library selection | Choosing or comparing a parser framework, terminal output, TUI, configuration, HTTP, authentication, testing, or packaging stack | [Python CLI library selection](./references/library-selection.md) |
|
||||
| OAuth for installed applications | The API uses OAuth, OIDC discovery, refresh tokens, loopback callbacks, or device authorization | [OAuth 2.0 for installed CLI clients](./references/oauth.md) |
|
||||
|
||||
## Completion Checks
|
||||
|
||||
1. Commands model recognizable user tasks with consistent names and options.
|
||||
2. Interactive conveniences have explicit non-interactive equivalents.
|
||||
3. Stdout, stderr, machine output, and exit statuses form a stable automation contract.
|
||||
4. Configuration has one visible precedence order and credentials use an appropriate protected source.
|
||||
5. Commands do not own raw HTTP, authentication lifecycle, or terminal-independent business logic.
|
||||
6. Timeouts, retries, pagination, cancellation, and state-changing request safety are explicit.
|
||||
7. Errors are actionable, categorized, redacted, and mapped at one process boundary.
|
||||
8. Destructive and batch operations define confirmation, idempotency, and partial-failure behavior.
|
||||
9. Tests exercise installed command behavior as well as isolated application and transport logic.
|
||||
10. Help text and diagnostics let users discover the command surface and effective non-secret configuration.
|
||||
@@ -0,0 +1,175 @@
|
||||
# Python CLI Library Selection
|
||||
|
||||
Use this reference when choosing libraries for a new Python CLI or deciding whether an existing stack still fits. Choose each layer independently: a command parser, terminal renderer, terminal UI, settings model, HTTP client, authentication implementation, test runner, and package manager solve different problems.
|
||||
|
||||
## Default Stack
|
||||
|
||||
For a new typed application CLI, start with:
|
||||
|
||||
| Concern | Default | Why |
|
||||
| --- | --- | --- |
|
||||
| Command parsing | [Cyclopts](https://cyclopts.readthedocs.io/en/latest/) | Type-driven commands, rich type support, docstring-derived help, validation, command groups, configuration sources, and testing helpers |
|
||||
| Human terminal output | [Rich](https://rich.readthedocs.io/en/stable/) | Tables, progress, status, syntax, terminal detection, and separate output consoles |
|
||||
| Settings and data validation | [Pydantic](https://docs.pydantic.dev/latest/) and [Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) | Typed models and explicit environment, dotenv, secret, and custom settings sources |
|
||||
| HTTP | [HTTPX2](https://pydantic.dev/docs/httpx2/) | Actively maintained synchronous and asynchronous APIs, explicit clients, timeouts, streaming, and testable transports |
|
||||
| OAuth | [Authlib 1.8+](https://pypi.org/project/Authlib/) | OAuth implementation integrated with HTTPX2; use the [OAuth reference](./oauth.md) for architecture and security requirements |
|
||||
| Tests | [pytest](https://docs.pytest.org/en/stable/) | Fixtures, parametrization, output capture, monkeypatching, and a broad plugin ecosystem |
|
||||
| Project and environment | [uv](https://docs.astral.sh/uv/) | Project dependencies, lockfiles, environments, scripts, builds, and tool execution |
|
||||
|
||||
Add [Textual](https://textual.textualize.io/) only when the product needs a persistent, event-driven terminal interface. It complements a command parser; it does not replace the scriptable command surface.
|
||||
|
||||
This is a starting point, not a mandate. Preserve a sound existing stack unless a requirement exposes a concrete limitation.
|
||||
|
||||
## Choose The Command Framework
|
||||
|
||||
### Use Cyclopts by default for a new typed application CLI
|
||||
|
||||
[Cyclopts](https://cyclopts.readthedocs.io/en/latest/) derives commands and parameters from Python function signatures and supports built-in and user-defined types, including unions, literals, dataclasses, Pydantic models, and attrs classes. It can derive help from docstrings and provides converters, validators, nested commands, lazy loading, configuration sources, documentation integration, and testing guidance.
|
||||
|
||||
Choose Cyclopts when:
|
||||
|
||||
- Modern type annotations should be the primary command schema.
|
||||
- Commands accept structured dataclasses or validation models.
|
||||
- Rich unions, literals, nested structures, or reusable parameter groups matter.
|
||||
- The project values concise declarations and generated documentation.
|
||||
- A newer and smaller ecosystem is an acceptable tradeoff.
|
||||
|
||||
Before committing, prototype the hardest command signature, help page, validation error, completion behavior, and test invocation. Do not evaluate a framework only on a one-command example.
|
||||
|
||||
### Use Typer for the mainstream type-driven choice
|
||||
|
||||
[Typer](https://typer.tiangolo.com/) also derives CLI arguments and options from Python type hints and provides automatic help, shell completion, nested command groups, Rich-formatted output, packaging guidance, and test helpers. It is a strong choice when contributor familiarity, established examples, and ecosystem recognition matter more than Cyclopts' broader type model.
|
||||
|
||||
Since Typer 0.26.0, [Typer vendors Click](https://typer.tiangolo.com/#click-code) rather than depending on the external Click package. Do not assume an arbitrary Click extension or subclass will integrate with modern Typer; verify that requirement against the installed Typer release.
|
||||
|
||||
Choose Typer when:
|
||||
|
||||
- The team already knows Typer or follows the FastAPI ecosystem.
|
||||
- The command types fit Typer's supported parameter model.
|
||||
- A familiar, established type-driven framework lowers contributor cost.
|
||||
- Existing Typer conventions or integrations outweigh framework-switching benefits.
|
||||
|
||||
### Use Click when explicit control is the requirement
|
||||
|
||||
[Click](https://click.palletsprojects.com/en/stable/) models commands, groups, contexts, parameters, types, and invocation explicitly. It supports arbitrary command nesting, lazy subcommand loading, custom parameter types, extension APIs, testing utilities, and a mature plugin ecosystem.
|
||||
|
||||
Choose Click when:
|
||||
|
||||
- The CLI is itself a framework or plugin host.
|
||||
- Commands must be discovered or loaded lazily.
|
||||
- Parsing, context propagation, invocation, or help behavior needs unusual customization.
|
||||
- Existing Click extensions are a hard dependency.
|
||||
- Explicit declarations are preferable to inference from application types.
|
||||
|
||||
Do not choose Click merely because it is mature. For ordinary application commands, the extra parser-level detail may duplicate function types, defaults, validation, and documentation.
|
||||
|
||||
### Use argparse when dependency constraints dominate
|
||||
|
||||
[`argparse`](https://docs.python.org/3/library/argparse.html) is the standard-library parser and supports subcommands, generated help, custom actions and types, argument files, and parser-level error handling. Python 3.14 added colored help and `suggest_on_error`, making its default experience more capable than older comparisons imply.
|
||||
|
||||
Choose argparse when:
|
||||
|
||||
- The tool must remain standard-library-only.
|
||||
- It is a small utility with a stable and modest command surface.
|
||||
- Conservative deployment environments value availability over declaration ergonomics.
|
||||
- Adding a runtime dependency has a real operational cost.
|
||||
|
||||
For a substantial typed application, account for the duplication between parser declarations and the application's function signatures, models, defaults, validation, and help text.
|
||||
|
||||
### Use Fire for exposure, not deliberate public design
|
||||
|
||||
[Python Fire](https://github.com/google/python-fire) generates a CLI from functions, classes, modules, mappings, and other Python objects. This is useful for developer tools, debugging, exploration, and rapidly exposing an internal Python API.
|
||||
|
||||
Avoid Fire as the default for a stable public CLI. Exposing the Python object model couples command names, arguments, and behavior to implementation details instead of treating the CLI as a deliberately designed compatibility surface.
|
||||
|
||||
## Framework Decision Table
|
||||
|
||||
| Primary requirement | Choose | Main tradeoff |
|
||||
| --- | --- | --- |
|
||||
| New, typed application with rich parameter models | Cyclopts | Smaller ecosystem and less accumulated operational history |
|
||||
| Type-driven CLI with maximum contributor familiarity | Typer | Verify complex typing and Click-extension assumptions |
|
||||
| Plugin framework or unusual parser behavior | Click | More explicit declarations and parser-specific code |
|
||||
| Standard-library-only or tiny utility | argparse | Imperative setup and duplicated schema information |
|
||||
| Rapid internal exposure of Python objects | Fire | Python implementation becomes the CLI contract |
|
||||
|
||||
When Cyclopts and Typer both fit, build the same representative vertical slice in each. Include the most complex parameter model, nested command registration, configuration injection, help output, validation failure, shell completion, and command test. Select from that evidence rather than syntax preference.
|
||||
|
||||
## Keep Complementary Libraries In Their Layer
|
||||
|
||||
### Rich is presentation, not parsing
|
||||
|
||||
Use [Rich](https://rich.readthedocs.io/en/stable/) behind a renderer abstraction for human-readable tables, progress, status displays, syntax, and styled errors. Keep structured output on a separate serialization path so `--output json` never contains decoration, progress, or terminal control codes.
|
||||
|
||||
Typer includes Rich as a dependency and uses it for formatted errors. Cyclopts can also produce Rich-oriented help and errors. This does not remove the need for an application-owned output boundary.
|
||||
|
||||
### Textual is an optional interactive mode
|
||||
|
||||
Use [Textual](https://textual.textualize.io/) when users need a persistent screen, navigation, reactive widgets, keyboard actions, or live dashboards. Keep ordinary parser commands for automation and direct operations:
|
||||
|
||||
```text
|
||||
mycli projects list -> scriptable command
|
||||
mycli interactive -> Textual application
|
||||
both -> application services -> API client
|
||||
```
|
||||
|
||||
The command and TUI adapters should call the same application services. Do not embed API and domain behavior separately in Textual event handlers.
|
||||
|
||||
## Supporting Stack Decisions
|
||||
|
||||
### Configuration and models
|
||||
|
||||
Use dataclasses when configuration is small, already parsed, and needs no source orchestration. Use [Pydantic](https://docs.pydantic.dev/latest/) for structured request, response, configuration, or command models that benefit from validation and serialization. Use [Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) when environment variables, dotenv files, secret files, or custom settings sources participate in explicit precedence.
|
||||
|
||||
Do not pass framework parameter objects into application services. Convert parser output into ordinary typed values or application models at the command boundary.
|
||||
|
||||
### HTTP
|
||||
|
||||
Use [HTTPX2](https://pydantic.dev/docs/httpx2/) for new API clients. It is the actively developed continuation of HTTPX and supports synchronous and asynchronous clients, explicit timeouts, streaming, custom authentication, and mock transports. [Authlib 1.8+](https://pypi.org/project/Authlib/) integrates with HTTPX2 directly. Reuse a client with explicit timeouts rather than calling top-level request functions throughout resource methods.
|
||||
|
||||
Preserve [HTTPX](https://www.python-httpx.org/) in a sound existing client until its dependencies, type checks, and transport tests are ready to migrate. Do not use HTTPX2's process-wide import alias from reusable library code, and do not keep HTTPX and HTTPX2 as permanent parallel transports without a concrete compatibility requirement.
|
||||
|
||||
Use [aiohttp](https://docs.aiohttp.org/en/stable/) when the project already standardizes on its async client, depends on its streaming or WebSocket behavior, or has measured requirements that justify a different transport. Do not introduce both HTTPX2 and aiohttp without a clear ownership boundary.
|
||||
|
||||
### Authentication
|
||||
|
||||
Use [Authlib 1.8+](https://pypi.org/project/Authlib/) for OAuth protocol behavior rather than implementing grants, PKCE, token parsing, and refresh directly. Keep it behind an authentication abstraction. For OAuth-enabled installed applications, follow [OAuth 2.0 for installed CLI clients](./oauth.md).
|
||||
|
||||
Use [keyring](https://keyring.readthedocs.io/en/latest/) to access operating-system credential stores when the deployment environment provides one. Treat headless secret storage as an explicit deployment decision rather than silently falling back to plaintext configuration.
|
||||
|
||||
### Testing and packaging
|
||||
|
||||
Use [pytest](https://docs.pytest.org/en/stable/) for application and command tests. Combine framework-level invocation helpers with subprocess tests of the installed console entry point; a runner helper alone does not verify packaging or startup behavior.
|
||||
|
||||
Use [uv](https://docs.astral.sh/uv/) for dependency management, lockfiles, isolated tool execution, and project commands when the repository adopts uv. Declare the CLI through a `[project.scripts]` entry point in [`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#creating-and-packaging-command-line-tools) so installation, tests, and users invoke the same bootstrap path.
|
||||
|
||||
## Architecture Rule
|
||||
|
||||
Do not couple application behavior to the chosen CLI framework:
|
||||
|
||||
```text
|
||||
Cyclopts / Typer / Click / argparse
|
||||
|
|
||||
v
|
||||
thin command adapters
|
||||
|
|
||||
v
|
||||
application services
|
||||
|
|
||||
v
|
||||
API client
|
||||
```
|
||||
|
||||
Command functions should parse or receive values, call an application service, and hand the result to a renderer. Keep API calls, authentication, retries, and domain decisions outside parser decorators and callbacks. This makes framework-specific tests small and keeps a future parser migration bounded.
|
||||
|
||||
## Selection Checklist
|
||||
|
||||
1. Identify the minimum supported Python version and dependency constraints.
|
||||
2. Model the hardest real command, not the smallest demonstration command.
|
||||
3. Decide whether type annotations or explicit parser objects should own the command schema.
|
||||
4. Check complex types, nested commands, lazy loading, plugins, completion, help, validation, and test support against actual requirements.
|
||||
5. Separate parsing from Rich presentation and optional Textual interaction.
|
||||
6. Select configuration, HTTP, authentication, testing, and packaging libraries independently.
|
||||
7. Prototype ambiguous framework choices with the same vertical slice.
|
||||
8. Pin compatible versions and verify behavior against installed-library documentation before implementation.
|
||||
9. Keep application services free of CLI-framework types.
|
||||
10. Preserve stable stdout, stderr, and exit-status contracts regardless of library defaults.
|
||||
@@ -0,0 +1,513 @@
|
||||
# OAuth 2.0 For Installed CLI Clients
|
||||
|
||||
Use this reference when a Python CLI calls an OAuth-protected API. Keep authentication, token lifecycle, HTTP transport, and API resources as separate ownership boundaries.
|
||||
|
||||
## Recommended Default
|
||||
|
||||
For an interactive installed CLI, use:
|
||||
|
||||
> Public client + Authorization Code + PKCE using `S256` + loopback callback + Authlib 1.8+ + HTTPX2 + protected credential store + centralized token refresh + minimum scopes.
|
||||
|
||||
Follow the current [OAuth 2.0 Security Best Current Practice](https://www.rfc-editor.org/rfc/rfc9700) and the [OAuth 2.0 guidance for native applications](https://www.rfc-editor.org/rfc/rfc8252). Do not use the implicit grant, Resource Owner Password Credentials grant, or an embedded client secret.
|
||||
|
||||
## Responsibility Boundaries
|
||||
|
||||
Keep dependencies pointed inward toward authentication and transport primitives:
|
||||
|
||||
```text
|
||||
CLI commands
|
||||
├── login/logout/status -> OAuthManager -> authorization server
|
||||
└── API commands -> ApiClient/resources -> OAuthTransport
|
||||
└── TokenManager
|
||||
├── TokenStore
|
||||
└── OAuth client / HTTP transport
|
||||
```
|
||||
|
||||
| Component | Owns | Must not own |
|
||||
| --- | --- | --- |
|
||||
| `OAuthManager` | Interactive login, callback validation, token exchange, logout | API resource methods |
|
||||
| `TokenStore` | Loading, atomically saving, and deleting sensitive token state | Refresh policy or HTTP requests |
|
||||
| `TokenManager` | Expiry checks, refresh synchronization, and valid access-token retrieval | CLI presentation or resource URLs |
|
||||
| `OAuthTransport` | Bearer-token injection and one bounded authentication retry | Interactive login UX |
|
||||
| `ApiClient` and resources | API operations, request models, and response models | OAuth grants, refresh tokens, or credential storage |
|
||||
|
||||
Keep [Authlib's HTTPX2 OAuth client](https://github.com/authlib/authlib/blob/v1.8.0/authlib/integrations/httpx_client/oauth2_client.py) behind the authentication boundary. API resources should request an authenticated transport or call `TokenManager.get_valid_access_token()`; they should not depend directly on Authlib.
|
||||
|
||||
## Library Selection
|
||||
|
||||
Use one library per responsibility and keep each one behind an application-owned interface:
|
||||
|
||||
| Concern | Default for new code | Use something else when |
|
||||
| --- | --- | --- |
|
||||
| OAuth protocol | [Authlib 1.8+](https://pypi.org/project/Authlib/) | A provider supplies an official, maintained SDK that correctly implements its non-standard behavior |
|
||||
| API and OAuth HTTP | [HTTPX2 2.x](https://pydantic.dev/docs/httpx2/) | Preserve HTTPX in an existing stable client until its dependencies and test doubles are ready to migrate |
|
||||
| Desktop credential storage | [keyring](https://keyring.readthedocs.io/en/latest/) | The target platforms are explicitly supported by a reviewed native alternative, or the deployment already owns a managed vault |
|
||||
| Async coordination | [`asyncio`](https://docs.python.org/3/library/asyncio-sync.html) for an asyncio-only CLI | The application already standardizes on [AnyIO](https://anyio.readthedocs.io/en/stable/) or supports multiple async backends |
|
||||
| Tests | [pytest](https://docs.pytest.org/en/stable/) and [`httpx2.MockTransport`](https://pydantic.dev/docs/httpx2/advanced/transports/#mock-transports) | The repository has an established equivalent |
|
||||
|
||||
[HTTPX2](https://pypi.org/project/httpx2/) is the actively developed continuation of HTTPX under Pydantic stewardship. It keeps the familiar client, request, response, authentication, and mock-transport APIs while using the `httpx2` import. Authlib 1.8 moved its HTTP client integration to HTTPX2, so new OAuth clients can use one HTTP implementation:
|
||||
|
||||
```bash
|
||||
uv add "Authlib>=1.8" "httpx2>=2" keyring
|
||||
```
|
||||
|
||||
Do not call [`httpx2.alias_httpx()`](https://pydantic.dev/docs/httpx2/api/api/#httpx2.alias_httpx) from reusable library code. It changes imports process-wide and exists as a temporary application-level migration aid. If an existing dependency still requires `httpx`, keep both clients behind local abstractions and remove HTTPX only after dependency and transport tests pass.
|
||||
|
||||
## Configuration And Secret State
|
||||
|
||||
Separate public OAuth configuration from sensitive OAuth state.
|
||||
|
||||
Public configuration may contain:
|
||||
|
||||
- Client ID for the registered public client.
|
||||
- Issuer, authorization endpoint, token endpoint, and optional revocation or device-authorization endpoint.
|
||||
- Exact registered redirect URI rules.
|
||||
- Required scopes and, when supported, resource or audience indicators.
|
||||
|
||||
Sensitive state includes:
|
||||
|
||||
- Access tokens.
|
||||
- Refresh tokens.
|
||||
- Token expiry and related token response fields when they reveal account or authorization state.
|
||||
|
||||
Represent the complete token response and store it through a narrow abstraction. A `TypedDict` documents the common fields without discarding provider-specific fields from the runtime dictionary:
|
||||
|
||||
```python
|
||||
from typing import Protocol, Required, TypedDict
|
||||
|
||||
|
||||
class OAuthToken(TypedDict, total=False):
|
||||
access_token: Required[str]
|
||||
refresh_token: str
|
||||
token_type: str
|
||||
expires_at: float
|
||||
expires_in: int
|
||||
scope: str
|
||||
|
||||
|
||||
class TokenStore(Protocol):
|
||||
async def load(self) -> OAuthToken | None: ...
|
||||
async def save(self, token: OAuthToken) -> None: ...
|
||||
async def delete(self) -> None: ...
|
||||
```
|
||||
|
||||
For a desktop CLI, [keyring](https://keyring.readthedocs.io/en/latest/) remains the conservative default because it selects macOS Keychain, Windows Credential Locker, Secret Service, or KWallet as available. Its API is synchronous, so move calls off the event-loop thread. Store one JSON document per account so access-token and refresh-token rotation is replaced as one logical update:
|
||||
|
||||
```python
|
||||
import json
|
||||
from typing import cast
|
||||
|
||||
import anyio
|
||||
import keyring
|
||||
from keyring.backend import KeyringBackend
|
||||
from keyring.errors import KeyringError
|
||||
|
||||
|
||||
class CredentialStoreError(RuntimeError):
|
||||
pass
|
||||
|
||||
|
||||
class KeyringTokenStore:
|
||||
def __init__(
|
||||
self,
|
||||
service: str,
|
||||
account: str,
|
||||
backend: KeyringBackend | None = None,
|
||||
) -> None:
|
||||
self._service = service
|
||||
self._account = account
|
||||
self._backend = backend or keyring.get_keyring()
|
||||
if self._backend.priority <= 0:
|
||||
raise CredentialStoreError("No protected credential store is available")
|
||||
|
||||
async def load(self) -> OAuthToken | None:
|
||||
try:
|
||||
raw = await anyio.to_thread.run_sync(
|
||||
self._backend.get_password, self._service, self._account
|
||||
)
|
||||
except KeyringError as error:
|
||||
raise CredentialStoreError("Could not read OAuth credentials") from error
|
||||
if raw is None:
|
||||
return None
|
||||
try:
|
||||
value = json.loads(raw)
|
||||
except json.JSONDecodeError as error:
|
||||
raise CredentialStoreError("Stored OAuth credentials are invalid") from error
|
||||
if not isinstance(value, dict) or not isinstance(value.get("access_token"), str):
|
||||
raise CredentialStoreError("Stored OAuth credentials are invalid")
|
||||
return cast("OAuthToken", value)
|
||||
|
||||
async def save(self, token: OAuthToken) -> None:
|
||||
encoded = json.dumps(token, separators=(",", ":"))
|
||||
try:
|
||||
await anyio.to_thread.run_sync(
|
||||
self._backend.set_password,
|
||||
self._service,
|
||||
self._account,
|
||||
encoded,
|
||||
)
|
||||
except KeyringError as error:
|
||||
raise CredentialStoreError("Could not save OAuth credentials") from error
|
||||
|
||||
async def delete(self) -> None:
|
||||
if await self.load() is None:
|
||||
return
|
||||
try:
|
||||
await anyio.to_thread.run_sync(
|
||||
self._backend.delete_password, self._service, self._account
|
||||
)
|
||||
except KeyringError as error:
|
||||
raise CredentialStoreError("Could not delete OAuth credentials") from error
|
||||
```
|
||||
|
||||
Fail closed when no recommended backend is available. Do not install [`keyrings.alt`](https://pypi.org/project/keyrings.alt/) as an automatic fallback; it intentionally includes possibly insecure backends.
|
||||
|
||||
### Storage Alternatives
|
||||
|
||||
- Consider [`rust-native-keyring`](https://pypi.org/project/rust-native-keyring/) when native compiled wheels, the Rust [keyring ecosystem](https://github.com/open-source-cooperative/keyring-rs), and its richer credential-store selection fit the supported platforms. Its Python package is still `0.x`, so pin it, verify wheel availability, and test lock/unlock and deletion behavior on every target OS before preferring it over `keyring`.
|
||||
- Consider the official [1Password Python SDK](https://www.1password.dev/sdks/) when users already rely on 1Password and desktop authorization prompts, auditing, or shared vault policy are product requirements. It is asynchronous and supports desktop-app authorization, but its SDK is also still version `0`; it is not a transparent local-keyring replacement.
|
||||
- Use a managed service such as [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets-python-sdk.html), [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/secrets/quick-create-python), [Google Secret Manager](https://docs.cloud.google.com/secret-manager/docs/reference/libraries), or [HashiCorp Vault](https://developer.hashicorp.com/vault/docs/get-started/developer-qs) for unattended or centrally governed deployments. Authenticate with workload identity or another deployment-owned mechanism; do not solve storage by introducing a second long-lived bootstrap secret.
|
||||
|
||||
For a headless environment without a credential service, require an explicit storage backend appropriate to its threat model; do not silently fall back to plaintext config. Never emit tokens through logs, telemetry, exceptions, shell output, or status commands.
|
||||
|
||||
## Interactive Authorization
|
||||
|
||||
Use Authorization Code with PKCE for browser-based login:
|
||||
|
||||
1. Generate a cryptographically random `state` and a fresh PKCE `code_verifier` for every attempt.
|
||||
2. Derive the `S256` code challenge and construct the authorization URL with the exact requested redirect URI and minimum scopes.
|
||||
3. Bind a temporary listener to `127.0.0.1` on an ephemeral port. Do not expose it on all interfaces.
|
||||
4. Open the system browser and wait for one callback with a short timeout and cancellation path.
|
||||
5. Reject OAuth errors, a missing code, or any callback whose `state` does not exactly match.
|
||||
6. Exchange the code using the original verifier and redirect URI.
|
||||
7. Persist the complete returned token state atomically, then stop the listener immediately.
|
||||
8. Return a minimal success page and CLI message without displaying credentials.
|
||||
|
||||
Treat the CLI as a public client. A secret distributed inside source, a package, a binary, or an environment-independent configuration file cannot authenticate installed copies of the CLI.
|
||||
|
||||
The following manager shows the Authlib-owned part of a loopback flow. A separate callback receiver should bind `127.0.0.1`, accept one request, enforce a timeout and maximum request size, then pass the complete callback URL to `finish()`:
|
||||
|
||||
```python
|
||||
import secrets
|
||||
from dataclasses import dataclass
|
||||
from urllib.parse import parse_qs, urlsplit
|
||||
|
||||
from authlib.integrations.httpx_client import AsyncOAuth2Client
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class OAuthConfig:
|
||||
client_id: str
|
||||
authorization_endpoint: str
|
||||
token_endpoint: str
|
||||
redirect_uri: str
|
||||
scopes: tuple[str, ...]
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class PendingAuthorization:
|
||||
url: str
|
||||
state: str
|
||||
code_verifier: str
|
||||
|
||||
|
||||
class OAuthManager:
|
||||
def __init__(self, config: OAuthConfig, store: TokenStore) -> None:
|
||||
self._config = config
|
||||
self._store = store
|
||||
self._client = AsyncOAuth2Client(
|
||||
client_id=config.client_id,
|
||||
redirect_uri=config.redirect_uri,
|
||||
scope=" ".join(config.scopes),
|
||||
code_challenge_method="S256",
|
||||
token_endpoint_auth_method="none",
|
||||
)
|
||||
|
||||
def begin(self) -> PendingAuthorization:
|
||||
verifier = secrets.token_urlsafe(64)
|
||||
url, state = self._client.create_authorization_url(
|
||||
self._config.authorization_endpoint,
|
||||
code_verifier=verifier,
|
||||
)
|
||||
return PendingAuthorization(url=url, state=state, code_verifier=verifier)
|
||||
|
||||
async def finish(
|
||||
self, callback_url: str, pending: PendingAuthorization
|
||||
) -> OAuthToken:
|
||||
callback = urlsplit(callback_url)
|
||||
expected = urlsplit(self._config.redirect_uri)
|
||||
callback_target = (callback.scheme, callback.hostname, callback.port, callback.path)
|
||||
expected_target = (expected.scheme, expected.hostname, expected.port, expected.path)
|
||||
if callback_target != expected_target:
|
||||
raise AuthenticationError("OAuth callback used an unexpected redirect URI")
|
||||
|
||||
query = parse_qs(callback.query)
|
||||
if query.get("state") != [pending.state]:
|
||||
raise AuthenticationError("OAuth callback state did not match")
|
||||
if "error" in query:
|
||||
raise AuthenticationError("Authorization server rejected login")
|
||||
code = query.get("code", [None])[0]
|
||||
if code is None:
|
||||
raise AuthenticationError("OAuth callback did not contain a code")
|
||||
|
||||
result = await self._client.fetch_token(
|
||||
self._config.token_endpoint,
|
||||
code=code,
|
||||
code_verifier=pending.code_verifier,
|
||||
)
|
||||
token = cast("OAuthToken", dict(result))
|
||||
await self._store.save(token)
|
||||
return token
|
||||
|
||||
async def aclose(self) -> None:
|
||||
await self._client.aclose()
|
||||
```
|
||||
|
||||
Do not persist `PendingAuthorization`: `state` and `code_verifier` are short-lived, single-attempt values. Define `AuthenticationError` in the application's stable error taxonomy and keep callback query values out of its message.
|
||||
|
||||
If a browser or loopback listener is impractical and the provider exposes it, use the standardized [Device Authorization Grant](https://www.rfc-editor.org/rfc/rfc8628). Respect the server-provided polling interval, `slow_down`, expiration, and cancellation behavior. Do not invent a device flow against a provider that does not advertise or document one.
|
||||
|
||||
## Authorization Server Metadata
|
||||
|
||||
Prefer [OAuth 2.0 Authorization Server Metadata](https://www.rfc-editor.org/rfc/rfc8414) or OpenID Connect discovery when the provider supports it. Validate that discovered metadata belongs to the configured issuer and require HTTPS for non-loopback endpoints.
|
||||
|
||||
Use explicit endpoints when discovery is unavailable or when a controlled deployment intentionally pins them. Do not mix endpoints discovered from one issuer with configuration from another.
|
||||
|
||||
## Token Lifecycle
|
||||
|
||||
Centralize expiry and refresh decisions in `TokenManager`:
|
||||
|
||||
```text
|
||||
load token
|
||||
├── missing -> authentication required
|
||||
├── valid beyond refresh leeway -> return access token
|
||||
└── expired or near expiry
|
||||
└── acquire refresh lock
|
||||
├── reload token
|
||||
├── return it if another task refreshed it
|
||||
└── refresh, atomically persist the full response, and return it
|
||||
```
|
||||
|
||||
Use a small expiry leeway, commonly 60 seconds, to avoid starting a request with a token that expires in transit. For a single-process async CLI, an `asyncio.Lock` is sufficient for in-process refresh coordination. If multiple processes can share one token store, add storage-level coordination or optimistic versioning; an in-process lock cannot prevent cross-process races.
|
||||
|
||||
Preserve a refresh token when the server omits it from a refresh response, but replace it whenever rotation returns a new one. Save the newly returned token as one atomic state update so an older writer cannot restore a superseded refresh token.
|
||||
|
||||
Classify missing, expired-without-refresh, rejected-refresh, and revoked credentials as authentication failures with a clear path to log in again. Do not turn refresh failures into anonymous API calls.
|
||||
|
||||
A small refresher adapter and token manager keep Authlib details out of storage and API resources:
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
import time
|
||||
from collections.abc import Callable
|
||||
|
||||
|
||||
class AuthenticationError(RuntimeError):
|
||||
pass
|
||||
|
||||
|
||||
class AuthlibTokenRefresher:
|
||||
def __init__(self, config: OAuthConfig) -> None:
|
||||
self._config = config
|
||||
|
||||
async def refresh(self, token: OAuthToken) -> OAuthToken:
|
||||
refresh_token = token.get("refresh_token")
|
||||
if refresh_token is None:
|
||||
raise AuthenticationError("Login is required")
|
||||
async with AsyncOAuth2Client(
|
||||
client_id=self._config.client_id,
|
||||
token=dict(token),
|
||||
token_endpoint_auth_method="none",
|
||||
) as client:
|
||||
result = await client.refresh_token(
|
||||
self._config.token_endpoint,
|
||||
refresh_token=refresh_token,
|
||||
)
|
||||
refreshed = cast("OAuthToken", dict(result))
|
||||
refreshed.setdefault("refresh_token", refresh_token)
|
||||
return refreshed
|
||||
|
||||
|
||||
class TokenManager:
|
||||
def __init__(
|
||||
self,
|
||||
store: TokenStore,
|
||||
refresher: AuthlibTokenRefresher,
|
||||
*,
|
||||
refresh_leeway: float = 60.0,
|
||||
clock: Callable[[], float] = time.time,
|
||||
) -> None:
|
||||
self._store = store
|
||||
self._refresher = refresher
|
||||
self._refresh_leeway = refresh_leeway
|
||||
self._clock = clock
|
||||
self._lock = asyncio.Lock()
|
||||
|
||||
def _is_usable(self, token: OAuthToken) -> bool:
|
||||
expires_at = token.get("expires_at")
|
||||
return expires_at is None or expires_at > self._clock() + self._refresh_leeway
|
||||
|
||||
async def get_valid_access_token(self, *, force_refresh: bool = False) -> str:
|
||||
token = await self._store.load()
|
||||
if token is None:
|
||||
raise AuthenticationError("Login is required")
|
||||
if not force_refresh and self._is_usable(token):
|
||||
return token["access_token"]
|
||||
|
||||
async with self._lock:
|
||||
token = await self._store.load()
|
||||
if token is None:
|
||||
raise AuthenticationError("Login is required")
|
||||
if not force_refresh and self._is_usable(token):
|
||||
return token["access_token"]
|
||||
refreshed = await self._refresher.refresh(token)
|
||||
await self._store.save(refreshed)
|
||||
return refreshed["access_token"]
|
||||
```
|
||||
|
||||
This lock covers one process. Replace or augment it with storage-level compare-and-swap or an inter-process lock when several processes share the same credential entry.
|
||||
|
||||
## Authenticated HTTP Transport
|
||||
|
||||
The transport should:
|
||||
|
||||
1. Obtain a valid access token before sending a protected request.
|
||||
2. Inject the authorization header without exposing the token to API resource code.
|
||||
3. Apply the project's normal timeout, TLS, proxy, retry, and error-mapping policy.
|
||||
4. Optionally react to one `401` by forcing one synchronized refresh and replaying the request once.
|
||||
5. Raise an authentication error if the replay is still unauthorized.
|
||||
|
||||
Do not refresh blindly on every `401`; unauthorized responses can indicate revocation, malformed credentials, the wrong audience, or another authentication failure. Never create an unbounded refresh or request loop. Replay only requests whose body can be safely regenerated, and do not treat `403` as an expiry signal.
|
||||
|
||||
[HTTPX2 custom authentication](https://pydantic.dev/docs/httpx2/advanced/authentication/#custom-authentication-schemes) is a compact way to apply the token manager to every API request. This example retries one bodyless, read-only request after a synchronized refresh and leaves all other `401` responses untouched:
|
||||
|
||||
```python
|
||||
import httpx2
|
||||
|
||||
|
||||
class OAuthAuth(httpx2.Auth):
|
||||
requires_response_body = True
|
||||
|
||||
def __init__(self, tokens: TokenManager) -> None:
|
||||
self._tokens = tokens
|
||||
|
||||
def sync_auth_flow(self, request: httpx2.Request):
|
||||
raise RuntimeError("OAuthAuth requires httpx2.AsyncClient")
|
||||
yield request
|
||||
|
||||
async def async_auth_flow(self, request: httpx2.Request):
|
||||
access_token = await self._tokens.get_valid_access_token()
|
||||
request.headers["Authorization"] = f"Bearer {access_token}"
|
||||
response = yield request
|
||||
|
||||
if response.status_code != 401 or request.method not in {"GET", "HEAD", "OPTIONS"}:
|
||||
return
|
||||
access_token = await self._tokens.get_valid_access_token(force_refresh=True)
|
||||
request.headers["Authorization"] = f"Bearer {access_token}"
|
||||
yield request
|
||||
|
||||
|
||||
class ApiClient:
|
||||
def __init__(self, base_url: str, tokens: TokenManager) -> None:
|
||||
self._http = httpx2.AsyncClient(
|
||||
base_url=base_url,
|
||||
auth=OAuthAuth(tokens),
|
||||
timeout=httpx2.Timeout(20.0, connect=5.0),
|
||||
)
|
||||
|
||||
async def get_project(self, project_id: str) -> dict[str, object]:
|
||||
response = await self._http.get(f"/projects/{project_id}")
|
||||
response.raise_for_status()
|
||||
value = response.json()
|
||||
if not isinstance(value, dict):
|
||||
raise ValueError("Expected an object response")
|
||||
return value
|
||||
|
||||
async def aclose(self) -> None:
|
||||
await self._http.aclose()
|
||||
```
|
||||
|
||||
For streaming requests, uploads, or state-changing methods, omit automatic replay unless the API supplies an idempotency mechanism and the request body can be rebuilt. Map the final HTTPX2 response or exception into application errors before it reaches a CLI command.
|
||||
|
||||
## Scopes And Token Restrictions
|
||||
|
||||
- Request only scopes needed by the CLI's supported operations.
|
||||
- Keep scopes explicit in configuration and stable in tests.
|
||||
- Request offline access or equivalent provider-specific scope only when refresh tokens are needed.
|
||||
- Use audience or resource restrictions when supported.
|
||||
- Detect when stored authorization lacks scopes required by a command and direct the user through deliberate reauthorization rather than quietly broadening every login.
|
||||
|
||||
## CLI Surface
|
||||
|
||||
Expose a small authentication surface consistent with the existing command framework:
|
||||
|
||||
```text
|
||||
mycli login
|
||||
mycli logout
|
||||
mycli auth status
|
||||
```
|
||||
|
||||
`login` starts interactive authorization and reports only progress and outcome. `logout` deletes local token state and uses the provider's revocation endpoint when supported; explain if remote revocation fails after local deletion. `auth status` may show account identity, granted scopes, issuer, and expiry, but never a token or authorization code.
|
||||
|
||||
A manual `auth refresh` command is optional and primarily diagnostic. Normal API commands should not require users to manage refresh timing.
|
||||
|
||||
## Suggested Package Shape
|
||||
|
||||
Adapt names to the existing project rather than forcing this exact tree:
|
||||
|
||||
```text
|
||||
src/mycli/
|
||||
├── cli.py
|
||||
├── errors.py
|
||||
├── api/
|
||||
│ ├── client.py
|
||||
│ ├── transport.py
|
||||
│ └── resources/
|
||||
└── auth/
|
||||
├── config.py
|
||||
├── manager.py
|
||||
├── token.py
|
||||
└── store.py
|
||||
```
|
||||
|
||||
Keep token models independent from provider client objects so storage, tests, and API code do not inherit Authlib's internal representation as a public application contract.
|
||||
|
||||
## Branching Guidance
|
||||
|
||||
- If the provider supports loopback redirects: use Authorization Code with PKCE and an ephemeral `127.0.0.1` listener.
|
||||
- If the execution environment cannot open a browser or accept a loopback callback: use Device Authorization Grant only when the provider supports it.
|
||||
- If the API is called by unattended automation rather than a person: use the provider's machine-to-machine grant and credential mechanism; do not reuse an interactive user's refresh token as service identity.
|
||||
- If the provider supports discovery: derive endpoints from validated issuer metadata; otherwise pin explicit HTTPS endpoints.
|
||||
- If requests are concurrent in one process: serialize refresh with a lock and re-read state after acquisition.
|
||||
- If token state is shared across processes: use inter-process coordination and atomic persistence.
|
||||
- If an existing CLI already has HTTP and configuration abstractions: integrate at those boundaries instead of replacing the command framework or resource layer.
|
||||
|
||||
## Tests And Verification
|
||||
|
||||
Test protocol behavior without depending on a live identity provider:
|
||||
|
||||
- Login creates fresh state and verifier values and uses `S256`.
|
||||
- Callback handling accepts the expected state and rejects missing, mismatched, duplicate, timed-out, and OAuth-error callbacks.
|
||||
- The listener binds only to loopback and always shuts down.
|
||||
- Token exchange uses the same redirect URI and verifier as authorization.
|
||||
- Valid tokens bypass refresh; near-expiry tokens refresh once.
|
||||
- Concurrent requests cause one refresh and all callers observe the persisted replacement token.
|
||||
- Refresh-token rotation cannot be overwritten by stale state.
|
||||
- A `401` causes at most one eligible replay; a second `401` fails.
|
||||
- Status and error output remain useful without revealing token values.
|
||||
- Logout clears local state and handles optional remote revocation explicitly.
|
||||
|
||||
Use deterministic clocks, fake token stores, and [`httpx2.MockTransport`](https://pydantic.dev/docs/httpx2/advanced/transports/#mock-transports) for unit tests. Add a provider integration test only when the project has suitable isolated credentials and CI secret handling.
|
||||
|
||||
## Completion Checks
|
||||
|
||||
1. The CLI is registered and implemented as a public client without an embedded secret.
|
||||
2. Interactive login uses Authorization Code with PKCE `S256`, fresh state, exact redirect validation, and a bounded loopback listener.
|
||||
3. Device authorization is conditional on provider support and follows server polling instructions.
|
||||
4. Token storage is replaceable, protected, atomic, and absent from logs and normal output.
|
||||
5. One component owns expiry, synchronized refresh, and refresh-token rotation.
|
||||
6. API resources remain independent of OAuth protocol and storage details.
|
||||
7. Scopes and audience are minimal and explicit.
|
||||
8. Authentication retries are bounded and replay only eligible requests.
|
||||
9. Login, logout, status, refresh, concurrency, callback rejection, and redaction paths have focused verification.
|
||||
10. Provider-specific behavior and installed dependency versions are checked against current primary documentation.
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: nicegui
|
||||
description: 'Build, review, and debug NiceGUI applications. Use for FastAPI or Uvicorn integration, app factories and lifespan, ui.* components, Quasar props/events/slots, Tailwind page layout, colors and dark mode, bindings and bindable_dataclass, editable ui.table cells, uploads/forms/live updates, or version-specific NiceGUI source research.'
|
||||
description: 'Build, review, debug, configure, deploy, and package NiceGUI applications. Use for FastAPI or Uvicorn integration, ui.run settings, native mode, Docker or executable deployment, app factories and lifespan, thin pages and reusable component factories, bindable dataclass handles, ui.refreshable methods, ui.* components, Quasar props/events/slots, Tailwind layout, colors, bindings, editable ui.table cells, uploads/forms/live updates, or version-specific source research.'
|
||||
---
|
||||
|
||||
# NiceGUI Application Guide
|
||||
@@ -19,21 +19,27 @@ Use this skill to choose the smallest supporting reference for a NiceGUI task. T
|
||||
|
||||
| Task or symptom | Load first | Add only when |
|
||||
| --- | --- | --- |
|
||||
| Choose package boundaries, dependency direction, page registration, health routes, or optional persistence, LangGraph, and mounted-docs placement | [application architecture](./references/architecture.md) | Add [FastAPI and Uvicorn startup](./references/fastapi-uvicorn-startup.md) for concrete ASGI ownership or startup code. |
|
||||
| Decide between `ui.run()` and `ui.run_with()`, compose a parent FastAPI app, define lifespan ordering, build an app factory, configure typed settings, expose a project script, or handle reload/workers | [FastAPI and Uvicorn startup](./references/fastapi-uvicorn-startup.md) | Add [application architecture](./references/architecture.md) only for wider package placement. |
|
||||
| Choose package boundaries, dependency direction, thin page composition, reusable component factories, returned dataclass component handles, page registration, health routes, or optional subsystem placement | [application architecture](./references/architecture.md) | Add [binding dataclasses](./references/binding-dataclasses.md) for the component handle's binding graph or [FastAPI and Uvicorn startup](./references/fastapi-uvicorn-startup.md) for concrete ASGI ownership. |
|
||||
| Decide between `ui.run()` and `ui.run_with()`, compose a parent FastAPI app, define lifespan ordering, build an app factory, configure typed settings, expose a project script, or handle reload/workers | [FastAPI and Uvicorn startup](./references/fastapi-uvicorn-startup.md) | Add [configuration and deployment](./references/configuration-and-deployment.md) for concrete `ui.run` options, hosting, native mode, or packaging. |
|
||||
| Configure `ui.run`, consume `app.urls`, select NiceGUI environment variables, run behind Docker or a reverse proxy, enable HTTPS, build a native app, package with PyInstaller or Nuitka, or evaluate NiceGUI On Air | [configuration and deployment](./references/configuration-and-deployment.md) | Add [FastAPI and Uvicorn startup](./references/fastapi-uvicorn-startup.md) when a parent ASGI app, app factory, lifespan, reload, or workers own part of startup. |
|
||||
| Choose a `ui.*` constructor, binding, Quasar prop, event, slot, or frontend method; diagnose model events, event payloads, scoped-slot props, detached popups, `ui.select`, or `ui.icon` | [component mechanics](./references/component-mechanics.md) | Add [source documentation](./references/source-documentation.md) when the installed wrapper or bundled Quasar version must be verified. |
|
||||
| Build page shells, rows, columns, grids, widths, overflow, responsive reflow, typography, font loading, static assets, or deliberate scaling | [page structure, typography, and scaling](./references/styling-and-customization.md) | Add [component mechanics](./references/component-mechanics.md) when layout depends on a Quasar prop, slot, popup, or generated component structure. |
|
||||
| Configure `app.colors()`, `ui.colors()`, semantic or fixed Quasar colors, custom color names, component color values, CSS color variables, or `ui.dark_mode()` | [NiceGUI and Quasar color theming](./references/colors-and-quasar-theming.md) | Add [page structure, typography, and scaling](./references/styling-and-customization.md) only when the task also changes physical layout or CSS loading. |
|
||||
| Model typed page state with `binding.bindable_dataclass`, understand propagation and transform direction, bind nested values, avoid active-link polling, or design projection/persistence rollback | [binding dataclasses](./references/binding-dataclasses.md) | Add [component mechanics](./references/component-mechanics.md) for browser-originated event proposals. |
|
||||
| Model typed page or component state with `binding.bindable_dataclass`, return a bound component handle, understand propagation and transform direction, bind nested values, avoid active-link polling, or design projection/persistence rollback | [binding dataclasses](./references/binding-dataclasses.md) | Add [application architecture](./references/architecture.md) for the render-factory and thin-page boundary or [component mechanics](./references/component-mechanics.md) for browser-originated proposals. |
|
||||
| Customize `ui.table` or QTable columns, formatting, classes, props, responsive density, toolbar controls, visible columns, empty states, named slots, or frontend methods | [table customization](./references/table-customization.md) | Add [editable tables](./references/tables.md) only when cells also accept server-authoritative edits. |
|
||||
| Make `ui.table` cells editable with stable row keys, dataframe projections, row-scoped dataclasses, validation, touched rows, selection-preserving refresh, or `QPopupEdit` | [editable tables](./references/tables.md) | Follow its links to binding or component mechanics only when changing the underlying projection or event bridge. |
|
||||
| Implement uploads, form submission, SSE versus WebSockets, background jobs, duplicate-submit guards, or explicit `@ui.refreshable` refreshes | [interaction patterns](./references/interaction-patterns.md) | Add [binding dataclasses](./references/binding-dataclasses.md) when state propagation itself is the problem. |
|
||||
| Implement uploads, form submission, SSE versus WebSockets, background jobs, duplicate-submit guards, or `@ui.refreshable` and `@ui.refreshable_method` component regions | [interaction patterns](./references/interaction-patterns.md) | Add [application architecture](./references/architecture.md) for the reusable component contract or [binding dataclasses](./references/binding-dataclasses.md) when state propagation itself is the problem. |
|
||||
| Build or explain URL-backed tabs, persistent tab panels, `ui.sub_pages` route adapters, browser-history synchronization, or parameterized routes that share one tab | [URL-backed tabs with sub pages](./references/tabbed-subpages.md) | Add [binding dataclasses](./references/binding-dataclasses.md) only when the route-backed state grows beyond the single field shown in the example. |
|
||||
| Investigate upload errors, async UI races, stale assets, navigation/state drift, or perform a compact production-readiness review | [troubleshooting and quality gates](./references/troubleshooting-and-quality-gates.md) | Follow the symptom to one detailed reference above. |
|
||||
| Verify a framework claim against primary NiceGUI, FastAPI, Uvicorn, Tailwind, Quasar, SQLAlchemy, Pydantic, or LangGraph documentation | [source documentation](./references/source-documentation.md) | Use a task page first when implementation guidance, not source lookup, is needed. |
|
||||
|
||||
## Boundary Rules
|
||||
|
||||
- Use [application architecture](./references/architecture.md) for module ownership, not for page geometry or low-level component behavior.
|
||||
- Use [FastAPI and Uvicorn startup](./references/fastapi-uvicorn-startup.md) to decide which process owns startup; use [configuration and deployment](./references/configuration-and-deployment.md) after that decision for runtime, native, hosting, and packaging settings.
|
||||
- Keep page functions thin: compose page shells and returned component handles there; keep each component's element tree, bindings, callbacks, and bounded refreshes in its render factory or component object.
|
||||
- Use [page structure, typography, and scaling](./references/styling-and-customization.md) for physical layout. Use [component mechanics](./references/component-mechanics.md) for the behavior crossing NiceGUI, Quasar, Vue, and browser boundaries.
|
||||
- Start read-only table presentation and QTable control work in [table customization](./references/table-customization.md); keep editable state and validation in [editable tables](./references/tables.md).
|
||||
- Use [binding dataclasses](./references/binding-dataclasses.md) for the binding graph and Python model projections. Use [interaction patterns](./references/interaction-patterns.md) for user workflows such as upload, submit, refresh, streaming, and background work.
|
||||
- Start editable-table work in [editable tables](./references/tables.md). It already identifies the exact binding and event sections needed by that pattern.
|
||||
- Treat [source documentation](./references/source-documentation.md) as a source index, not as an implementation workflow.
|
||||
@@ -44,16 +50,21 @@ Load an example only when its exact mechanic matches the task:
|
||||
|
||||
- [binding transforms](./examples/data_binding.py): `bindable_dataclass`, `ui.date`, and typed `forward`/`backward` conversion.
|
||||
- [select events](./examples/select_events.py): `on_change`, generic Quasar events, `update:model-value`, browser-to-Python payload forwarding, and programmatic value changes.
|
||||
- [editable table](./examples/editable_table.py): dataframe-to-row state, named QTable cell slots, controlled editors, Python validation, touched rows, and canonical row refresh.
|
||||
- [table customization](./examples/table_customization.py): raw-value sorting with cosmetic prefix, suffix, and datetime formatting; dynamic classes; QTable props; toolbar and cell slots; filtering; visible columns; and empty states.
|
||||
- [editable table](./examples/editable_table.py): dataframe-to-row state, named QTable cell slots, controlled editors, dialog-based whole-row save/cancel edits, Python validation, touched rows, and canonical row refresh.
|
||||
- [tabbed sub-pages](./examples/tab_spa.py): a persistent shell with URL-backed tabs, tab panels, browser-history navigation, and retained state for a parameterized report route. See the [reference explanation](./references/tabbed-subpages.md) for the ownership model and behavioral boundaries.
|
||||
|
||||
## Defaults That Span References
|
||||
|
||||
- Keep composition, transport, services, pages, and components directionally separated.
|
||||
- Prefer reusable render functions that return typed component handles; use bindable dataclass fields for the state intentionally exposed to composition code.
|
||||
- Keep business logic out of UI components and event handlers.
|
||||
- Avoid blocking I/O and CPU-heavy work in the UI event loop.
|
||||
- Prefer event-driven updates and explicit refreshes to unrelated polling.
|
||||
- Keep browser-originated values as proposals; validate and normalize them in Python before mutating authoritative state.
|
||||
- Use Tailwind for physical structure and scoped static CSS only for requirements that NiceGUI, Quasar, or utilities cannot express cleanly.
|
||||
- Prefer NiceGUI context managers and `ui.*` elements over raw Vue templates. Keep application logic and authoritative state in Python; use minimal browser expressions only for scoped-slot values or client-only behavior, following [Python-owned slot composition](./references/component-mechanics.md#prefer-python-owned-composition).
|
||||
- For each presentation requirement, check the component's typed Python arguments and helpers before using `.props(...)` or `.classes(...)`. Create an application class and add CSS only when no Python API, documented component prop or slot, or existing utility class can express the requirement.
|
||||
- Use NiceGUI context managers for element structure and Tailwind for generic layout, spacing, responsive behavior, and typography. Keep Quasar classes for semantic palette roles or component-specific geometry, and use Quasar props for component behavior and density; see [combining Tailwind with Quasar utilities](./references/styling-and-customization.md#combine-tailwind-with-quasar-utilities-deliberately).
|
||||
- Provide loading, success, and failure states for user-triggered work.
|
||||
- Verify component-specific behavior against the installed NiceGUI version and its bundled Quasar version.
|
||||
|
||||
|
||||
@@ -3,9 +3,11 @@
|
||||
# dependencies = [
|
||||
# "nicegui==3.16.0",
|
||||
# "pandas",
|
||||
# "pydantic>=2",
|
||||
# ]
|
||||
# ///
|
||||
|
||||
from collections.abc import Callable
|
||||
from dataclasses import dataclass
|
||||
from dataclasses import field
|
||||
|
||||
@@ -13,6 +15,9 @@ import pandas as pd
|
||||
from nicegui import binding
|
||||
from nicegui import events
|
||||
from nicegui import ui
|
||||
from pydantic import BaseModel
|
||||
from pydantic import ValidationError
|
||||
from pydantic import field_validator
|
||||
|
||||
STATUS_OPTIONS = ["draft", "active", "archived"]
|
||||
EDITABLE_FIELDS = ("name", "quantity", "status")
|
||||
@@ -21,6 +26,52 @@ type TableValue = str | int
|
||||
type TableRow = dict[str, TableValue]
|
||||
|
||||
|
||||
class RowEditDraft(BaseModel):
|
||||
name: str
|
||||
quantity: int
|
||||
status: str
|
||||
|
||||
@field_validator("name")
|
||||
@classmethod
|
||||
def validate_name(cls, value: str) -> str:
|
||||
if not (name := value.strip()):
|
||||
raise ValueError("Name is required")
|
||||
return name
|
||||
|
||||
@field_validator("quantity", mode="before")
|
||||
@classmethod
|
||||
def validate_quantity(cls, value: object) -> int:
|
||||
if isinstance(value, bool) or value is None:
|
||||
raise TypeError("Quantity must be an integer")
|
||||
if not isinstance(value, (int, float, str)):
|
||||
raise TypeError("Quantity must be an integer")
|
||||
if isinstance(value, float) and not value.is_integer():
|
||||
raise ValueError("Quantity must be an integer")
|
||||
try:
|
||||
quantity = int(value)
|
||||
except (TypeError, ValueError, OverflowError) as error:
|
||||
raise ValueError("Quantity must be an integer") from error
|
||||
if not 0 <= quantity <= 1_000:
|
||||
raise ValueError("Quantity must be between 0 and 1000")
|
||||
return quantity
|
||||
|
||||
@field_validator("status")
|
||||
@classmethod
|
||||
def validate_status(cls, value: str) -> str:
|
||||
if value not in STATUS_OPTIONS:
|
||||
raise ValueError("Unknown status")
|
||||
return value
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class RowEditorDialog:
|
||||
open_for_row_id: Callable[[int], None]
|
||||
|
||||
|
||||
def _validation_message(error: ValidationError) -> str:
|
||||
return str(error.errors()[0]["msg"])
|
||||
|
||||
|
||||
@binding.bindable_dataclass
|
||||
class EditableRow:
|
||||
id: int
|
||||
@@ -46,6 +97,18 @@ class EditableRow:
|
||||
other_strict=True,
|
||||
)
|
||||
|
||||
def to_draft(self) -> RowEditDraft:
|
||||
return RowEditDraft(name=self.name, quantity=self.quantity, status=self.status)
|
||||
|
||||
def validate_update(self, updates: dict[str, object]) -> RowEditDraft:
|
||||
base_values = self.to_draft().model_dump()
|
||||
return RowEditDraft.model_validate({**base_values, **updates})
|
||||
|
||||
def apply_draft(self, draft: RowEditDraft) -> None:
|
||||
self.name = draft.name
|
||||
self.quantity = draft.quantity
|
||||
self.status = draft.status
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class EditableTableState:
|
||||
@@ -86,30 +149,65 @@ def dataframe_to_state(dataframe: pd.DataFrame) -> EditableTableState:
|
||||
return EditableTableState(rows_by_id)
|
||||
|
||||
|
||||
def normalize_edit(field: str, raw_value: object) -> TableValue:
|
||||
match field:
|
||||
case "name":
|
||||
if not isinstance(raw_value, str) or not (name := raw_value.strip()):
|
||||
raise ValueError("Name is required")
|
||||
return name
|
||||
case "quantity":
|
||||
if isinstance(raw_value, bool) or not isinstance(raw_value, (int, float, str)):
|
||||
raise TypeError("Quantity must be an integer")
|
||||
if isinstance(raw_value, float) and not raw_value.is_integer():
|
||||
raise ValueError("Quantity must be an integer")
|
||||
def render_row_editor_dialog(
|
||||
state: EditableTableState,
|
||||
refresh_table: Callable[[], None],
|
||||
) -> RowEditorDialog:
|
||||
selected_row_id: int | None = None
|
||||
|
||||
with ui.dialog() as edit_dialog, ui.card().classes("w-96"):
|
||||
dialog_heading = ui.label("Edit row")
|
||||
draft_name = ui.input("Name")
|
||||
draft_quantity = ui.number("Quantity", min=0, max=1_000, precision=0)
|
||||
draft_status = ui.select(STATUS_OPTIONS, label="Status")
|
||||
with ui.row().classes("w-full justify-end"):
|
||||
ui.button("Cancel", on_click=edit_dialog.close).props("flat")
|
||||
|
||||
def save_dialog_edit() -> None:
|
||||
nonlocal selected_row_id
|
||||
try:
|
||||
quantity = int(raw_value)
|
||||
except (ValueError, OverflowError) as error:
|
||||
raise ValueError("Quantity must be an integer") from error
|
||||
if not 0 <= quantity <= 1_000:
|
||||
raise ValueError("Quantity must be between 0 and 1000")
|
||||
return quantity
|
||||
case "status":
|
||||
if not isinstance(raw_value, str) or raw_value not in STATUS_OPTIONS:
|
||||
raise ValueError("Unknown status")
|
||||
return raw_value
|
||||
case _:
|
||||
raise ValueError(f"Field {field!r} is not editable")
|
||||
if selected_row_id is None:
|
||||
raise ValueError("Select a row before saving")
|
||||
|
||||
row_state = state.row(selected_row_id)
|
||||
if row_state is None:
|
||||
raise ValueError("This row no longer exists")
|
||||
|
||||
draft = row_state.validate_update(
|
||||
{
|
||||
"name": draft_name.value,
|
||||
"quantity": draft_quantity.value,
|
||||
"status": draft_status.value,
|
||||
},
|
||||
)
|
||||
row_state.apply_draft(draft)
|
||||
row_state.touched = True
|
||||
edit_dialog.close()
|
||||
except ValidationError as error:
|
||||
ui.notify(_validation_message(error), type="negative")
|
||||
except ValueError as error:
|
||||
ui.notify(str(error), type="negative")
|
||||
finally:
|
||||
refresh_table()
|
||||
|
||||
ui.button("Save", icon="save", on_click=save_dialog_edit)
|
||||
|
||||
def open_for_row_id(row_id: int) -> None:
|
||||
nonlocal selected_row_id
|
||||
row_state = state.row(row_id)
|
||||
if row_state is None:
|
||||
ui.notify("This row no longer exists", type="negative")
|
||||
return
|
||||
|
||||
selected_row_id = row_id
|
||||
draft = row_state.to_draft()
|
||||
dialog_heading.set_text(f"Edit row {row_id}")
|
||||
draft_name.set_value(draft.name)
|
||||
draft_quantity.set_value(draft.quantity)
|
||||
draft_status.set_value(draft.status)
|
||||
edit_dialog.open()
|
||||
|
||||
return RowEditorDialog(open_for_row_id=open_for_row_id)
|
||||
|
||||
|
||||
def render_table(dataframe: pd.DataFrame) -> EditableTableState:
|
||||
@@ -118,6 +216,7 @@ def render_table(dataframe: pd.DataFrame) -> EditableTableState:
|
||||
{"name": "name", "label": "Name", "field": "name", "align": "left"},
|
||||
{"name": "quantity", "label": "Quantity", "field": "quantity", "align": "right"},
|
||||
{"name": "status", "label": "Status", "field": "status", "align": "left"},
|
||||
{"name": "actions", "label": "Actions", "field": "id", "align": "center"},
|
||||
]
|
||||
table = ui.table(
|
||||
columns=columns,
|
||||
@@ -127,53 +226,45 @@ def render_table(dataframe: pd.DataFrame) -> EditableTableState:
|
||||
pagination=10,
|
||||
).classes("w-120")
|
||||
|
||||
def apply_edit(event: events.GenericEventArguments) -> None:
|
||||
def refresh_table() -> None:
|
||||
table.update_rows(state.table_rows(), clear_selection=False)
|
||||
|
||||
def apply_inline_edit(event: events.GenericEventArguments) -> None:
|
||||
try:
|
||||
raw_row_id, raw_field, raw_value = event.args
|
||||
row_id = int(raw_row_id)
|
||||
field_name = str(raw_field)
|
||||
if field_name not in EDITABLE_FIELDS:
|
||||
raise ValueError(f"Field {field_name!r} is not editable")
|
||||
|
||||
row_state = state.row(row_id)
|
||||
if row_state is None:
|
||||
raise ValueError("This row no longer exists")
|
||||
|
||||
normalized_value = normalize_edit(field_name, raw_value)
|
||||
setattr(row_state, field_name, normalized_value)
|
||||
draft = row_state.validate_update({field_name: raw_value})
|
||||
row_state.apply_draft(draft)
|
||||
row_state.touched = True
|
||||
except ValidationError as error:
|
||||
ui.notify(_validation_message(error), type="negative")
|
||||
except (TypeError, ValueError) as error:
|
||||
ui.notify(str(error), type="negative")
|
||||
finally:
|
||||
table.update_rows(state.table_rows(), clear_selection=False)
|
||||
refresh_table()
|
||||
|
||||
def show_changes() -> None:
|
||||
changed_rows = state.touched_rows()
|
||||
if not changed_rows:
|
||||
ui.notify("No rows changed")
|
||||
return
|
||||
summary = "; ".join(
|
||||
f"{row.id}: {row.name}, quantity {row.quantity}, status {row.status}" for row in changed_rows
|
||||
)
|
||||
ui.notify(f"Changed rows: {summary}")
|
||||
for row in changed_rows:
|
||||
ui.notify(f"Changed row: {row.id}: {row.name}, quantity {row.quantity}, status {row.status}")
|
||||
|
||||
with table.add_slot("body-cell-name"), table.cell("name"):
|
||||
name_input = ui.input().props(remove="value")
|
||||
name_input.props(':value="props.value" dense borderless debounce=400').on(
|
||||
"update:value",
|
||||
handler=apply_edit,
|
||||
js_handler="(value) => emit(props.row.id, props.col.name, value)",
|
||||
)
|
||||
row_editor = render_row_editor_dialog(state, refresh_table)
|
||||
|
||||
with table.add_slot("body-cell-quantity"), table.cell("quantity"):
|
||||
ui.number(min=0, max=1_000).props(':model-value="props.value" dense borderless debounce=400').on(
|
||||
"update:model-value",
|
||||
handler=apply_edit,
|
||||
js_handler="(value) => emit(props.row.id, props.col.name, value)",
|
||||
)
|
||||
|
||||
with table.add_slot("body-cell-status"), table.cell("status"):
|
||||
ui.select(STATUS_OPTIONS).props(':model-value="props.value" dense borderless options-dense').on(
|
||||
"update:model-value",
|
||||
handler=apply_edit,
|
||||
js_handler="(option) => emit(props.row.id, props.col.name, option.label)",
|
||||
_add_slots(
|
||||
table,
|
||||
apply_inline_edit,
|
||||
row_editor.open_for_row_id,
|
||||
)
|
||||
|
||||
with ui.row().classes("w-120 justify-end"):
|
||||
@@ -182,6 +273,51 @@ def render_table(dataframe: pd.DataFrame) -> EditableTableState:
|
||||
return state
|
||||
|
||||
|
||||
def open_dialog_for_row(open_editor: Callable[[int], None], event: events.GenericEventArguments) -> None:
|
||||
try:
|
||||
row_id = int(event.args)
|
||||
open_editor(row_id)
|
||||
except (TypeError, ValueError):
|
||||
ui.notify("Invalid row key", type="negative")
|
||||
|
||||
|
||||
def _add_slots(
|
||||
table: ui.table,
|
||||
apply_inline_edit: Callable[[events.GenericEventArguments], None],
|
||||
open_editor: Callable[[int], None],
|
||||
):
|
||||
with table.add_slot("body-cell-name"), table.cell("name"):
|
||||
name_input = ui.input().props(remove="value")
|
||||
name_input.props(':value="props.value" dense borderless debounce=400').on(
|
||||
"update:value",
|
||||
handler=apply_inline_edit,
|
||||
js_handler="(value) => emit(props.row.id, props.col.name, value)",
|
||||
)
|
||||
|
||||
with table.add_slot("body-cell-quantity"), table.cell("quantity"):
|
||||
ui.number(min=0, max=1_000).props(':model-value="props.value" dense borderless debounce=400').on(
|
||||
"update:model-value",
|
||||
handler=apply_inline_edit,
|
||||
js_handler="(value) => emit(props.row.id, props.col.name, value)",
|
||||
)
|
||||
|
||||
with table.add_slot("body-cell-status"), table.cell("status"):
|
||||
ui.select(STATUS_OPTIONS).props(':model-value="props.value" dense borderless options-dense').on(
|
||||
"update:model-value",
|
||||
handler=apply_inline_edit,
|
||||
js_handler="(option) => emit(props.row.id, props.col.name, option.label)",
|
||||
)
|
||||
|
||||
with table.add_slot("body-cell-actions"), table.cell("actions"):
|
||||
edit_button = ui.button(icon="edit")
|
||||
edit_button.props('flat round dense color=primary aria-label="Edit row"')
|
||||
edit_button.tooltip("Edit this row").on(
|
||||
"click",
|
||||
handler=lambda event: open_dialog_for_row(open_editor, event),
|
||||
js_handler="() => emit(props.row.id)",
|
||||
)
|
||||
|
||||
|
||||
if __name__ in {"__main__", "__mp_main__"}:
|
||||
items = pd.DataFrame(
|
||||
[
|
||||
|
||||
+210
@@ -0,0 +1,210 @@
|
||||
#!/usr/bin/env -S uv run --script
|
||||
# /// script
|
||||
# dependencies = [
|
||||
# "nicegui==3.16.0",
|
||||
# ]
|
||||
# ///
|
||||
|
||||
"""Demonstrate URL-backed tabs with persistent parameterized-route state."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Callable
|
||||
from urllib.parse import urlsplit
|
||||
|
||||
from nicegui import binding
|
||||
from nicegui import events
|
||||
from nicegui import ui
|
||||
from nicegui.elements.tabs import Tab
|
||||
from nicegui.elements.tabs import TabPanel
|
||||
|
||||
type PageBuilder = Callable[..., None]
|
||||
|
||||
DEFAULT_REPORT_PATH = "/reports/a"
|
||||
REPORTS_TAB = "reports"
|
||||
TAB_ROUTES = frozenset({"/", "/projects", "/settings"})
|
||||
|
||||
|
||||
def page_heading(title: str, description: str) -> None:
|
||||
"""Render a shared heading for sub-page content."""
|
||||
with ui.column().classes("w-full gap-1"):
|
||||
ui.label(title).classes("text-3xl font-semibold text-stone-900")
|
||||
ui.label(description).classes("text-base text-stone-600")
|
||||
|
||||
|
||||
def overview_page() -> None:
|
||||
"""Render the overview sub-page."""
|
||||
with ui.column().classes("w-full max-w-6xl mx-auto gap-6 px-4 py-8"):
|
||||
page_heading("Overview", "A quick read on the workspace today.")
|
||||
|
||||
metrics = (
|
||||
("Active projects", "8", "folder_open", "primary"),
|
||||
("Tasks completed", "24", "task_alt", "positive"),
|
||||
("Needs attention", "3", "error_outline", "warning"),
|
||||
)
|
||||
with ui.grid().classes("w-full grid-cols-1 gap-4 md:grid-cols-3"):
|
||||
for label, value, icon, color in metrics:
|
||||
with ui.card().classes("w-full p-5 gap-3"):
|
||||
with ui.row().classes("w-full items-center justify-between"):
|
||||
ui.label(label).classes("text-sm font-medium text-stone-600")
|
||||
ui.icon(icon, color=color).classes("text-2xl")
|
||||
ui.label(value).classes("text-3xl font-semibold text-stone-900")
|
||||
|
||||
|
||||
def projects_page() -> None:
|
||||
"""Render the projects sub-page."""
|
||||
with ui.column().classes("w-full max-w-6xl mx-auto gap-6 px-4 py-8"):
|
||||
page_heading("Projects", "Each route builds its own content inside the shared shell.")
|
||||
|
||||
with ui.list().props("bordered separator").classes("w-full bg-white rounded"):
|
||||
for name, status, color in (
|
||||
("Client portal", "On track", "positive"),
|
||||
("Mobile refresh", "In review", "primary"),
|
||||
("Data migration", "Blocked", "negative"),
|
||||
):
|
||||
with ui.item():
|
||||
with ui.item_section().props("avatar"):
|
||||
ui.icon("folder", color=color)
|
||||
with ui.item_section():
|
||||
ui.item_label(name)
|
||||
ui.item_label(status).props("caption")
|
||||
with ui.item_section().props("side"):
|
||||
ui.badge(status, color=color)
|
||||
|
||||
|
||||
def report_page(state: NavigationState) -> None:
|
||||
"""Render report content bound to the active route parameter."""
|
||||
with ui.column().classes("w-full max-w-6xl mx-auto gap-6 px-4 py-8"):
|
||||
with ui.column().classes("w-full gap-1"):
|
||||
ui.label().bind_text_from(
|
||||
state,
|
||||
"active_report_path",
|
||||
backward=lambda path: f"Report {report_id_from_path(path).upper()}",
|
||||
).classes("text-3xl font-semibold text-stone-900")
|
||||
ui.label("The report ID is injected from the URL path.").classes("text-base text-stone-600")
|
||||
|
||||
with ui.card().classes("w-full max-w-2xl p-5 gap-4"):
|
||||
ui.label("Parameterized route").classes("text-xl font-semibold text-stone-900")
|
||||
ui.label().bind_text_from(
|
||||
state,
|
||||
"active_report_path",
|
||||
backward=lambda path: f"Loaded {path}",
|
||||
).classes("text-stone-600")
|
||||
with ui.row().classes("gap-2"):
|
||||
ui.button("Report A", on_click=lambda: ui.navigate.to("/reports/a")).props("outline")
|
||||
ui.button("Report B", on_click=lambda: ui.navigate.to("/reports/b")).props("outline")
|
||||
|
||||
|
||||
def settings_page() -> None:
|
||||
"""Render the settings sub-page."""
|
||||
with ui.column().classes("w-full max-w-6xl mx-auto gap-6 px-4 py-8"):
|
||||
page_heading("Settings", "Controls here are recreated when this sub-page is opened.")
|
||||
|
||||
with ui.card().classes("w-full max-w-2xl p-5 gap-4"):
|
||||
ui.label("Notifications").classes("text-xl font-semibold text-stone-900")
|
||||
ui.switch("Weekly summary", value=True)
|
||||
ui.switch("Project status changes", value=True)
|
||||
ui.switch("Product announcements", value=False)
|
||||
|
||||
|
||||
def normalize_route(path: str) -> str:
|
||||
"""Extract and normalize the path portion of a route."""
|
||||
return urlsplit(path).path.rstrip("/") or "/"
|
||||
|
||||
|
||||
def tab_name_for_route(route: str) -> str:
|
||||
"""Return the tab name associated with a concrete route."""
|
||||
if route.startswith("/reports/"):
|
||||
return REPORTS_TAB
|
||||
return route if route in TAB_ROUTES else "/"
|
||||
|
||||
|
||||
@binding.bindable_dataclass
|
||||
class NavigationState:
|
||||
"""Store client-local navigation state for parameterized tabs."""
|
||||
|
||||
active_report_path: str = DEFAULT_REPORT_PATH
|
||||
|
||||
|
||||
type TabHandler = events.ValueChangeEventArguments[str | Tab | TabPanel | None]
|
||||
|
||||
|
||||
def report_id_from_path(path: str) -> str:
|
||||
"""Extract the report ID from a normalized report route."""
|
||||
return path.rsplit("/", maxsplit=1)[-1]
|
||||
|
||||
|
||||
def create_tabs(state: NavigationState, initial_route: str) -> ui.tabs:
|
||||
"""Create route-aware tabs and retain the last selected report."""
|
||||
|
||||
def navigate(event: TabHandler) -> None:
|
||||
"""Navigate to the route represented by the selected tab."""
|
||||
match event.value:
|
||||
case str(tabname):
|
||||
destination = state.active_report_path if tabname == REPORTS_TAB else tabname
|
||||
ui.navigate.to(destination)
|
||||
case _:
|
||||
return
|
||||
|
||||
with ui.column().classes("mx-auto"), ui.tabs() as tabs:
|
||||
ui.tab("/", label="Overview", icon="space_dashboard")
|
||||
ui.tab("/projects", label="Projects", icon="folder_open")
|
||||
ui.tab(REPORTS_TAB, label="Reports", icon="summarize")
|
||||
ui.tab("/settings", label="Settings", icon="settings")
|
||||
|
||||
tabs.set_value(tab_name_for_route(initial_route))
|
||||
tabs.on_value_change(navigate)
|
||||
|
||||
return tabs
|
||||
|
||||
|
||||
def render_tab_panels(tabs: ui.tabs, state: NavigationState, active_tab: str) -> None:
|
||||
"""Render all tabbed page content inside a tab panels container."""
|
||||
with ui.tab_panels(tabs, value=active_tab, animated=True).classes("w-full"):
|
||||
with ui.tab_panel("/"):
|
||||
overview_page()
|
||||
with ui.tab_panel("/projects"):
|
||||
projects_page()
|
||||
with ui.tab_panel(REPORTS_TAB):
|
||||
report_page(state)
|
||||
with ui.tab_panel("/settings"):
|
||||
settings_page()
|
||||
|
||||
|
||||
def root() -> None:
|
||||
"""Build the persistent application shell and sub-page container."""
|
||||
initial_route = normalize_route(ui.context.client.sub_pages_router.current_path)
|
||||
state = NavigationState()
|
||||
if tab_name_for_route(initial_route) == REPORTS_TAB:
|
||||
state.active_report_path = initial_route
|
||||
|
||||
with ui.header(elevated=True).classes("py-0 items-center"):
|
||||
tabs = create_tabs(state, initial_route)
|
||||
ui.button(icon="settings").classes("text-white").props("round flat").tooltip("Settings")
|
||||
|
||||
render_tab_panels(tabs, state, tab_name_for_route(initial_route))
|
||||
|
||||
def route_overview() -> None:
|
||||
tabs.set_value("/")
|
||||
|
||||
def route_projects() -> None:
|
||||
tabs.set_value("/projects")
|
||||
|
||||
def route_reports(report_id: str) -> None:
|
||||
state.active_report_path = f"/reports/{report_id}"
|
||||
tabs.set_value(REPORTS_TAB)
|
||||
|
||||
def route_settings() -> None:
|
||||
tabs.set_value("/settings")
|
||||
|
||||
routes: dict[str, PageBuilder] = {
|
||||
"/": route_overview,
|
||||
"/projects": route_projects,
|
||||
"/reports/{report_id}": route_reports,
|
||||
"/settings": route_settings,
|
||||
}
|
||||
ui.sub_pages(routes).classes("hidden")
|
||||
|
||||
|
||||
if __name__ in {"__main__", "__mp_main__"}:
|
||||
ui.run(root, title="Northstar", port=8888, reload=True)
|
||||
@@ -0,0 +1,253 @@
|
||||
#!/usr/bin/env -S uv run --script
|
||||
# /// script
|
||||
# dependencies = [
|
||||
# "nicegui==3.16.0",
|
||||
# ]
|
||||
# ///
|
||||
|
||||
from nicegui import events
|
||||
from nicegui import ui
|
||||
|
||||
type TableValue = str | int | float
|
||||
type TableRow = dict[str, TableValue]
|
||||
|
||||
STATUS_COLORS = {
|
||||
"Ready": "positive",
|
||||
"Low": "warning",
|
||||
"Backorder": "negative",
|
||||
}
|
||||
|
||||
COLUMNS = [
|
||||
{
|
||||
"name": "actions",
|
||||
"label": "Actions",
|
||||
"required": True,
|
||||
"align": "center",
|
||||
},
|
||||
{
|
||||
"name": "name",
|
||||
"label": "Product",
|
||||
"field": "name",
|
||||
"required": True,
|
||||
"sortable": True,
|
||||
"align": "left",
|
||||
"headerClasses": "bg-grey-2 text-grey-9 font-bold",
|
||||
"classes": "font-medium",
|
||||
"headerStyle": "width: 40%; min-width: 12rem",
|
||||
"style": "width: 40%; min-width: 12rem",
|
||||
},
|
||||
{
|
||||
"name": "category",
|
||||
"label": "Category",
|
||||
"field": "category",
|
||||
"sortable": True,
|
||||
"align": "left",
|
||||
"headerStyle": "width: 9rem",
|
||||
"style": "width: 9rem",
|
||||
},
|
||||
{
|
||||
"name": "stock",
|
||||
"label": "In stock",
|
||||
"field": "stock",
|
||||
"sortable": True,
|
||||
"align": "right",
|
||||
"headerStyle": "width: 7rem",
|
||||
"style": "width: 7rem",
|
||||
":classes": "row => row.stock < 10 ? 'text-negative font-bold' : ''",
|
||||
":format": "value => value == null ? '' : `${value} units`",
|
||||
},
|
||||
{
|
||||
"name": "price",
|
||||
"label": "Unit price",
|
||||
"field": "price",
|
||||
"sortable": True,
|
||||
"align": "right",
|
||||
"headerStyle": "width: 8rem",
|
||||
"style": "width: 8rem",
|
||||
":format": "value => value == null ? '' : `$${value.toFixed(2)}`",
|
||||
},
|
||||
{
|
||||
"name": "status",
|
||||
"label": "Status",
|
||||
"field": "status",
|
||||
"sortable": True,
|
||||
"align": "center",
|
||||
"headerStyle": "width: 8rem",
|
||||
"style": "width: 8rem",
|
||||
"colorByValue": STATUS_COLORS,
|
||||
},
|
||||
{
|
||||
"name": "updated_at",
|
||||
"label": "Updated",
|
||||
"field": "updated_at",
|
||||
"sortable": True,
|
||||
"align": "left",
|
||||
"headerStyle": "width: 13rem",
|
||||
"style": "width: 13rem",
|
||||
":sort": "(left, right) => Date.parse(left) - Date.parse(right)",
|
||||
":format": """(() => {
|
||||
const formatter = new Intl.DateTimeFormat('en-US', {
|
||||
dateStyle: 'medium',
|
||||
timeStyle: 'short',
|
||||
timeZone: 'UTC',
|
||||
});
|
||||
return value => {
|
||||
if (!value) return '';
|
||||
const timestamp = Date.parse(value);
|
||||
return Number.isNaN(timestamp) ? 'Invalid date' : formatter.format(timestamp);
|
||||
};
|
||||
})()""",
|
||||
},
|
||||
]
|
||||
|
||||
ROWS: list[TableRow] = [
|
||||
{
|
||||
"id": 101,
|
||||
"name": "Desk lamp",
|
||||
"category": "Lighting",
|
||||
"stock": 7,
|
||||
"price": 42.5,
|
||||
"status": "Low",
|
||||
"updated_at": "2026-08-31T16:20:00Z",
|
||||
},
|
||||
{
|
||||
"id": 102,
|
||||
"name": "Task chair",
|
||||
"category": "Seating",
|
||||
"stock": 18,
|
||||
"price": 289.0,
|
||||
"status": "Ready",
|
||||
"updated_at": "2026-09-01T08:45:00Z",
|
||||
},
|
||||
{
|
||||
"id": 103,
|
||||
"name": "Monitor arm",
|
||||
"category": "Hardware",
|
||||
"stock": 0,
|
||||
"price": 119.95,
|
||||
"status": "Backorder",
|
||||
"updated_at": "2026-08-29T11:05:00Z",
|
||||
},
|
||||
{
|
||||
"id": 104,
|
||||
"name": "Cable tray",
|
||||
"category": "Hardware",
|
||||
"stock": 34,
|
||||
"price": 31.25,
|
||||
"status": "Ready",
|
||||
"updated_at": "2026-09-01T14:30:00Z",
|
||||
},
|
||||
{
|
||||
"id": 105,
|
||||
"name": "Side table",
|
||||
"category": "Furniture",
|
||||
"stock": 9,
|
||||
"price": 164.5,
|
||||
"status": "Low",
|
||||
"updated_at": "2026-08-30T19:15:00Z",
|
||||
},
|
||||
{
|
||||
"id": 106,
|
||||
"name": "Floor light",
|
||||
"category": "Lighting",
|
||||
"stock": 15,
|
||||
"price": 98.0,
|
||||
"status": "Ready",
|
||||
"updated_at": "2026-09-01T10:10:00Z",
|
||||
},
|
||||
]
|
||||
|
||||
|
||||
def render_table() -> ui.table:
|
||||
table = ui.table(
|
||||
columns=COLUMNS,
|
||||
column_defaults={"headerClasses": "text-grey-8"},
|
||||
rows=ROWS,
|
||||
row_key="id",
|
||||
pagination={
|
||||
"sortBy": "stock",
|
||||
"descending": True,
|
||||
"rowsPerPage": 5,
|
||||
},
|
||||
).classes("w-full max-w-5xl")
|
||||
|
||||
(
|
||||
table.props(
|
||||
# Surface and cell layout.
|
||||
"flat bordered separator=horizontal wrap-cells"
|
||||
)
|
||||
.props(
|
||||
# Local sorting and page-size choices; zero means "all rows".
|
||||
'binary-state-sort :rows-per-page-options="[5, 10, 0]"'
|
||||
)
|
||||
.props(
|
||||
# Compact cells only below Quasar's medium breakpoint.
|
||||
':dense="Quasar.Screen.lt.md"'
|
||||
)
|
||||
.props(
|
||||
# Distinguish an empty dataset from a filter with no matches.
|
||||
'no-data-label="No inventory items" no-results-label="No matching inventory items"'
|
||||
)
|
||||
)
|
||||
|
||||
with table.add_slot("top-left"), ui.row(align_items="center").classes("gap-2"):
|
||||
ui.icon("inventory_2", size="sm", color="primary")
|
||||
ui.label("Inventory").classes("text-xl font-medium")
|
||||
ui.badge(str(len(ROWS)), color="grey-3", text_color="grey-9")
|
||||
|
||||
with table.add_slot("top-right"):
|
||||
ui.input(placeholder="Search inventory").props("dense outlined clearable debounce=250").bind_value_to(
|
||||
table,
|
||||
"filter",
|
||||
)
|
||||
|
||||
with table.add_slot("body-cell-status"), table.cell("status"):
|
||||
ui.badge(outline=True).props(':label="props.value" :color="props.col.colorByValue[props.value] ?? \'grey\'"')
|
||||
|
||||
def open_product(event: events.GenericEventArguments) -> None:
|
||||
product = next((row for row in table.rows if row[table.row_key] == event.args), None)
|
||||
if product is None:
|
||||
ui.notify("Product no longer exists", type="negative")
|
||||
return
|
||||
ui.notify(f"Opening {product['name']}")
|
||||
|
||||
with (
|
||||
table.add_slot("body-cell-actions"),
|
||||
table.cell("actions"),
|
||||
ui.button(icon="open_in_new")
|
||||
.props("round flat size='sm'")
|
||||
.on(
|
||||
"click.stop",
|
||||
handler=open_product,
|
||||
js_handler="() => emit(props.key)",
|
||||
),
|
||||
):
|
||||
ui.tooltip("Open product")
|
||||
|
||||
with table.add_slot("no-data"), ui.row(align_items="center").classes("w-full justify-center gap-2 p-6 text-grey-7"):
|
||||
ui.icon("inventory_2", size="2em").props(":name=\"props.filter ? 'filter_alt_off' : 'inventory_2'\"")
|
||||
ui.element("span").props(':textContent="props.message"')
|
||||
|
||||
optional_columns = [column for column in table.columns if not column.get("required")]
|
||||
|
||||
def set_visible_columns(names: list[str]) -> None:
|
||||
table.props["visible-columns"] = names
|
||||
table.update()
|
||||
|
||||
ui.select(
|
||||
{column["name"]: column["label"] for column in optional_columns},
|
||||
value=[column["name"] for column in optional_columns],
|
||||
label="Visible columns",
|
||||
multiple=True,
|
||||
clearable=True,
|
||||
on_change=lambda event: set_visible_columns(event.value),
|
||||
).props("outlined dense options-dense").classes("w-64")
|
||||
|
||||
return table
|
||||
|
||||
|
||||
if __name__ in {"__main__", "__mp_main__"}:
|
||||
with ui.column(align_items="center").classes("w-full gap-4 p-4"):
|
||||
render_table()
|
||||
|
||||
ui.run(port=8888, reload=True)
|
||||
@@ -70,12 +70,104 @@ Avoid imports from services back into API or UI modules.
|
||||
|
||||
## Page And Component Ownership
|
||||
|
||||
Page modules compose routes from presentation components and service calls. They should not own domain rules, persistence, or long-running synchronous work.
|
||||
Page modules should be a thin route-level composition layer. A page resolves route inputs and page-scoped dependencies, establishes the page shell, composes reusable components, and wires only the interactions that cross component boundaries. It should not contain a component's internal element tree, field bindings, refresh logic, domain rules, persistence, or long-running synchronous work.
|
||||
|
||||
Extract a presentation pattern to `ui/components/` when it appears on two or more pages or owns a meaningful interaction boundary. Keep one-off route composition in the page module. Reusable components should accept data and event callbacks instead of importing page state or business services implicitly.
|
||||
Extract a presentation pattern to `ui/components/` when it appears on two or more pages or owns a meaningful state or interaction boundary. Reusable components should accept initial data, use-case functions, and event callbacks explicitly instead of importing page state or business services implicitly.
|
||||
|
||||
For page composition, responsive layout, Quasar props, and CSS customization, load [styling and customization](./styling-and-customization.md).
|
||||
|
||||
## Reusable Component Contract
|
||||
|
||||
In this architecture, a "component" is an application-level composition pattern, not necessarily a custom Vue component or a subclass of NiceGUI `Element`. Its usual shape is:
|
||||
|
||||
1. A typed dataclass represents the component's public handle and local UI state.
|
||||
2. A render or factory function creates one component instance, builds its element subtree, and binds elements to that instance.
|
||||
3. The function returns the instance so its caller can read or change intentional state, invoke public actions, or coordinate it with another component.
|
||||
4. Internal elements, event handlers, validation feedback, and refreshable regions remain private to the component unless an imperative element handle is intentionally part of its API.
|
||||
|
||||
Use [`binding.bindable_dataclass`](./binding-dataclasses.md) for fields that drive or receive element properties. Plain `@dataclass` is sufficient when the returned object only groups element handles or callbacks and does not need immediate field propagation. Use `bindable_fields` when the dataclass also stores injected dependencies or other fields that should not participate in NiceGUI's binding graph.
|
||||
|
||||
```python
|
||||
from collections.abc import Awaitable, Callable
|
||||
from dataclasses import field
|
||||
|
||||
from nicegui import binding, ui
|
||||
|
||||
|
||||
Search = Callable[[str], Awaitable[list[str]]]
|
||||
|
||||
|
||||
@binding.bindable_dataclass(bindable_fields={"query", "busy", "items"})
|
||||
class SearchPanel:
|
||||
search: Search = field(repr=False)
|
||||
query: str = ""
|
||||
busy: bool = False
|
||||
items: list[str] = field(default_factory=list)
|
||||
|
||||
@ui.refreshable_method
|
||||
def render_results(self) -> None:
|
||||
if not self.items:
|
||||
ui.label("No results")
|
||||
for item in self.items:
|
||||
ui.label(item)
|
||||
|
||||
async def submit(self) -> None:
|
||||
if self.busy:
|
||||
return
|
||||
self.busy = True
|
||||
try:
|
||||
self.items = await self.search(self.query)
|
||||
await self.render_results.refresh()
|
||||
finally:
|
||||
self.busy = False
|
||||
|
||||
|
||||
def render_search_panel(search: Search) -> SearchPanel:
|
||||
panel = SearchPanel(search=search)
|
||||
with ui.column().classes("w-full gap-3"):
|
||||
ui.input("Search").bind_value(panel, "query")
|
||||
ui.button("Search", on_click=panel.submit).bind_enabled_from(
|
||||
panel,
|
||||
"busy",
|
||||
backward=lambda busy: not busy,
|
||||
)
|
||||
ui.label().bind_text_from(
|
||||
panel,
|
||||
"items",
|
||||
backward=lambda items: f"{len(items)} results",
|
||||
)
|
||||
panel.render_results()
|
||||
return panel
|
||||
```
|
||||
|
||||
The returned dataclass is the component API. Its bindable fields synchronize stable element properties, while `render_results()` owns a bounded region whose child structure changes with `items`. The injected `search` callable preserves dependency direction: the component can invoke a use case without locating a service globally.
|
||||
|
||||
[`@ui.refreshable_method`](https://nicegui.io/documentation/refreshable) is the instance-oriented refresh surface for this pattern. NiceGUI records refresh targets by method instance, allowing each page-created component object to refresh independently. Detailed target, argument, async, and lifecycle behavior is documented under [refreshable component regions](./interaction-patterns.md#refreshable-component-regions).
|
||||
|
||||
### Thin Page Example
|
||||
|
||||
```python
|
||||
from nicegui import ui
|
||||
|
||||
from app.services.catalog import search_catalog
|
||||
from app.ui.components.search_panel import render_search_panel
|
||||
|
||||
|
||||
@ui.page("/catalog")
|
||||
def catalog_page() -> None:
|
||||
with ui.column().classes("mx-auto w-full max-w-5xl gap-6"):
|
||||
ui.label("Catalog").classes("text-2xl font-semibold")
|
||||
render_search_panel(search_catalog)
|
||||
```
|
||||
|
||||
The page owns the route and composition. The component owns its controls, binding graph, feedback state, and structural refresh. The service owns search rules and data access. If two component handles must coordinate, keep the page wiring declarative, such as subscribing one component's public event to another component's public refresh action; move orchestration with domain meaning into a service.
|
||||
|
||||
### Component Lifetime
|
||||
|
||||
Create component state during each page build unless sharing is deliberate. A module-global component dataclass can leak UI state across clients, and a module-global `@ui.refreshable` function can refresh every recorded target. Do not retain returned handles beyond their owning client without an explicit cleanup and stale-client policy.
|
||||
|
||||
Bindings to elements are removed with NiceGUI's element lifecycle. Refreshing a region deletes and recreates the elements inside that region, so external code should retain the component handle rather than private child element references. Component-owned subscriptions, timers, and background tasks must follow the client deletion rules in [interaction mechanics](./interaction-patterns.md#page-and-client-lifetime).
|
||||
|
||||
## Optional Persistence
|
||||
|
||||
Use only when the product requires durable data.
|
||||
|
||||
@@ -51,6 +51,24 @@ class SearchState:
|
||||
|
||||
A bound field omitted from `bindable_fields` still works, but NiceGUI must treat it as an active link and poll it for changes.
|
||||
|
||||
## Bindable Dataclasses As Component Handles
|
||||
|
||||
A reusable NiceGUI component can expose a bindable dataclass as its typed public handle. The component's render function creates the dataclass instance, builds the element subtree, establishes bindings against that instance, and returns it to the page. This keeps the page at the composition level while the component owns its field wiring and internal elements. See the complete [reusable component contract](./architecture.md#reusable-component-contract).
|
||||
|
||||
Choose binding direction according to what the public field represents:
|
||||
|
||||
| Component field | Typical element relationship | Binding surface |
|
||||
| --- | --- | --- |
|
||||
| editable value such as `query` | control and component share the value | `element.bind_value(handle, "query")` |
|
||||
| rendered status such as `busy` or `count` | component state drives text, visibility, or enabled state | `bind_*_from` with a pure transform when needed |
|
||||
| browser proposal requiring validation | event handler validates before assignment | explicit callback, then assign the accepted bindable field |
|
||||
| collection controlling child count or layout | component state is read while rebuilding a bounded subtree | `@ui.refreshable_method`, not a binding to the child list itself |
|
||||
| injected service or callback | component implementation dependency | ordinary dataclass field omitted from `bindable_fields` |
|
||||
|
||||
The returned handle should expose intentional component state and actions, not every child element. Bindable fields are effective for stable element properties because assignments propagate immediately. They do not create or delete elements when collection structure changes; a component-owned refreshable method should rebuild that region after the authoritative field is replaced. The target and instance behavior is defined under [refreshable component regions](./interaction-patterns.md#refreshable-component-regions).
|
||||
|
||||
Create one handle during each page build unless shared state is deliberate. A module-global bindable component model propagates across clients that bind to it, just as a module-level refreshable function can own targets from multiple clients.
|
||||
|
||||
## Binding Graph And Propagation
|
||||
|
||||
NiceGUI stores bindings as directed edges from one object attribute to another. A two-way binding is two one-way edges with transforms in opposite directions.
|
||||
|
||||
@@ -235,6 +235,14 @@ viewport.on("scroll.passive", handle_scroll, throttle=0.1)
|
||||
|
||||
NiceGUI separates listener options such as `capture`, `once`, and `passive`, event modifiers such as `stop`, `prevent`, and `self`, and key filters such as `enter`. The tagged [`EventListener.to_dict()` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/event_listener.py) performs that classification before the frontend applies Vue's `withModifiers()` and `withKeys()` helpers. `throttle`, `leading_events`, and `trailing_events` regulate messages sent to Python; they do not throttle a client-only `js_handler` that never calls `emit`.
|
||||
|
||||
### Custom Vue Components
|
||||
|
||||
When NiceGUI's wrappers and the documented Quasar extension points cannot express a component, subclass `ui.element` and pair it with a Vue component. Start from NiceGUI's [custom Vue component example](https://github.com/zauberzeug/nicegui/tree/main/examples/custom_vue_component), keeping Python responsible for the server-facing state and event contract.
|
||||
|
||||
For a component with npm dependencies, bundle the frontend module and pass its ESM module name and bundled file path through the `esm` parameter on the Python element subclass. NiceGUI adds that module to the page import map. The [signature pad example](https://github.com/zauberzeug/nicegui/tree/main/examples/signature_pad) and [node module integration example](https://github.com/zauberzeug/nicegui/tree/main/examples/node_module_integration) demonstrate the package and bundling boundary.
|
||||
|
||||
Treat the generated JavaScript and CSS as package data in executable builds. PyInstaller or Nuitka configuration must include those assets, and the packaged artifact must be checked for successful module loading rather than only for process startup. Do not introduce a custom Vue component merely to avoid a supported NiceGUI constructor, Quasar prop, event, slot, or public method.
|
||||
|
||||
## Framework Boundary Model
|
||||
|
||||
A NiceGUI component is not a Python-rendered HTML fragment. Customization passes through several owners:
|
||||
@@ -302,6 +310,14 @@ NiceGUI creates a default slot for every element. Entering an element as a conte
|
||||
|
||||
These mechanics are defined by the tagged [`Element.add_slot()` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/element.py), the [`Slot` context manager](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/slot.py), and NiceGUI's [context-managed scoped-slot examples](https://github.com/zauberzeug/nicegui/blob/v3.16.0/website/documentation/content/table_documentation.py).
|
||||
|
||||
### Prefer Python-Owned Composition
|
||||
|
||||
Use NiceGUI context managers and `ui.*` elements for slot structure whenever they can represent the required element tree. Keep values, mappings, validation, permissions, event handling, and authoritative state transitions in Python. This preserves element identity, typed wrapper APIs, lifecycle cleanup, test visibility, and the normal NiceGUI update path.
|
||||
|
||||
Use the narrowest browser-side expression for state that exists only while Quasar renders a scoped slot. A dynamic prop such as `:label="props.value"` may project that value into a NiceGUI element without moving the surrounding structure or business rules into JavaScript. When Python needs a browser-owned value, emit the smallest serializable proposal to a Python handler and validate it there.
|
||||
|
||||
Escalate to `add_slot(name, template)` only when the slot contract requires client-side structure that context-managed NiceGUI elements cannot preserve, such as a browser-side `v-for`, a variable number of sibling roots, or Vue's object form of `v-bind` for a Quasar interaction bundle. Keep raw templates small, use documented scoped props, and do not duplicate authoritative application logic in JavaScript.
|
||||
|
||||
### Context-Managed NiceGUI Elements
|
||||
|
||||
Ordinary NiceGUI elements can populate slot content:
|
||||
@@ -313,7 +329,7 @@ with name_input.add_slot("prepend"):
|
||||
ui.icon("person")
|
||||
```
|
||||
|
||||
Nested context managers express the component hierarchy while preserving NiceGUI element identity, event registration, updates, deletion, and test visibility. The `add_slot(name, template)` form accepts a raw Vue template for client-side structures such as a `v-for` that creates a variable number of sibling elements.
|
||||
Nested context managers express the component hierarchy while preserving NiceGUI element identity, event registration, updates, deletion, and test visibility.
|
||||
|
||||
### Scoped Props On The Client
|
||||
|
||||
|
||||
@@ -0,0 +1,194 @@
|
||||
# NiceGUI Configuration And Deployment
|
||||
|
||||
Use this reference when a NiceGUI task concerns `ui.run(...)` settings, runtime URLs, native windows, environment variables, server hosting, executable packaging, or NiceGUI On Air. For startup ownership, app factories, `ui.run_with(...)`, lifespan, reload, and workers, load [FastAPI and Uvicorn startup](./fastapi-uvicorn-startup.md).
|
||||
|
||||
The public surfaces below follow NiceGUI's current [configuration and deployment documentation](https://nicegui.io/documentation/section_configuration_deployment). Inspect the target project's pinned NiceGUI version before relying on a recently added option or native-mode behavior.
|
||||
|
||||
## Configure The Owning Runtime
|
||||
|
||||
Choose the process owner before setting runtime options:
|
||||
|
||||
| Deployment shape | Owning surface | Where configuration belongs |
|
||||
| --- | --- | --- |
|
||||
| NiceGUI is the application and starts its server | `ui.run(...)` | NiceGUI arguments plus additional Uvicorn keyword arguments |
|
||||
| A parent FastAPI app owns startup | `ui.run_with(parent_app, ...)` and the external ASGI server | NiceGUI composition options in `ui.run_with`; socket, TLS, reload, and worker options in Uvicorn or the process manager |
|
||||
| Desktop application | `ui.run(native=True, ...)` | NiceGUI runtime options and `app.native` configuration |
|
||||
| Packaged browser or desktop executable | `ui.run(reload=False, ...)` | import-safe page registration, packaging flags, and multiprocessing setup |
|
||||
|
||||
Do not split ownership by calling `ui.run()` and a separate server launcher for the same app. The exact composition patterns and worker constraints are in [FastAPI and Uvicorn startup](./fastapi-uvicorn-startup.md).
|
||||
|
||||
## Select `ui.run` Options Deliberately
|
||||
|
||||
[`ui.run(...)`](https://nicegui.io/documentation/run) accepts several groups of settings:
|
||||
|
||||
| Concern | Representative options | Decision rule |
|
||||
| --- | --- | --- |
|
||||
| route and metadata | `root`, `title`, `viewport`, `favicon`, `language`, `dark`, `markdown` | Use a root callable or decorated pages; override metadata per page when it is route-specific. |
|
||||
| network and launch | `host`, `port`, `show`, `on_air` | Bind and expose only the interfaces required by the deployment; treat On Air as a separate remote-access choice. |
|
||||
| client recovery | `reconnect_timeout`, `message_history_length` | Tune together from observed disconnect duration and replay volume; replay is not durable job delivery. |
|
||||
| binding work | `binding_refresh_interval` | Reduce active links before lowering the interval; use `None` only when no polling-based links need updates. |
|
||||
| static delivery | `cache_control_directives`, `gzip_middleware_factory` | Preserve deliberate cache lifetimes and compression behavior; disabling gzip or changing immutable caching is an operational decision. |
|
||||
| development | `reload`, `uvicorn_reload_dirs`, `uvicorn_reload_includes`, `uvicorn_reload_excludes`, `uvicorn_logging_level` | Keep reload local to development and restart fully when changing options that the reloader process owns. |
|
||||
| frontend runtime | `tailwind`, `unocss`, `prod_js` | Verify class compatibility before switching CSS engines; use production Vue and Quasar assets in deployed apps. |
|
||||
| API visibility | `fastapi_docs`, `endpoint_documentation` | Expose only the OpenAPI surfaces the application intends to publish. |
|
||||
| browser storage | `storage_secret`, `session_middleware_kwargs` | A secret is required for `ui.storage.user` and `ui.storage.browser`; load it from a secret source and configure cookie policy for the deployment. |
|
||||
| native window | `native`, `window_size`, `fullscreen`, `frameless` | Use only for a desktop app with a supported browser engine. |
|
||||
|
||||
Additional keyword arguments are forwarded to `uvicorn.run`. Most `ui.run` option changes require stopping and fully restarting the process; do not assume development auto-reload applies them.
|
||||
|
||||
## Read Runtime URLs After Binding
|
||||
|
||||
[`app.urls`](https://nicegui.io/documentation/section_configuration_deployment#urls) contains the URLs on which the running app is available. The server has not bound its sockets during `app.on_startup`, so the collection is not available there. Read it in a page function or subscribe to `app.urls.on_change` when another application component needs the final addresses.
|
||||
|
||||
```python
|
||||
from nicegui import app, ui
|
||||
|
||||
|
||||
@ui.page('/')
|
||||
def home() -> None:
|
||||
for url in app.urls:
|
||||
ui.link(url, target=url)
|
||||
|
||||
|
||||
ui.run()
|
||||
```
|
||||
|
||||
Do not derive a public URL solely from the listening host and port when a reverse proxy, container port mapping, or tunnel owns the external address.
|
||||
|
||||
## Configure Environment-Controlled Facilities
|
||||
|
||||
NiceGUI recognizes these framework environment variables:
|
||||
|
||||
| Variable | Default | Effect |
|
||||
| --- | --- | --- |
|
||||
| `MATPLOTLIB` | enabled | Set to `false` to skip the potentially costly Matplotlib import; `ui.pyplot` and `ui.line_plot` then remain unavailable. |
|
||||
| `NICEGUI_STORAGE_PATH` | `.nicegui` in the working directory | Changes the local storage-file directory. |
|
||||
| `NICEGUI_REDIS_URL` | no Redis backend | Selects Redis for shared persistent storage. |
|
||||
| `NICEGUI_REDIS_KEY_PREFIX` | `nicegui:` | Namespaces NiceGUI keys in Redis. |
|
||||
| `MARKDOWN_CONTENT_CACHE_SIZE` | `1000` | Bounds cached Markdown snippets. |
|
||||
| `RST_CONTENT_CACHE_SIZE` | `1000` | Bounds cached reStructuredText snippets. |
|
||||
|
||||
Treat these as process-start configuration. For application-owned host, port, credentials, feature flags, and service settings, use one validated settings model rather than scattering direct environment reads. When multiple processes or executables share local storage, do not let them independently rewrite the same files; give each instance a distinct `NICEGUI_STORAGE_PATH` or configure Redis where state must be shared.
|
||||
|
||||
## Deploy A Browser-Hosted App
|
||||
|
||||
Run the production entry point under a service manager or container restart policy. NiceGUI's [multi-architecture Docker image](https://hub.docker.com/r/zauberzeug/nicegui) runs an application mounted at `/app`; its default internal port is `8080`, so publish that port explicitly. The image supports non-root execution through `PUID` and `PGID` and passes process signals through to the app.
|
||||
|
||||
```bash
|
||||
docker run --detach --restart always \
|
||||
--publish 80:8080 \
|
||||
--env PUID="$(id -u)" \
|
||||
--env PGID="$(id -g)" \
|
||||
--volume "$PWD:/app" \
|
||||
zauberzeug/nicegui:latest
|
||||
```
|
||||
|
||||
For HTTPS, either pass Uvicorn's `ssl_certfile` and `ssl_keyfile` options to `ui.run(...)` or terminate TLS at a reverse proxy such as NGINX or Traefik. A reverse-proxy deployment must preserve NiceGUI's HTTP and Socket.IO traffic, forwarding scheme and host information, route prefixes, timeouts, and upload limits consistently. Verify the rendered page, static assets, websocket connection, reconnect behavior, and upload path through the public URL rather than only against the container port.
|
||||
|
||||
Use one worker by default. NiceGUI clients, element trees, tasks, and ordinary Python state are process-local; a multi-worker deployment needs compatible session affinity and externalized shared state. See [FastAPI and Uvicorn startup](./fastapi-uvicorn-startup.md#development-reload) before adding workers or combining them with reload.
|
||||
|
||||
## Build A Native Desktop App
|
||||
|
||||
[`ui.run(native=True)`](https://nicegui.io/documentation/section_configuration_deployment#native-mode) launches a pywebview window. `window_size`, `fullscreen`, and `frameless` cover common presentation settings. Configure lower-level pywebview behavior before startup through:
|
||||
|
||||
- `app.native.window_args` for `webview.create_window` arguments
|
||||
- `app.native.start_args` for `webview.start` arguments
|
||||
- `app.native.settings` for pywebview settings
|
||||
- `app.native.main_window` for asynchronous access to the running window
|
||||
|
||||
Values in `window_args` and `start_args` take precedence over overlapping `ui.run` arguments. The browser engine must support ES modules and import maps; use Chrome 89 or newer, a current WebKitGTK or Qt backend on Linux, and the EdgeChromium prerequisites used by pywebview on Windows. A local Windows `favicon` used as the native icon must be an `.ico` file.
|
||||
|
||||
Native mode chooses an available port automatically when `port` is omitted. Browser mode defaults to `8080`; use `native.find_open_port()` explicitly when multiple browser-mode executable instances must coexist.
|
||||
|
||||
### Native Events And Process Placement
|
||||
|
||||
Register sync or async handlers with `app.native.on(...)`. Supported lifecycle and window events are `shown`, `loaded`, `minimized`, `maximized`, `restored`, `resized`, `moved`, `closed`, and `drop`. Resized and moved events expose dimensions or coordinates in `event.args`; drop events expose filesystem paths under `event.args['files']`.
|
||||
|
||||
The native UI runs in a separate process. Define `app.native.window_args`, `start_args`, `settings`, and event registrations outside the `if __name__ == '__main__':` guard so the child process sees them.
|
||||
|
||||
```python
|
||||
from nicegui import app, ui
|
||||
|
||||
app.native.window_args['resizable'] = False
|
||||
app.native.on('drop', lambda event: print(event.args['files']))
|
||||
|
||||
if __name__ == '__main__':
|
||||
ui.run(native=True, reload=False)
|
||||
```
|
||||
|
||||
Native storage follows the same scopes as browser mode. Multiple executable instances started from one working directory can collide on the default `.nicegui` files; isolate `NICEGUI_STORAGE_PATH` per instance or use Redis for intentionally shared state.
|
||||
|
||||
## Package An Executable
|
||||
|
||||
Both `nicegui-pack`/PyInstaller and Nuitka require an import-safe application:
|
||||
|
||||
1. Disable auto-reload with `ui.run(reload=False, ...)`.
|
||||
2. Supply a `root` page callable to `ui.run` or register at least one `@ui.page`.
|
||||
3. Decide whether the executable opens a browser or uses `native=True`.
|
||||
4. Use an available port when simultaneous instances are valid.
|
||||
5. Exercise the built artifact on every target operating system; a successful build on the development host does not establish runtime compatibility.
|
||||
|
||||
With [`nicegui-pack`](https://nicegui.io/documentation/section_configuration_deployment#package-for-installation), `--onefile` is convenient but starts more slowly because PyInstaller extracts it on each run. A directory build starts faster and can be archived for distribution. Use `--windowed` only with `native=True`; a browser-mode application without a console has no normal Ctrl-C exit surface.
|
||||
|
||||
Nuitka must include both NiceGUI modules and package data because NiceGUI uses lazy imports and ships frontend assets:
|
||||
|
||||
```bash
|
||||
python -m nuitka \
|
||||
--onefile \
|
||||
--include-package=nicegui \
|
||||
--include-package-data=nicegui \
|
||||
main.py
|
||||
```
|
||||
|
||||
Add equivalent package and package-data flags for optional libraries that ship templates or frontend assets. Prefer `--standalone` when startup speed matters more than producing one file.
|
||||
|
||||
### Multiprocessing In Packaged Native Apps
|
||||
|
||||
Packaged native apps must call [`multiprocessing.freeze_support()`](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.freeze_support) as the first statement inside the main guard to prevent recursive process creation. Keep native settings outside the guard so the spawned native process applies them.
|
||||
|
||||
```python
|
||||
from multiprocessing import freeze_support
|
||||
|
||||
from nicegui import app, ui
|
||||
|
||||
app.native.window_args['transparent'] = True
|
||||
|
||||
|
||||
def root() -> None:
|
||||
ui.label('Packaged app')
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
freeze_support()
|
||||
ui.run(root, native=True, reload=False)
|
||||
```
|
||||
|
||||
## Use On Air Only For Deliberate Remote Access
|
||||
|
||||
[`ui.run(on_air=True)`](https://nicegui.io/documentation/section_configuration_deployment#nicegui-on-air) creates a temporary public URL, currently valid for one hour. A private device token can select a stable organization/device URL. Treat that token as a secret, and do not log or commit it.
|
||||
|
||||
NiceGUI On Air is a tech preview, not a substitute for selecting an authentication, authorization, availability, and data-governance model. Before exposing an application, review what data and actions become reachable, add application authentication where needed, and verify the service's current operational and privacy terms. Use ordinary hosted deployment when the application requires controlled networking, durable availability, or organization-owned TLS and access policy.
|
||||
|
||||
## Deployment Verification
|
||||
|
||||
Validate the built deployment through its real entry point and public boundary:
|
||||
|
||||
- process starts with reload disabled and shuts down cleanly under the service manager or container runtime
|
||||
- health route, root page, static assets, Socket.IO connection, and reconnect flow work through the proxy or published port
|
||||
- `app.urls` is consumed only after server binding and is not mistaken for canonical proxy configuration
|
||||
- storage survives and isolates users, tabs, workers, and executable instances as designed
|
||||
- TLS, forwarded headers, cookie flags, upload limits, cache policy, and logs match the public deployment
|
||||
- a native build opens, handles window events, closes cleanly, and can run alongside another instance when supported
|
||||
- packaged artifacts include NiceGUI and optional-library data files and are tested on each target platform
|
||||
- normal background tasks cancel on shutdown, while only explicitly bounded finalization work uses `@background_tasks.await_on_shutdown`; see [interaction mechanics](./interaction-patterns.md#execution-contexts)
|
||||
|
||||
## Sources
|
||||
|
||||
!!! info "Primary sources"
|
||||
- [NiceGUI configuration and deployment](https://nicegui.io/documentation/section_configuration_deployment)
|
||||
- [`ui.run` arguments](https://nicegui.io/documentation/run)
|
||||
- [NiceGUI Docker example](https://github.com/zauberzeug/nicegui/tree/main/examples/docker_image)
|
||||
- [NiceGUI NGINX HTTPS example](https://github.com/zauberzeug/nicegui/blob/main/examples/nginx_https/nginx.conf)
|
||||
- [NiceGUI FastAPI example](https://github.com/zauberzeug/nicegui/tree/main/examples/fastapi)
|
||||
- [pywebview API](https://pywebview.flowrl.com/api)
|
||||
- [Uvicorn settings](https://www.uvicorn.org/settings/)
|
||||
@@ -57,6 +57,8 @@ ui.run()
|
||||
|
||||
In this mode, NiceGUI configures and starts its own [Uvicorn-derived server](https://github.com/zauberzeug/nicegui/blob/main/nicegui/server.py). Do not also call `uvicorn.run()`.
|
||||
|
||||
For `ui.run` arguments, runtime URL discovery, native mode, environment variables, hosted deployment, and executable packaging, use [configuration and deployment](./configuration-and-deployment.md).
|
||||
|
||||
### Let FastAPI Own The Application
|
||||
|
||||
Use `ui.run_with()` when an existing FastAPI application owns middleware, API routers, OpenAPI configuration, lifespan resources, or deployment startup. The [official NiceGUI FastAPI example](https://github.com/zauberzeug/nicegui/blob/main/examples/fastapi/main.py) follows this model.
|
||||
|
||||
@@ -146,7 +146,9 @@ uploader = ui.upload(
|
||||
|
||||
Generate the durable storage name independently from `file.name`, keep user-uploaded active content off the application origin, and apply content-specific scanning before downstream parsers consume the file. Call `uploader.reset()` when the product should clear QUploader's client-side queue after a completed or abandoned operation.
|
||||
|
||||
## Element Updates And Refreshable Regions
|
||||
## Refreshable Component Regions
|
||||
|
||||
The reusable [component factory pattern](./architecture.md#reusable-component-contract) combines stable bindable fields with bounded structural refreshes. Use bindings and setters while an existing element can represent the change; use a refreshable region when the number, type, order, or nesting of child elements must be rebuilt.
|
||||
|
||||
Use the narrowest update mechanism that represents the change:
|
||||
|
||||
@@ -157,18 +159,55 @@ Use the narrowest update mechanism that represents the change:
|
||||
| a bounded subtree whose structure changed | `@ui.refreshable` or `@ui.refreshable_method` |
|
||||
| navigation to a different page | `ui.navigate` or `ui.sub_pages` |
|
||||
|
||||
The tagged [`refreshable` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/functions/refreshable.py) records every invocation as a target container. `refresh()` clears and recreates each matching target; it does not diff children. Arguments passed to `refresh()` replace prior positional arguments when non-empty and update prior keyword arguments.
|
||||
The tagged [`refreshable` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/functions/refreshable.py) records every invocation as a target containing a `RefreshableContainer`, the function arguments, and the associated object instance when applicable. The initial call both renders the region and registers that target. Calling `refresh()` before the decorated function or method has rendered does nothing because no target exists yet.
|
||||
|
||||
A module-level refreshable called by multiple clients has multiple targets, so refreshing it can update all surviving targets. Define the decorated function inside the page, create a page-local decorated wrapper, or use a per-page object with `@ui.refreshable_method` when clients need independent refresh behavior.
|
||||
For each matching target, `refresh()` clears the container, updates its remembered arguments, and invokes the function again inside that same container. It recreates the subtree rather than diffing children. Bindings and event handlers owned by deleted elements follow normal element cleanup; a retained reference to a former child does not become the new child. Expose component state and public actions through the returned component handle instead of leaking refresh-owned element references.
|
||||
|
||||
For asynchronous refreshable functions:
|
||||
### Function And Method Scope
|
||||
|
||||
Choose the decorator according to state ownership:
|
||||
|
||||
| Form | Target identity | Appropriate scope |
|
||||
| --- | --- | --- |
|
||||
| module-level `@ui.refreshable` | every surviving call target of that decorated function | deliberate multicast or shared rendering |
|
||||
| page-local `@ui.refreshable` | calls recorded by the function created during that page build | one page client |
|
||||
| page-created `ui.refreshable(function)` | calls recorded by that decorated wrapper | one page client or component factory call |
|
||||
| `@ui.refreshable_method` | targets whose recorded instance equals the accessed object | reusable component instances with independent state |
|
||||
|
||||
A module-level refreshable called by multiple clients has multiple targets, so one refresh can update every surviving target. The official [global and local scope examples](https://nicegui.io/documentation/refreshable#global_scope) demonstrate this distinction. For reusable components returned as dataclass handles, prefer a page-created instance with `@ui.refreshable_method`; NiceGUI's tagged [multi-instance tests](https://github.com/zauberzeug/nicegui/blob/v3.16.0/tests/test_refreshable.py) verify that refreshing one instance selects its own targets.
|
||||
|
||||
Calling the same refreshable function more than once creates more than one target. For `@ui.refreshable_method`, every call made on the same instance belongs to that instance, so `instance.region.refresh()` refreshes all surviving targets for that method and instance. Use separate methods or separate component instances when independently refreshing two regions is required.
|
||||
|
||||
### Arguments And Return Behavior
|
||||
|
||||
Targets remember their initial positional and keyword arguments:
|
||||
|
||||
- no refresh arguments reuse all remembered values
|
||||
- non-empty positional refresh arguments replace the remembered positional tuple
|
||||
- keyword refresh arguments update the remembered keyword dictionary
|
||||
- arguments must remain consistently positional or keyword; supplying the same parameter through both paths raises `TypeError`
|
||||
- the initial call and each refresh return the decorated function's normal result; the `refresh()` wrapper itself exposes NiceGUI's awaitable response behavior
|
||||
|
||||
Parameters should describe render input, not hide durable state. On a reusable component, fields on the returned dataclass usually provide a clearer interface than repeatedly replacing a long refresh argument list.
|
||||
|
||||
### Async Refresh
|
||||
|
||||
An async refreshable's initial invocation returns its coroutine and should be awaited when page construction depends on its output. For subsequent refreshes:
|
||||
|
||||
- `await region.refresh()` waits for all matching async refreshes to finish
|
||||
- calling `region.refresh()` without awaiting schedules the async work in the background
|
||||
- awaiting is appropriate when a button must remain disabled until rendering completes
|
||||
- each refresh clears the old target before the new async render finishes, so provide a stable outer loading surface when an empty interval would be disruptive
|
||||
|
||||
`ui.state()` is local storage indexed by call order inside one refreshable target. It can only be called inside a refreshable function, and conditional changes to state-call order can associate values with the wrong logical state. Use typed page state or bindable dataclasses when state identity must remain explicit.
|
||||
Multiple matching targets are refreshed together; awaiting waits for all async results through `asyncio.gather`. That coordinates completion but does not serialize competing refresh calls. Apply the generation, lock, or coalescing policy described under [concurrency and feedback state](#concurrency-and-feedback-state) when two operations can refresh the same target concurrently.
|
||||
|
||||
### Target And Local-State Lifetime
|
||||
|
||||
Before every invocation or refresh, NiceGUI prunes targets whose container was deleted. Clearing an ancestor, navigating away, deleting the client, or replacing an outer refreshable region can therefore remove an inner target. A later call to the inner region's `refresh()` cannot recreate a pruned outer placement; the owning outer render must invoke it again.
|
||||
|
||||
`ui.state()` stores values in a list owned by one refreshable target and identifies each value by call order. Its setter automatically refreshes the associated instance target. Conditional or reordered `ui.state()` calls can associate stored values with a different logical variable, so keep their call order stable.
|
||||
|
||||
For reusable application components, a bindable dataclass is usually the clearer state owner: fields have explicit names, can bind directly to stable elements, and remain available to the page through the returned handle. Reserve `ui.state()` for small render-local values that do not need a typed component API, cross-component coordination, service persistence, or independent tests.
|
||||
|
||||
## Timers And Application Events
|
||||
|
||||
@@ -204,6 +243,8 @@ The tagged [`run` implementation](https://github.com/zauberzeug/nicegui/blob/v3.
|
||||
|
||||
The tagged [`background_tasks` implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/background_tasks.py) keeps strong references to running tasks, forwards unhandled exceptions to global exception handlers, and cancels ordinary tasks during shutdown. `create_lazy()` coalesces repeated work by name into the current run plus only the latest waiting coroutine; it is useful for refresh-style invalidation, not for work where every event must be processed.
|
||||
|
||||
Decorate a coroutine with `@background_tasks.await_on_shutdown` only when process shutdown must wait for that bounded task to finish, such as flushing a small already-accepted result. The decorator prevents NiceGUI's normal shutdown cancellation; it does not make the work durable after a crash, container kill, or host failure. Keep unbounded work and retryable jobs in an external worker rather than delaying application termination indefinitely.
|
||||
|
||||
## Live Update Transports
|
||||
|
||||
| Requirement | Default surface |
|
||||
|
||||
@@ -9,11 +9,16 @@ Use these links to verify framework-specific behavior before relying on version-
|
||||
- [Element styling, props, and events](https://nicegui.io/documentation/element)
|
||||
- [NiceGUI element source](https://github.com/zauberzeug/nicegui/tree/main/nicegui/elements)
|
||||
- [Pages, routing, and FastAPI integration](https://www.nicegui.io/documentation/section_pages_routing)
|
||||
- [Configuration, native mode, hosting, and packaging](https://nicegui.io/documentation/section_configuration_deployment)
|
||||
- [`ui.run` arguments](https://nicegui.io/documentation/run)
|
||||
- [`ui.run_with` implementation](https://github.com/zauberzeug/nicegui/blob/main/nicegui/ui_run_with.py)
|
||||
- [FastAPI integration example](https://github.com/zauberzeug/nicegui/blob/main/examples/fastapi/main.py)
|
||||
- [Binding properties and bindable dataclasses](https://www.nicegui.io/documentation/section_binding_properties)
|
||||
- [Action events](https://www.nicegui.io/documentation/section_action_events)
|
||||
- [Security best practices](https://www.nicegui.io/documentation/section_security)
|
||||
- [Machine-readable sitewide documentation index](https://nicegui.io/static/sitewide_index.json)
|
||||
- [Machine-readable documentation search index](https://nicegui.io/static/search_index.json)
|
||||
- [Machine-readable examples index](https://nicegui.io/static/examples_index.json)
|
||||
|
||||
## FastAPI
|
||||
|
||||
|
||||
@@ -82,7 +82,20 @@ Tailwind's [responsive variants](https://tailwindcss.com/docs/responsive-design)
|
||||
|
||||
### Combine Tailwind With Quasar Utilities Deliberately
|
||||
|
||||
NiceGUI's `.classes()` accepts both Tailwind utilities and CSS helpers bundled with Quasar. Tailwind remains the default for application layout and responsive structure; Quasar helpers are useful when dimensions should follow Quasar's component conventions:
|
||||
NiceGUI's `.classes()` accepts both Tailwind utilities and CSS helpers bundled with Quasar. Assign each concern to one system:
|
||||
|
||||
| Concern | Default owner | Examples |
|
||||
| --- | --- | --- |
|
||||
| Python element structure | NiceGUI | `ui.row`, `ui.column`, `ui.grid`, slot context managers |
|
||||
| Generic geometry and responsive layout | Tailwind | `w-full`, `items-center`, `justify-center`, `gap-2`, `p-6`, `flex-wrap` |
|
||||
| Generic application typography | Tailwind | `text-xl`, `font-medium`, `leading-6`, `truncate` |
|
||||
| Theme-aware semantic color | Quasar | `text-primary`, `bg-positive`, `text-grey-7` |
|
||||
| Component behavior and density | Quasar props | `dense`, `outlined`, `round`, `separator=horizontal` |
|
||||
| Component-specific geometry | Quasar helper classes | `q-table--col-auto-width`, `absolute-top-right` |
|
||||
|
||||
Prefer the Tailwind spelling when both systems express ordinary application layout or typography. For example, use `w-full` instead of `full-width`, `items-center justify-center` instead of `flex-center`, `gap-2` instead of `q-gutter-sm`, `p-4` instead of `q-pa-md`, and `text-xl font-medium` instead of `text-h6 text-weight-medium`. This keeps spacing, breakpoints, and type choices in one vocabulary.
|
||||
|
||||
Quasar helpers remain useful when a value intentionally follows Quasar's component conventions:
|
||||
|
||||
- [`q-m*` and `q-p*` spacing classes](https://quasar.dev/style/spacing) when spacing should follow Quasar's component scale
|
||||
- [typography helpers](https://quasar.dev/style/typography), such as `text-h6`, `text-subtitle2`, and `text-weight-medium`, for text that should follow Quasar's type system
|
||||
@@ -90,7 +103,7 @@ NiceGUI's `.classes()` accepts both Tailwind utilities and CSS helpers bundled w
|
||||
- [positioning helpers](https://quasar.dev/style/positioning), such as `absolute-top-right`, when positioning content relative to a Quasar component
|
||||
- [size and overflow helpers](https://quasar.dev/style/other-helper-classes), such as `fit`, `full-width`, and `overflow-auto`, when matching Quasar layout behavior
|
||||
|
||||
Do not assign the same property through both systems on one element. For example, `w-full q-pa-md` uses Tailwind for width and Quasar for component-scale padding; adding `p-4` would create competing padding declarations. The same rule applies to Tailwind and Quasar visibility helpers or to Tailwind font sizes and Quasar heading classes.
|
||||
Do not assign the same property through both systems on one element. For example, `w-full q-pa-md` deliberately uses Tailwind for width and Quasar for component-scale padding; adding `p-4` would create competing padding declarations. The same rule applies to Tailwind and Quasar visibility helpers or to Tailwind font sizes and Quasar heading classes.
|
||||
|
||||
```python
|
||||
with ui.card().classes("w-full max-w-2xl q-pa-md"):
|
||||
|
||||
@@ -0,0 +1,101 @@
|
||||
# URL-Backed Tabs with Sub Pages
|
||||
|
||||
The [`tab_spa.py` example](../examples/tab_spa.py) combines [NiceGUI tabs](https://nicegui.io/documentation/tabs) with [sub-page routing](https://nicegui.io/documentation/sub_pages). It keeps one application shell and one set of tab panels mounted while the browser URL identifies the active view.
|
||||
|
||||
The example targets NiceGUI `3.16.0`. In this design, tabs are the visible navigation and content mechanism; `ui.sub_pages` is a URL-matching adapter whose route builders update the tab state instead of rendering route content inside the router.
|
||||
|
||||
## Responsibility Map
|
||||
|
||||
| Surface | Responsibility |
|
||||
| --- | --- |
|
||||
| `root()` | Creates one client-local shell, reads the initial URL, and connects the tabs, panels, and router. |
|
||||
| `ui.tabs` | Holds the selected tab name and emits user selection changes. |
|
||||
| `ui.tab_panels` | Displays the panel whose name matches the selected tab. |
|
||||
| `ui.sub_pages` | Matches URL paths, extracts route parameters, and invokes the corresponding route callback without a full page reload. |
|
||||
| `NavigationState` | Retains the concrete report path represented by the shared `reports` tab. |
|
||||
| `ui.navigate.to()` | Changes the browser location so the sub-pages router can resolve the destination. |
|
||||
|
||||
The separation matters because a tab name is not always a URL. Static tabs use their route as their name, but every `/reports/{report_id}` URL maps to the single `reports` tab and panel.
|
||||
|
||||
## Route and Panel Mapping
|
||||
|
||||
| Browser path | Tab value | Panel value | Route callback effect |
|
||||
| --- | --- | --- | --- |
|
||||
| `/` | `/` | `/` | Selects the overview panel. |
|
||||
| `/projects` | `/projects` | `/projects` | Selects the projects panel. |
|
||||
| `/reports/a` | `reports` | `reports` | Stores `/reports/a` and selects the reports panel. |
|
||||
| `/reports/b` | `reports` | `reports` | Stores `/reports/b` and selects the reports panel. |
|
||||
| `/settings` | `/settings` | `/settings` | Selects the settings panel. |
|
||||
|
||||
`tab_name_for_route()` is the translation boundary. It preserves static route names, collapses concrete report routes to `reports`, and returns `/` for other paths.
|
||||
|
||||
## Initial Page Construction
|
||||
|
||||
`root()` reads `ui.context.client.sub_pages_router.current_path` before creating the navigation controls. `normalize_route()` removes query strings, fragments, and trailing slashes so `/projects/` and `/projects` select the same tab.
|
||||
|
||||
For a direct request to `/reports/b`, the initial route produces two values:
|
||||
|
||||
- `active_report_path` becomes `/reports/b`.
|
||||
- the selected tab and panel become `reports`.
|
||||
|
||||
The initial `tabs.set_value(...)` call occurs before `tabs.on_value_change(navigate)` is registered. Initial selection therefore establishes the shell state without treating page construction as a user navigation. Passing the same initial tab value to `ui.tab_panels` aligns the content container with the tabs from the first render.
|
||||
|
||||
All panel builders run during shell construction. Switching tabs changes the selected panel; it does not rerun `overview_page()`, `projects_page()`, `report_page()`, or `settings_page()`. Their element state remains client-local for the lifetime of that shell.
|
||||
|
||||
## Tab-Originated Navigation
|
||||
|
||||
The tab change handler receives the selected tab name. Static tab names are already destinations. The reports tab resolves through `state.active_report_path`, which supplies the last concrete report URL:
|
||||
|
||||
```python
|
||||
destination = state.active_report_path if tabname == REPORTS_TAB else tabname
|
||||
ui.navigate.to(destination)
|
||||
```
|
||||
|
||||
[`ui.navigate.to()`](https://nicegui.io/documentation/navigate) performs the route transition. The sub-pages router then matches the new location and invokes a callback that selects the corresponding tab. Because the panel container is associated with `tabs`, the visible panel follows that selected value.
|
||||
|
||||
## URL-Originated Navigation
|
||||
|
||||
The route callbacks contain no page markup. They translate router matches back into the visible state:
|
||||
|
||||
```python
|
||||
def route_reports(report_id: str) -> None:
|
||||
state.active_report_path = f"/reports/{report_id}"
|
||||
tabs.set_value(REPORTS_TAB)
|
||||
```
|
||||
|
||||
This direction handles direct links and browser back or forward navigation. A URL such as `/reports/b` supplies `report_id="b"`; the callback reconstructs the normalized concrete path, updates report-bound labels through `NavigationState`, and selects the shared reports panel.
|
||||
|
||||
The router element is hidden because it is not the content container in this example:
|
||||
|
||||
```python
|
||||
ui.sub_pages(routes).classes("hidden")
|
||||
```
|
||||
|
||||
Normally, `ui.sub_pages` clears and rebuilds its own children when a route changes. Here its builders only mutate state outside that container, so hiding the empty routing element does not hide the tab-panel content.
|
||||
|
||||
## Parameterized Report State
|
||||
|
||||
`NavigationState.active_report_path` separates tab identity from route identity. The reports tab always has the stable value `reports`, while the state records `/reports/a`, `/reports/b`, or another matched report route.
|
||||
|
||||
This provides two forms of continuity:
|
||||
|
||||
- A direct report URL selects the correct tab and report during initial construction.
|
||||
- Leaving the reports tab and selecting it again during the same client lifetime returns to the last visited report.
|
||||
|
||||
The state is page-local, not durable storage. Reloading a non-report URL creates a new `NavigationState` and restores `DEFAULT_REPORT_PATH`. Shareable report identity remains durable because report pages encode it in the URL.
|
||||
|
||||
## Behavioral Boundaries
|
||||
|
||||
- `TAB_ROUTES` contains concrete routes whose path and tab identity are the same. Parameterized route families require a stable synthetic tab name such as `reports`.
|
||||
- `normalize_route()` intentionally ignores query parameters and fragments for tab selection. Route callbacks would need matching parameters if those values affected panel state.
|
||||
- The hidden router also hides its built-in 404 output. As written, an unmatched path selects the overview panel through `tab_name_for_route()` while the router's not-found content remains invisible.
|
||||
- Panels are mounted together, so expensive panel construction still occurs during the initial shell build. Lazy or route-specific construction requires a different content ownership model.
|
||||
- The pattern preserves the shell only for navigation handled by the current `ui.sub_pages` router. A full reload creates a new client and rebuilds all page-local state.
|
||||
|
||||
## Source Index
|
||||
|
||||
!!! info "NiceGUI sources"
|
||||
- [Sub pages and URL parameters](https://nicegui.io/documentation/sub_pages)
|
||||
- [Tabs, tab names, and tab panels](https://nicegui.io/documentation/tabs)
|
||||
- [Navigation and browser history](https://nicegui.io/documentation/navigate)
|
||||
- [NiceGUI `3.16.0` sub-pages implementation](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/sub_pages.py)
|
||||
@@ -0,0 +1,412 @@
|
||||
# Table Customization
|
||||
|
||||
Use this reference when a [`ui.table`](https://nicegui.io/documentation/table) needs presentation, controls, responsive behavior, or custom cell content while retaining [Quasar QTable](https://quasar.dev/vue-components/table) sorting, filtering, pagination, and selection behavior. Use [editable tables](./tables.md) instead when browser-originated cell values must be validated and committed by Python.
|
||||
|
||||
## Version Baseline
|
||||
|
||||
This reference and its runnable example were verified against this bundled stack:
|
||||
|
||||
| Layer | Version | Evidence |
|
||||
| --- | --- | --- |
|
||||
| NiceGUI | `3.16.0` | [Tagged `Table` source](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/table.py) |
|
||||
| Quasar | `2.18.5` | [NiceGUI frontend dependencies](https://github.com/zauberzeug/nicegui/blob/v3.16.0/package.json) |
|
||||
| Vue | `3.5.22` | [NiceGUI frontend dependencies](https://github.com/zauberzeug/nicegui/blob/v3.16.0/package.json) |
|
||||
|
||||
Recheck the tagged NiceGUI sources and bundled dependencies for another release. The current Quasar documentation may describe features added after NiceGUI's bundled Quasar version.
|
||||
|
||||
## Choose The Narrowest Layer
|
||||
|
||||
Apply customization at the highest-level API that expresses it:
|
||||
|
||||
1. Use `ui.table(...)` for rows, columns, defaults, stable row identity, title, selection, and pagination.
|
||||
2. Use column definitions for alignment, sorting, formatting, cell classes, header classes, and width hints.
|
||||
3. Use `.props(...)` for QTable behavior that the NiceGUI constructor does not expose, such as `dense`, `separator`, `wrap-cells`, `rows-per-page-options`, and empty-state labels.
|
||||
4. Use named slots for custom toolbar content, one special header or cell, loading, no-data content, or pagination controls.
|
||||
5. Use a full `header`, `body`, or `item` slot only when the whole generated structure must change.
|
||||
6. Add narrowly scoped CSS for behavior that neither component API covers, such as sticky columns.
|
||||
|
||||
NiceGUI's tagged [table client wrapper](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/table.js) passes props to QTable and forwards every supplied slot with its scoped properties. This makes QTable's API the source of truth below the NiceGUI wrapper, but it does not make every current QTable feature compatible with the bundled `2.18.5` release.
|
||||
|
||||
## Columns Before Slots
|
||||
|
||||
A QTable column is both a data projection and a presentation contract. Keep its `name` unique because sorting and `body-cell-[name]` slot selection use it. `field` identifies or computes the raw cell value; it does not need to match the column name.
|
||||
|
||||
```python
|
||||
columns = [
|
||||
{
|
||||
"name": "available",
|
||||
"label": "In stock",
|
||||
"field": "stock",
|
||||
"sortable": True,
|
||||
"align": "right",
|
||||
},
|
||||
]
|
||||
|
||||
table = ui.table(
|
||||
rows=rows,
|
||||
columns=columns,
|
||||
column_defaults={"headerClasses": "text-grey-8"},
|
||||
row_key="id",
|
||||
)
|
||||
```
|
||||
|
||||
Use plain keys such as `classes`, `style`, `headerClasses`, and `headerStyle` for static values. NiceGUI's client-side dynamic-property conversion recognizes colon-prefixed keys such as `:field`, `:format`, `:sort`, `:classes`, and `:style` as JavaScript expressions. Keep row data JSON-serializable; format display values in a column or slot rather than putting component objects in rows.
|
||||
|
||||
### Raw Values And Cosmetic Display Formatting
|
||||
|
||||
Use the column's `format(value, row)` function when only the displayed cell text should change. QTable's tagged [`getCellValue`](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/QTable.js) resolves `field` first and then passes that raw value through `format`. The formatted result is used by the default cell renderer and exposed to `body-cell-*` slots as `props.value`.
|
||||
|
||||
Keep the layers distinct:
|
||||
|
||||
| Layer | Owns | Effect |
|
||||
| --- | --- | --- |
|
||||
| row value | canonical JSON-serializable data sent by Python | remains available as `props.row.<field>` |
|
||||
| `field` | raw value extraction or derivation | supplies sorting and the input to `format` |
|
||||
| `format` | cosmetic text projection | changes default rendering, `props.value`, and local default-filter matching |
|
||||
| `body-cell-*` slot | component structure around the value | use for badges, icons, links, controls, or multiple elements |
|
||||
|
||||
Formatting does not mutate `table.rows` or the row object. QTable's tagged [sorting implementation](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/table-sort.js) compares raw `field` values, while its tagged [default filter](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/table-filter.js) searches the formatted values returned by `getCellValue`. This is usually desirable: numbers sort numerically while users can search what they see.
|
||||
|
||||
#### Prefix And Suffix Text
|
||||
|
||||
Use a null-safe `:format` expression for simple prefix or suffix text:
|
||||
|
||||
```python
|
||||
columns = [
|
||||
{
|
||||
"name": "price",
|
||||
"label": "Unit price",
|
||||
"field": "price",
|
||||
"sortable": True,
|
||||
":format": "value => value == null ? '' : `$${value.toFixed(2)}`",
|
||||
},
|
||||
{
|
||||
"name": "stock",
|
||||
"label": "In stock",
|
||||
"field": "stock",
|
||||
"sortable": True,
|
||||
":format": "value => value == null ? '' : `${value} units`",
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
The underlying values stay numeric, so sorting remains numeric. Check `value == null` rather than `if (!value)` when zero is valid; `0` must render as `$0.00` or `0 units`, not as an empty cell. Use a named cell slot instead when the prefix or suffix needs separate styling, an icon, a tooltip, or accessible text that differs from the visible text.
|
||||
|
||||
#### Datetime Text
|
||||
|
||||
Send datetimes as ISO 8601 strings with an explicit offset. Python's [`datetime.isoformat()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.isoformat) includes an offset for aware values, and [`astimezone()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.astimezone) preserves the represented instant while converting zones:
|
||||
|
||||
```python
|
||||
from datetime import UTC, datetime
|
||||
|
||||
updated_at = datetime.now(UTC)
|
||||
row = {"updated_at": updated_at.astimezone(UTC).isoformat()}
|
||||
```
|
||||
|
||||
Avoid locale-formatted strings and naive datetime strings as transport values. JavaScript guarantees support for its standard ISO date-time format, but [date-time strings without an offset](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse) are interpreted in the browser's local timezone when they contain both a date and time. An explicit `Z` or `+00:00` identifies the instant unambiguously.
|
||||
|
||||
For repeated cells, construct one [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) and return a formatter closure. NiceGUI evaluates the colon-prefixed expression into the column function, so the formatter is reused instead of performing locale-data lookup for every cell:
|
||||
|
||||
```python
|
||||
columns = [
|
||||
{
|
||||
"name": "updated_at",
|
||||
"label": "Updated",
|
||||
"field": "updated_at",
|
||||
"sortable": True,
|
||||
":sort": "(left, right) => Date.parse(left) - Date.parse(right)",
|
||||
":format": """(() => {
|
||||
const formatter = new Intl.DateTimeFormat('en-US', {
|
||||
dateStyle: 'medium',
|
||||
timeStyle: 'short',
|
||||
timeZone: 'UTC',
|
||||
});
|
||||
return value => {
|
||||
if (!value) return '';
|
||||
const timestamp = Date.parse(value);
|
||||
return Number.isNaN(timestamp) ? 'Invalid date' : formatter.format(timestamp);
|
||||
};
|
||||
})()""",
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
Choose locale and timezone deliberately:
|
||||
|
||||
- Use a fixed locale such as `en-US` when the product requires one stable language convention; use `undefined` to follow the browser's locale.
|
||||
- Set `timeZone` to `UTC` or an IANA zone such as `America/New_York` for deterministic product behavior; omit it only when each viewer should see browser-local time.
|
||||
- Keep invalid-value handling explicit. `Date.parse()` returns `NaN` for an invalid value, while passing an invalid date directly to the formatter can throw.
|
||||
|
||||
Sorting still receives the raw ISO value from `field`; it never compares the formatted label. The explicit `:sort` function above converts those raw strings to epoch milliseconds, so values with different offsets are ordered by instant while cells keep their localized display text. Validate datetime strings before sending them because an invalid value makes `Date.parse()` return `NaN`. For a simpler data contract, send epoch milliseconds as the field value and format that number directly.
|
||||
|
||||
Lexicographic sorting without a custom `sort` function is chronological only when every ISO string uses the same fixed-width representation and offset, as in normalized UTC values. Local filtering is intentionally different: it matches the formatted text, so searches follow the chosen locale and timezone rather than the raw ISO string.
|
||||
|
||||
### Cell Classes And Styles
|
||||
|
||||
Quasar's tagged [`table-column-selection.js`](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/table-column-selection.js), [`QTh.js`](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/QTh.js), and [`QTd.js`](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/QTd.js) establish the exact targets:
|
||||
|
||||
| Column key | Applied to | Static or dynamic | Typical uses |
|
||||
| --- | --- | --- | --- |
|
||||
| `headerClasses` | The generated `<th>` for this column | Static string | Header color, weight, whitespace, sticky positioning, utility-based width |
|
||||
| `classes` | Every generated `<td>` in this column | String or function of `row` | Body typography, whitespace, conditional color, utility-based width |
|
||||
| `headerStyle` | Inline `style` on the generated `<th>` | Static string | Header-specific dimensions or positioning |
|
||||
| `style` | Inline `style` on every generated `<td>` | String or function of `row` | Body dimensions, overflow, or row-dependent presentation |
|
||||
|
||||
`align` is separate: Quasar prepends `text-left`, `text-right`, or `text-center` to both header and body classes. It also appends header state classes such as `sortable`, `sorted`, and `sort-desc`. Supplying `classes` or `headerClasses` does not remove those generated classes.
|
||||
|
||||
These fields interact through normal CSS rules:
|
||||
|
||||
- On the same cell, inline `style` normally wins over a conflicting class declaration. A class rule containing `!important` can beat a normal inline declaration; avoid building a width policy around that exception.
|
||||
- The order of class names in the `class` attribute does not decide precedence. CSS origin, importance, cascade layer, selector specificity, and stylesheet source order do.
|
||||
- `headerClasses` never flows into body cells, and `classes` never flows into the header. The same separation applies to `headerStyle` and `style`.
|
||||
- `column_defaults` is merged as `{**defaults, **column}`. A column-level value replaces the complete default value for that key; class strings are not concatenated. Include shared classes again in an overriding column value when they must be retained.
|
||||
- A named `header-cell-*` or `body-cell-*` slot replaces QTable's default cell renderer. Use `table.header(column_name)` or `table.cell(column_name)` so Quasar reapplies the computed column classes and styles to the resulting `QTh` or `QTd`.
|
||||
|
||||
Prefer classes for reusable visual policy and static utility classes. Prefer `headerStyle` and `style` for one-off values, especially dimensions that do not have a clear project utility. Use `:classes` or `:style` only when the value genuinely depends on the browser-side row; otherwise a static value is easier to inspect and override.
|
||||
|
||||
### Column Width Model
|
||||
|
||||
QTable renders a native table with `width: 100%`, `max-width: 100%`, and, by default, the browser's [`table-layout: auto`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/table-layout) algorithm. One column is a shared track: its header and all body cells receive the same final used width even though each cell can contribute a different width constraint.
|
||||
|
||||
This has several consequences:
|
||||
|
||||
1. A `width` in `headerStyle` and a different `width` in `style` do not override each other because they are declarations on different elements. The browser considers both, along with every cell's min-content and max-content size, and computes one column width.
|
||||
2. Under automatic layout, `width` is a strong sizing input, not a guaranteed cap. Long unbreakable content, cell padding, other columns, and the table's available width can make the column wider.
|
||||
3. `min-width` supplies a floor. `max-width` alone is not a dependable truncation mechanism for an automatic table because intrinsic content still participates in track sizing.
|
||||
4. QTable is `nowrap` by default through `q-table--no-wrap`. The `wrap-cells` prop removes that rule, allowing ordinary wrapping and reducing columns toward their min-content widths. For IDs or URLs, add [`overflow-wrap: anywhere`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/overflow-wrap) to create breaks inside otherwise unbreakable strings.
|
||||
5. Cell padding contributes to the track width. QTable uses `16px` horizontal padding per side normally and `8px` in dense mode, with larger edge padding retained for the first and last columns.
|
||||
|
||||
Use the following mechanisms in order:
|
||||
|
||||
| Goal | Recommended mechanism |
|
||||
| --- | --- |
|
||||
| Let content choose sensible widths | Leave `style` and `headerStyle` unset; keep automatic layout |
|
||||
| Keep a column from becoming too narrow | Put the same absolute `min-width` in `style` and `headerStyle` |
|
||||
| Give columns proportional targets | Put matching percentage `width` values in `style` and `headerStyle`; treat them as targets under automatic layout |
|
||||
| Keep utility or action cells compact | Use `auto-width` on `table.header(...)` and `table.cell(...)` in slots, or Quasar's `q-table--col-auto-width` class on both header and body; it sets `width: 1px` and content supplies the floor |
|
||||
| Allow readable narrow layouts | Enable `wrap-cells`, set a practical `min-width` for key columns, and let QTable's middle container scroll horizontally when the total minimum exceeds the viewport |
|
||||
| Guarantee a column allocation | Use fixed table layout, an explicit table width, matching first-row/header widths, and an explicit overflow policy |
|
||||
| Truncate text | Use a fixed/constrained track plus a block wrapper with Tailwind's `truncate` utility; [`text-overflow`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/text-overflow) does not create overflow by itself |
|
||||
|
||||
For ordinary data tables, automatic layout plus a few minimum or target widths is the idiomatic default. Apply matching values to `headerStyle` and `style`: one declaration is often enough to influence the shared track, but matching declarations make intent explicit, survive empty datasets, and keep custom header/body renderers consistent.
|
||||
|
||||
Use fixed layout only when predictable allocation matters more than content-driven sizing. QTable's `table-style` prop styles the scrolling wrapper `<div>`, not the nested native `<table>`, so it cannot set `table-layout`. This nested element cannot receive a utility class through NiceGUI or QTable's public API, making one application class and one scoped CSS rule necessary. Keep truncation on a Python-created wrapper with Tailwind's `truncate` utility:
|
||||
|
||||
```python
|
||||
ui.add_css("""
|
||||
.inventory-table .q-table {
|
||||
table-layout: fixed;
|
||||
}
|
||||
""")
|
||||
|
||||
table = ui.table(rows=rows, columns=columns).classes("inventory-table w-full")
|
||||
|
||||
with table.add_slot("body-cell-name"), table.cell("name"):
|
||||
ui.element("span").props(':textContent="props.value"').classes("block truncate")
|
||||
```
|
||||
|
||||
With fixed layout, the table must have a non-automatic width; QTable already gives its native table `width: 100%`, while `w-full` constrains the NiceGUI element. The first row's explicit widths determine tracks without a `<colgroup>`; later body content does not resize them and therefore needs wrapping, clipping, or scrolling. A full custom header changes that first-row contract, so retest every column after introducing one.
|
||||
|
||||
Column visibility has two useful patterns:
|
||||
|
||||
- Mark identity or action columns `required` when they must remain visible.
|
||||
- For a Python-owned column picker, assign the selected column names to `table.props["visible-columns"]`, then call `table.update()`. QTable automatically includes columns marked `required`. Assign the Python list directly to the prop rather than interpolating it into a JavaScript expression.
|
||||
|
||||
## QTable Props
|
||||
|
||||
Pass static QTable props as whitespace-delimited tokens. Prefix a prop with `:` only when its value is a JavaScript expression:
|
||||
|
||||
```python
|
||||
table.props(
|
||||
'flat bordered separator=horizontal wrap-cells '
|
||||
':dense="Quasar.Screen.lt.md" '
|
||||
':rows-per-page-options="[5, 10, 0]"'
|
||||
)
|
||||
```
|
||||
|
||||
Use static props for fixed component policy and dynamic props for small browser-owned presentation decisions such as responsive density. Keep authoritative business state and permission decisions in Python.
|
||||
|
||||
Useful QTable presentation props include:
|
||||
|
||||
| Need | Props |
|
||||
| --- | --- |
|
||||
| Surface | `flat`, `bordered`, `square`, `dark`, `color` |
|
||||
| Cell layout | `dense`, `separator`, `wrap-cells` |
|
||||
| Layers | `hide-header`, `hide-bottom`, `hide-pagination`, `hide-no-data` |
|
||||
| Labels | `no-data-label`, `no-results-label`, `loading-label`, `rows-per-page-label` |
|
||||
| Paging and sorting | `rows-per-page-options`, `binary-state-sort`, `column-sort-order` |
|
||||
| Large local datasets | `virtual-scroll`, `virtual-scroll-item-size`, `virtual-scroll-sticky-size-start` |
|
||||
|
||||
Virtual scrolling needs a bounded height and accurate row-size assumptions. If a full `body` slot renders multiple `QTr` elements for one data row, follow Quasar's `q-virtual-scroll--with-prev` and unique-key requirements. Do not enable virtual scrolling as a default for a small table.
|
||||
|
||||
## Named Slots
|
||||
|
||||
Prefer the smallest QTable slot that owns the customization:
|
||||
|
||||
| Slot | Use |
|
||||
| --- | --- |
|
||||
| `top-left`, `top-right` | Title, filters, column controls, export |
|
||||
| `header-cell-[name]` | One custom header while preserving other generated headers |
|
||||
| `body-cell-[name]` | One custom cell type while preserving generated rows and other cells |
|
||||
| `no-data`, `loading` | Empty, filtered-empty, and busy states |
|
||||
| `pagination` | Custom page controls |
|
||||
| `footer` | A real table footer such as totals |
|
||||
|
||||
Since NiceGUI `3.5.0`, a scoped slot can contain NiceGUI elements. Follow the [Python-owned slot composition](./component-mechanics.md#prefer-python-owned-composition) rule: use context managers and NiceGUI elements for structure, keep application logic in Python, and reserve dynamic props for scoped values that exist only in the browser. Wrap body-cell content in `table.cell(column_name)` so QTable retains the column's alignment and cell semantics:
|
||||
|
||||
```python
|
||||
STATUS_COLORS = {
|
||||
"Ready": "positive",
|
||||
"Low": "warning",
|
||||
"Backorder": "negative",
|
||||
}
|
||||
|
||||
columns = [
|
||||
{
|
||||
"name": "status",
|
||||
"label": "Status",
|
||||
"field": "status",
|
||||
"colorByValue": STATUS_COLORS,
|
||||
},
|
||||
]
|
||||
|
||||
with table.add_slot("body-cell-status"), table.cell("status"):
|
||||
ui.badge().props(
|
||||
':label="props.value" '
|
||||
':color="props.col.colorByValue[props.value] ?? \'grey\'"'
|
||||
)
|
||||
```
|
||||
|
||||
Inside table slots, `props.value` is the parsed and formatted cell value, `props.row` is the row object, and `props.col` is the column definition. Custom JSON-serializable column keys such as `colorByValue` therefore provide a clean bridge from Python-owned display policy to a reused browser-side slot. Use Quasar color names in the mapping when the component's `color` prop should follow the active theme, and include a fallback for unexpected values.
|
||||
|
||||
A slot template is reused for every matching row, so `props.value`, `props.row`, and `props.col` are JavaScript expressions, not Python variables. Keep authorization and business-state decisions out of this mapping; it is client-visible presentation metadata.
|
||||
|
||||
### Add A Button To A Cell
|
||||
|
||||
Add an action column to the table's column definitions, then target it with the corresponding `body-cell-[name]` slot. Use a NiceGUI `ui.button` rather than writing a raw QBtn template, and wrap it in `table.cell(column_name)` so QTable preserves the cell's alignment, classes, styles, and table semantics.
|
||||
|
||||
The slot's `props.key` is the primitive identity derived from the table's `row_key`. Forward that key to Python instead of sending the full browser-side row object. Resolve the current authoritative row again in the handler because the record may have changed or disappeared since the table was rendered:
|
||||
|
||||
```python
|
||||
from nicegui import events
|
||||
from nicegui import ui
|
||||
|
||||
columns = [
|
||||
{"name": "actions", "label": "Actions", "required": True, "align": "center"},
|
||||
{"name": "name", "label": "Product", "field": "name", "align": "left"},
|
||||
]
|
||||
rows = [
|
||||
{"id": 101, "name": "Desk lamp"},
|
||||
{"id": 102, "name": "Task chair"},
|
||||
]
|
||||
|
||||
table = ui.table(rows=rows, columns=columns, row_key="id")
|
||||
|
||||
def open_product(event: events.GenericEventArguments) -> None:
|
||||
product = next((row for row in table.rows if row[table.row_key] == event.args), None)
|
||||
if product is None:
|
||||
ui.notify("Product no longer exists", type="negative")
|
||||
return
|
||||
ui.notify(f"Opening {product['name']}")
|
||||
|
||||
with (
|
||||
table.add_slot("body-cell-actions"),
|
||||
table.cell("actions"),
|
||||
ui.button(icon="open_in_new")
|
||||
.props("round flat size='sm'")
|
||||
.on(
|
||||
"click.stop",
|
||||
handler=open_product,
|
||||
js_handler="() => emit(props.key)",
|
||||
),
|
||||
):
|
||||
ui.tooltip("Open product")
|
||||
```
|
||||
|
||||
The compact icon-only button uses QBtn's `round`, `flat`, and `size` props to avoid a visually heavy filled action in every row. Nest `ui.tooltip` inside the button so each row's cloned QTooltip uses its own parent as the target. Do not call `action_button.tooltip(...)` in a reused scoped slot: NiceGUI implements that convenience method with an element-ID target, and every clone would resolve to the first button. The `.on(...)` bridge is necessary here because `props.key` exists only in the reused browser-side slot scope; a normal Python `on_click` callback cannot capture a different row for each rendered instance. The `click.stop` modifier prevents the button click from also reaching a row-click handler. Treat the key as untrusted input and repeat authorization, existence, and state checks before performing the real action.
|
||||
|
||||
Replacing the full `body` or `header` slot also replaces behavior QTable would otherwise generate. Render `QTr` plus `QTd` or `QTh`, pass the scoped props through, preserve unique row keys, and retest sorting, selection, focus, and responsive behavior. In particular, QTable row-click events are not emitted when a full `body`, `row`, or `item` slot owns the structure.
|
||||
|
||||
## Toolbar Search
|
||||
|
||||
NiceGUI controls can live in QTable toolbar slots. Bind an input's value one way to the table's `filter` property for a small, local dataset:
|
||||
|
||||
```python
|
||||
with table.add_slot("top-right"):
|
||||
ui.input(placeholder="Search inventory").props(
|
||||
"dense outlined clearable debounce=250"
|
||||
).bind_value_to(table, "filter")
|
||||
```
|
||||
|
||||
The path from keystroke to displayed rows is:
|
||||
|
||||
1. `debounce=250` waits until input has been idle for 250 milliseconds, reducing value-change traffic while the user types.
|
||||
2. `bind_value_to(table, "filter")` immediately initializes `table.filter` from the input and then propagates later input values in that direction only.
|
||||
3. For local rows, QTable lowercases the search term and each computed cell value. A row remains when at least one column value contains the term as a substring.
|
||||
4. QTable filters first, sorts the matching rows, resets pagination to page 1 when the filter changes, and then slices the current page.
|
||||
5. When no row matches, the `no-data` slot receives the configured `no-results-label` as `message` and a truthy `filter`; when the underlying row list is empty without a filter, it receives `no-data-label` and a falsy `filter`.
|
||||
|
||||
The default matcher uses each column's resolved `field` and then its `format` function. In this example, searches can therefore match displayed values such as `Hardware`, `Backorder`, or `$31.25`; the row ID is not searchable because it has no column. QTable passes its computed columns to the matcher, so a column excluded with the `visible-columns` prop is not searched. Hiding a column with CSS classes would leave it in the search set and should not be used as a substitute for the component prop.
|
||||
|
||||
This is client-side filtering over rows already sent to the browser. Do not load a large dataset merely to search it locally. When pagination contains `rowsNumber`, QTable switches to server-side mode, stops applying its local matcher, and emits a `request` carrying the filter and pagination state; validate the term and query the authoritative data source in that handler. Add explicit backend search semantics for field scope, tokenization, locale, and ranking instead of assuming they match QTable's substring behavior.
|
||||
|
||||
When Python needs the browser's current result set, prefer `await table.get_filtered_sorted_rows()` for all matches before pagination or `await table.get_computed_rows()` for the current page. These helpers require a connected client and should not replace backend filtering for server-owned data.
|
||||
|
||||
Prefer typed table helpers over raw frontend calls. Use `table.run_method(...)` only for QTable methods without a NiceGUI helper, such as `scrollTo`, `sort`, or `firstPage`, and verify the method in the bundled QTable API first.
|
||||
|
||||
## Runnable Example
|
||||
|
||||
The complete example combines raw-value sorting with cosmetic prefix, suffix, and datetime formatting; column defaults; responsive QTable props; filtering; column visibility; a toolbar; custom status and action cells; and a filtered-empty state. It is available as [`table_customization.py`](../examples/table_customization.py) and as `skill://nicegui/examples/table_customization.py`.
|
||||
|
||||
```python title="table_customization.py"
|
||||
--8<-- "docs/skills/nicegui/examples/table_customization.py"
|
||||
```
|
||||
|
||||
Run it from the repository root:
|
||||
|
||||
```bash
|
||||
uv run src/personal_mcp/docs/skills/nicegui/examples/table_customization.py
|
||||
```
|
||||
|
||||
Verify that stock and price sort by their numeric row values while displaying suffix and prefix text. Verify that updated timestamps sort chronologically by their raw ISO values while displaying localized UTC text. Confirm that searches are case-insensitive, match formatted values across columns, reset to the first page, and change the empty-state message when no rows match. Confirm that optional columns can be hidden and restored, the status cell retains its alignment and badge styling, and each action button reports the product from its own row. Hover action buttons in multiple rows and confirm that each one independently shows exactly one `Open product` tooltip. Resize the browser across mobile, landscape desktop, and portrait desktop widths; the toolbar must remain usable and the table must scroll without overlapping controls.
|
||||
|
||||
## Escalation Boundaries
|
||||
|
||||
- For editable cells, stable row identity, proposal validation, and canonical refresh, use [editable tables](./tables.md).
|
||||
- For generic scoped-slot values, event forwarding, and model events, use [component mechanics](./component-mechanics.md).
|
||||
- For page width, overflow, typography, and static CSS loading, use [page structure, typography, and scaling](./styling-and-customization.md).
|
||||
- For theme colors and dark mode, use [NiceGUI and Quasar color theming](./colors-and-quasar-theming.md).
|
||||
|
||||
## Source Index
|
||||
|
||||
!!! info "Primary documentation"
|
||||
- [NiceGUI table documentation](https://nicegui.io/documentation/table)
|
||||
- [Quasar QTable documentation](https://quasar.dev/vue-components/table)
|
||||
- [Python aware and naive datetimes](https://docs.python.org/3/library/datetime.html#aware-and-naive-objects)
|
||||
- [JavaScript `Date.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse)
|
||||
- [JavaScript `Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat)
|
||||
- [CSS table layout algorithm](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/table-layout)
|
||||
- [CSS width sizing](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/width)
|
||||
|
||||
!!! info "NiceGUI `3.16.0` implementation"
|
||||
- [`Table` Python source](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/table.py)
|
||||
- [Table client wrapper](https://github.com/zauberzeug/nicegui/blob/v3.16.0/nicegui/elements/table.js)
|
||||
- [Frontend dependency manifest](https://github.com/zauberzeug/nicegui/blob/v3.16.0/package.json)
|
||||
|
||||
!!! info "Bundled Quasar `2.18.5` implementation"
|
||||
- [QTable API definition](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/QTable.json)
|
||||
- [QTable implementation](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/QTable.js)
|
||||
- [QTable column computation](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/table-column-selection.js)
|
||||
- [QTable styles](https://github.com/quasarframework/quasar/blob/quasar-v2.18.5/ui/src/components/table/QTable.sass)
|
||||
|
||||
## Completion Check
|
||||
|
||||
Before accepting a customized table:
|
||||
|
||||
1. Verify the target NiceGUI release and its bundled Quasar version.
|
||||
2. Set a primitive, immutable, unique `row_key` before using selection or row-scoped actions.
|
||||
3. Use constructor arguments and column definitions before QTable props or slots.
|
||||
4. Keep sortable values canonical and serializable; use `format` only for cosmetic text and `sort` only when raw values need a custom comparator.
|
||||
5. Choose the narrowest named slot and preserve QTable cell or header semantics.
|
||||
6. Recheck sorting, filtering, pagination, selection, and empty states after customization.
|
||||
7. Check mobile, landscape desktop, and portrait desktop layouts; verify the toolbar remains usable and wide tables scroll without overlapping controls.
|
||||
@@ -57,6 +57,8 @@ The complete runnable source is available as [`editable_table.py`](../examples/e
|
||||
|
||||
The editor path uses the transformed-event pattern from [controlled values and model events](./component-mechanics.md#controlled-values-and-model-events). Attach the listener directly to each cell editor because Vue component events do not bubble from the editor to the cell or table. Read the QTable cell value from `props.value`, emit `props.row.<row_key>`, `props.col.name`, and the proposed value, then resolve the row in Python. NiceGUI's text-input wrapper uses `value` and `update:value`, while the number and select editors use `model-value` and `update:model-value`. Remove the text input's static `value` prop before adding its scoped `:value` binding. The select editor emits a NiceGUI-normalized option object, so this example forwards `option.label`, which is also the canonical value in `STATUS_OPTIONS`.
|
||||
|
||||
When a row needs an explicit save/cancel workflow, add an actions cell (for example `body-cell-actions`) that emits only the immutable row key and opens one reusable `ui.dialog`. Keep dialog controls as local draft state rather than binding directly to the authoritative row model. On **Save**, re-resolve the row by key, validate and normalize every proposed field in Python (for example with a small Pydantic draft model), and then commit all assignments together so partial validation failure cannot leave mixed old/new values. On **Cancel** or dialog dismiss, close the dialog without mutating authoritative state. This keeps the table in named cell slots and avoids the full-row templating boundary required by `QPopupEdit`.
|
||||
|
||||
## Persistence And Row Refresh
|
||||
|
||||
Keep `table.rows` as the serializable projection described in [bindable dataclasses](./binding-dataclasses.md#persistence-and-rollback), not the business model. After every accepted or rejected proposal, call `table.update_rows(state.table_rows(), clear_selection=False)` so the canonical projection replaces any temporary editor display. Preserve selection only while the selected row identities remain valid; otherwise use the default `clear_selection=True`.
|
||||
|
||||
@@ -4,96 +4,44 @@ icon: lucide/flask-conical
|
||||
|
||||
# Testing
|
||||
|
||||
This page describes the current test layout and execution model for this repository.
|
||||
|
||||
Primary guidance sources:
|
||||
- [Pytest scaffolding skill](./skills/pytesting/SKILL.md)
|
||||
- [Pytest docs reference](./skills/pytesting/references/pytest-docs.md)
|
||||
- [FastAPI + uv + Docker skill](./skills/fastapi-uv-docker/SKILL.md)
|
||||
|
||||
## Goals
|
||||
|
||||
1. Keep local feedback fast with deterministic tests.
|
||||
2. Mirror source modules with focused test groups.
|
||||
3. Keep endpoint and MCP surface checks explicit.
|
||||
4. Make marker usage strict and intentional.
|
||||
The test suite checks that the same public MCP behavior works over HTTP and stdio.
|
||||
|
||||
## Current Test Layout
|
||||
|
||||
Current tree:
|
||||
|
||||
```text
|
||||
tests/
|
||||
__init__.py
|
||||
conftest.py
|
||||
registry/
|
||||
test_read.py
|
||||
ingest/
|
||||
test_current_docs.py
|
||||
test_document.py
|
||||
models/
|
||||
test_document_validation.py
|
||||
prompts/
|
||||
test_content_renderer.py
|
||||
test_filesystem_provider.py
|
||||
skills/
|
||||
test_provider.py
|
||||
web/
|
||||
conftest.py
|
||||
test_endpoint_connections.py
|
||||
test_mcp_prompts.py
|
||||
test_mcp_skills.py
|
||||
server_contract.py
|
||||
test_http.py
|
||||
test_stdio.py
|
||||
```
|
||||
|
||||
Source-to-test alignment today:
|
||||
- `src/personal_mcp/registry/ingest/` -> `tests/registry/ingest/`
|
||||
- `src/personal_mcp/registry/models/` -> `tests/registry/models/`
|
||||
- `src/personal_mcp/prompts/` -> `tests/prompts/`
|
||||
- `src/personal_mcp/skills/provider.py` -> `tests/skills/test_provider.py`
|
||||
- `src/personal_mcp/web/` and MCP HTTP surface -> `tests/web/`
|
||||
`server_contract.py` contains the shared expectations. Both transport tests verify the resources, prompts, fallback tools, and representative reads against that contract.
|
||||
|
||||
## Markers And Strictness
|
||||
## Run Tests
|
||||
|
||||
Configured markers in `pyproject.toml`:
|
||||
- `unit`: fast deterministic tests with no external dependencies
|
||||
- `integration`: framework or component integration tests
|
||||
- `smoke`: thin critical-path checks
|
||||
|
||||
Pytest runs with `--strict-markers`, so any unregistered marker fails the test run.
|
||||
|
||||
## Fixture Layering
|
||||
|
||||
Fixture placement follows test scope:
|
||||
1. `tests/conftest.py` for cross-suite defaults.
|
||||
2. `tests/web/conftest.py` for web and endpoint client setup.
|
||||
|
||||
Prefer adding fixtures at the narrowest scope that serves more than one test.
|
||||
|
||||
## Command Baseline
|
||||
|
||||
Canonical invocation:
|
||||
Run the full suite with:
|
||||
|
||||
```bash
|
||||
uv run pytest
|
||||
```
|
||||
|
||||
Useful filtered runs:
|
||||
Run one transport while working on a focused change:
|
||||
|
||||
```bash
|
||||
uv run pytest --collect-only -q
|
||||
uv run pytest -m unit -q
|
||||
uv run pytest -m integration -q
|
||||
uv run pytest -m smoke -q
|
||||
uv run pytest tests/test_http.py -q
|
||||
uv run pytest tests/test_stdio.py -q
|
||||
```
|
||||
|
||||
## Adding New Tests
|
||||
The repository uses strict pytest markers. Register any new marker in `pyproject.toml` before using it.
|
||||
|
||||
When adding coverage:
|
||||
1. Place tests under the nearest existing module subtree (`prompts/`, `registry/`, `skills/`, or `web/`).
|
||||
2. Mirror the source path where practical.
|
||||
3. Reuse existing `conftest.py` files before adding new fixture layers.
|
||||
4. Add markers only when they convey execution intent, and register new markers in `pyproject.toml` first.
|
||||
## Full Validation
|
||||
|
||||
This keeps the suite aligned with the current architecture while preserving a fast local test loop.
|
||||
```bash
|
||||
uv run zensical build
|
||||
uv run ruff check .
|
||||
uv run ty check
|
||||
uv run pytest
|
||||
```
|
||||
|
||||
Prefer durable boundaries over implementation details: provider discovery, prompt rendering, traversal rejection, protocol behavior, and installed-package path resolution. Do not test deleted catalog projections, Pydantic immutability internals, or helper delegation.
|
||||
See the [Pytesting skill](./skills/pytesting/SKILL.md) when adding or restructuring tests.
|
||||
@@ -2,105 +2,59 @@
|
||||
icon: lucide/workflow
|
||||
---
|
||||
|
||||
# Skill Usage Mechanics
|
||||
# Using Personal MCP
|
||||
|
||||
## Purpose
|
||||
Personal MCP gives clients access to skills, prompts, and general documentation. Use the smallest piece of content that matches the task instead of loading the whole library.
|
||||
|
||||
This page describes how clients discover and load `personal-mcp` skills published by the [FastMCP Skills Provider](https://gofastmcp.com/servers/providers/skills).
|
||||
## Connect
|
||||
|
||||
Skills are MCP resources. The client remains responsible for selecting guidance, loading only useful supporting material, and applying it to the current workspace.
|
||||
|
||||
## Published Skill Surface
|
||||
|
||||
Each directory beneath `src/personal_mcp/docs/skills/` publishes:
|
||||
|
||||
1. `skill://<name>/SKILL.md` for primary instructions
|
||||
2. `skill://<name>/_manifest` for file discovery and integrity metadata
|
||||
3. `skill://<name>/{path*}` for supporting files
|
||||
|
||||
The server uses `supporting_files="template"`. Main files and manifests appear in `resources/list`; supporting files stay behind per-skill wildcard templates so the resource list remains compact.
|
||||
|
||||
The manifest contains every skill-relative path, byte size, and SHA256 hash. References do not have synthetic ids or a separate catalog record.
|
||||
|
||||
Prompts are available through native MCP prompt discovery and rendering.
|
||||
|
||||
## Discovery Workflow
|
||||
|
||||
Use this bounded sequence:
|
||||
|
||||
1. List resources or call FastMCP `list_skills()`.
|
||||
2. Compare skill names and descriptions.
|
||||
3. Read one selected `skill://<name>/SKILL.md`.
|
||||
4. Read `skill://<name>/_manifest` only when supporting material may be useful.
|
||||
5. Fetch the minimum supporting paths needed for the task.
|
||||
6. Reconcile the guidance with the actual repository code before making changes.
|
||||
|
||||
Do not load every skill or every supporting file up front.
|
||||
|
||||
## FastMCP Client Utilities
|
||||
|
||||
FastMCP provides native utilities in `fastmcp.utilities.skills`:
|
||||
|
||||
1. `list_skills(client)` discovers main skill resources.
|
||||
2. `get_skill_manifest(client, name)` parses a generated manifest.
|
||||
3. `download_skill(client, name, target_dir)` downloads one skill.
|
||||
4. `sync_skills(client, target_dir)` downloads all advertised skills.
|
||||
|
||||
These utilities operate directly on the native `skill://` contract and require no repository-specific adapter.
|
||||
|
||||
## Copilot Invocation
|
||||
|
||||
In VS Code, skills can arrive through:
|
||||
|
||||
1. explicit attachment from `Add Context > MCP Resources` or `MCP: Browse Resources`
|
||||
2. direct resource reads on selected `skill://<name>/SKILL.md` entries
|
||||
3. a slash-command prompt that names a specific native skill URI
|
||||
|
||||
Instructions can steer retrieval, but they do not guarantee automatic resource attachment in every chat surface. Use `MCP: Browse Resources` to confirm server-side availability, then attach only the minimum skill resources needed for the current task.
|
||||
|
||||
A reliable prompt is:
|
||||
The HTTP endpoint is `/mcp`. For a local server on port `8765`, connect to:
|
||||
|
||||
```text
|
||||
Browse MCP resources, select the best matching skill://.../SKILL.md entry by description, inspect its _manifest only if supporting detail is needed, and reconcile the guidance with this workspace.
|
||||
http://127.0.0.1:8765/mcp
|
||||
```
|
||||
|
||||
## Thin Shim Pattern
|
||||
Clients that launch servers as subprocesses can use:
|
||||
|
||||
Consumer repositories can bind file scopes to native skill resources with short `.github/instructions/*.instructions.md` files.
|
||||
|
||||
| `applyTo` scope | Companion docs | Primary skill resource |
|
||||
| --- | --- | --- |
|
||||
| `**/*.md` | [Authoring Guide](./authoring.md) | `skill://zensical-docs/SKILL.md` |
|
||||
| `tests/**` | [Testing](./testing.md) | `skill://pytesting/SKILL.md` |
|
||||
| `.vscode/**` | [VS Code Configuration](./skills/vscode-configuration/SKILL.md) | `skill://vscode-configuration/SKILL.md` |
|
||||
|
||||
Minimal shape:
|
||||
|
||||
```md
|
||||
---
|
||||
name: <scope name>
|
||||
description: Route <path scope> edits to a personal-mcp skill.
|
||||
applyTo: '<glob>'
|
||||
---
|
||||
|
||||
Load `skill://<skill-name>/SKILL.md` first. Read `_manifest` and supporting files only when the task needs deeper detail. Apply the guidance to the current repository rather than treating it as generated output.
|
||||
```bash
|
||||
uv run mcp-stdio
|
||||
```
|
||||
|
||||
## Failure Recovery
|
||||
## Use A Skill
|
||||
|
||||
When no skill is an obvious match:
|
||||
Skills are MCP resources. A client should:
|
||||
|
||||
1. compare the available main-resource descriptions again
|
||||
2. select at most two candidates
|
||||
3. read their main files, not all supporting files
|
||||
4. ask one clarifying question if the choice remains ambiguous
|
||||
1. browse the available `skill://<name>/SKILL.md` resources
|
||||
2. choose one by its name and description
|
||||
3. read the main `SKILL.md`
|
||||
4. read its `_manifest` only when extra reference material is needed
|
||||
5. load only the relevant supporting files
|
||||
|
||||
When a supporting path fails, refresh `_manifest`; file paths are the public supporting-resource identifiers.
|
||||
The guidance should then be checked against the code and conventions in the current workspace.
|
||||
|
||||
## Runtime Checklist
|
||||
## Use A Prompt
|
||||
|
||||
1. Confirm MCP connectivity.
|
||||
2. Confirm at least one `skill://<name>/SKILL.md` resource is listed.
|
||||
3. Read its `_manifest` and verify `SKILL.md` appears with a SHA256 hash.
|
||||
4. Read one supporting file through its manifest path.
|
||||
5. Keep loaded context bounded to the selected skill and relevant files.
|
||||
Prompts are reusable workflows with named arguments. Browse the server's prompts, select one by its description, and supply the requested values when invoking it.
|
||||
|
||||
In VS Code, MCP prompts appear as chat slash commands. Resources can be opened from **MCP: Browse Resources** and attached as context when the active chat surface supports it.
|
||||
|
||||
## Tool Fallbacks
|
||||
|
||||
Some clients can call tools but cannot browse MCP resources or prompts directly. For those clients, the server exposes four read-only tools:
|
||||
|
||||
- `list_resources`
|
||||
- `read_resource`
|
||||
- `list_prompts`
|
||||
- `get_prompt`
|
||||
|
||||
They provide access to the same underlying content. Clients with native resource and prompt support should use those native features.
|
||||
|
||||
## Example Request
|
||||
|
||||
```text
|
||||
Browse the available Personal MCP skills, choose the best match for this task,
|
||||
read its main SKILL.md, and load supporting files only if they are needed.
|
||||
Apply the guidance to this repository rather than treating it as generated output.
|
||||
```
|
||||
|
||||
For the exact resource and prompt formats, see the [content contracts](./contracts/index.md).
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from fastmcp import FastMCP
|
||||
from fastmcp.server.transforms import PromptsAsTools
|
||||
from fastmcp.server.transforms import ResourcesAsTools
|
||||
from mcp_types import Icon
|
||||
|
||||
from .prompts.provider import prompt_lifespan
|
||||
@@ -10,8 +12,9 @@ from .skills import skill_lifespan
|
||||
|
||||
_SERVER_INSTRUCTIONS = """Personal development guidance exposed as native MCP resources and prompts.
|
||||
|
||||
Use prompts for parameterized workflows. For task-specific guidance, browse native skill resources,
|
||||
select one skill://<name>/SKILL.md resource, and read its manifest only when supporting detail is needed.
|
||||
Use prompts for parameterized workflows; tool-only agents can discover and render them with
|
||||
list_prompts and get_prompt. For task-specific guidance, browse native skill resources, select one
|
||||
skill://<name>/SKILL.md resource, and read its manifest only when supporting detail is needed.
|
||||
"""
|
||||
_SERVER_ICON = Icon(
|
||||
src=(
|
||||
@@ -59,6 +62,10 @@ def create_mcp() -> FastMCP:
|
||||
def docs_markdown(path: str) -> dict[str, str]:
|
||||
return read_docs_markdown_path(registry, path)
|
||||
|
||||
# Bridges tool-only clients that cannot browse native resources or prompts directly.
|
||||
mcp.add_transform(ResourcesAsTools(mcp))
|
||||
mcp.add_transform(PromptsAsTools(mcp))
|
||||
|
||||
return mcp
|
||||
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
from fastmcp import Client
|
||||
from mcp_types import TextContent
|
||||
from mcp_types import TextResourceContents
|
||||
|
||||
|
||||
@@ -6,8 +7,9 @@ async def assert_server_contract(client: Client) -> None:
|
||||
resources = {str(resource.uri) for resource in await client.list_resources()}
|
||||
templates = {str(template.uri_template) for template in await client.list_resource_templates()}
|
||||
prompts = {prompt.name for prompt in await client.list_prompts()}
|
||||
tools = {tool.name for tool in await client.list_tools()}
|
||||
|
||||
assert await client.list_tools() == []
|
||||
assert tools == {"get_prompt", "list_prompts", "list_resources", "read_resource"}
|
||||
assert "skill://pytesting/SKILL.md" in resources
|
||||
assert "resource://docs/{path*}" in templates
|
||||
assert "skill://pytesting/{path*}" in templates
|
||||
@@ -20,3 +22,13 @@ async def assert_server_contract(client: Client) -> None:
|
||||
assert "# Pytesting" in skill_content[0].text
|
||||
assert isinstance(docs_content[0], TextResourceContents)
|
||||
assert '"format": "markdown"' in docs_content[0].text
|
||||
|
||||
listed = await client.call_tool("list_resources")
|
||||
listed_content = listed.content[0]
|
||||
assert isinstance(listed_content, TextContent)
|
||||
assert "skill://pytesting/SKILL.md" in listed_content.text
|
||||
|
||||
read = await client.call_tool("read_resource", {"uri": "skill://pytesting/SKILL.md"})
|
||||
read_content = read.content[0]
|
||||
assert isinstance(read_content, TextContent)
|
||||
assert "# Pytesting" in read_content.text
|
||||
|
||||
+3
-112
@@ -11,7 +11,7 @@
|
||||
# The site_name is shown in the page header and the browser window title
|
||||
#
|
||||
# Read more: https://zensical.org/docs/setup/basics/#site_name
|
||||
site_name = "Documentation"
|
||||
site_name = "Personal MCP"
|
||||
|
||||
site_dir = "src/personal_mcp/site"
|
||||
docs_dir = "src/personal_mcp/docs"
|
||||
@@ -20,12 +20,12 @@ docs_dir = "src/personal_mcp/docs"
|
||||
# meaningful description of the site content for use by search engines.
|
||||
#
|
||||
# Read more: https://zensical.org/docs/setup/basics/#site_description
|
||||
site_description = "A new project generated from the default template project."
|
||||
site_description = "Software development guidance published as MCP resources, prompts, and human-readable documentation."
|
||||
|
||||
# The site_author attribute. This is used in the HTML head element.
|
||||
#
|
||||
# Read more: https://zensical.org/docs/setup/basics/#site_author
|
||||
site_author = "<your name here>"
|
||||
site_author = "Personal MCP"
|
||||
|
||||
# The site_url is the canonical URL for your site. When building online
|
||||
# documentation you should set this.
|
||||
@@ -47,115 +47,6 @@ Copyright © 2026 The authors
|
||||
# can be defined using TOML syntax.
|
||||
#
|
||||
# Read more: https://zensical.org/docs/setup/navigation/
|
||||
# nav = [
|
||||
# { "Home" = "index.md" },
|
||||
# { "Guide" = [
|
||||
# { "Arch" = "architecture.md" },
|
||||
# { "Contracts" = [
|
||||
# { "Overview" = "contracts/index.md" },
|
||||
# { "Prompt" = "contracts/prompt.md" },
|
||||
# { "Skill" = "contracts/skill_contract.md" },
|
||||
# { "Frontmatter" = "contracts/frontmatter.md" },
|
||||
# { "URIs" = "contracts/uris.md" },
|
||||
# ] },
|
||||
# { "MCP" = "mcp_layout.md" },
|
||||
# { "Copilot" = "copilot.md" },
|
||||
# { "Usage" = "usage.md" },
|
||||
# { "Authoring" = "authoring.md" },
|
||||
# { "Future Work" = "future_work.md" },
|
||||
# { "Testing" = "testing.md" },
|
||||
# { "Security" = "securing.md" },
|
||||
# ] },
|
||||
# { "Prompts" = [
|
||||
# { "Authoring" = "prompts/authoring/PROMPT.md" },
|
||||
# { "JSFiddle Page Layout" = "prompts/jsfiddle-page-layout/PROMPT.md" },
|
||||
# { "NiceGUI Component Extraction" = "prompts/nicegui-component-extraction/PROMPT.md" },
|
||||
# { "Pytest Fill Scaffold" = "prompts/pytest-fill-scaffold/PROMPT.md" },
|
||||
# { "Pytest Scaffold" = "prompts/pytest-scaffold/PROMPT.md" },
|
||||
# { "Greenfield Architecture" = "prompts/greenfield-architecture/PROMPT.md" },
|
||||
# { "MCP Consumer Repo Shim" = "prompts/mcp-consumer-repo-shim/PROMPT.md" },
|
||||
# ] },
|
||||
# { "Skills" = [
|
||||
# { "Copilot" = [
|
||||
# { "Overview" = "skills/copilot-customization/SKILL.md" },
|
||||
# { "VS Code" = "skills/copilot-customization/references/vscode-customization.md" },
|
||||
# ] },
|
||||
# { "VS Code Config" = [
|
||||
# { "Overview" = "skills/vscode-configuration/SKILL.md" },
|
||||
# { "Debug Launch" = "skills/vscode-configuration/references/debug-launch-configurations.md" },
|
||||
# { "FastAPI Debug" = "skills/vscode-configuration/references/fastapi-debugpy-launch.md" },
|
||||
# { "Tasks" = "skills/vscode-configuration/references/tasks-json-configuration.md" },
|
||||
# ] },
|
||||
# { "FastAPI UV" = [
|
||||
# { "Overview" = "skills/fastapi-uv-docker/SKILL.md" },
|
||||
# { "Best" = "skills/fastapi-uv-docker/references/fastapi-best-practices.md" },
|
||||
# { "Layout" = "skills/fastapi-uv-docker/references/uv-project-layout.md" },
|
||||
# { "Uvicorn" = "skills/fastapi-uv-docker/references/uvicorn-settings.md" },
|
||||
# { "Docker" = "skills/fastapi-uv-docker/references/docker-cloud-native.md" },
|
||||
# ] },
|
||||
# { "Async SQLA" = [
|
||||
# { "Overview" = "skills/async-fastapi-sqlmodel/SKILL.md" },
|
||||
# { "Engine" = "skills/async-fastapi-sqlmodel/references/engine.md" },
|
||||
# { "Session" = "skills/async-fastapi-sqlmodel/references/session.md" },
|
||||
# { "FastAPI" = "skills/async-fastapi-sqlmodel/references/fastapi.md" },
|
||||
# { "Tx" = "skills/async-fastapi-sqlmodel/references/transactions.md" },
|
||||
# { "SQLModel" = "skills/async-fastapi-sqlmodel/references/sqlmodel.md" },
|
||||
# { "CRUD" = "skills/async-fastapi-sqlmodel/references/crud.md" },
|
||||
# { "Testing" = "skills/async-fastapi-sqlmodel/references/testing.md" },
|
||||
# { "IO" = "skills/async-fastapi-sqlmodel/references/implicit_io.md" },
|
||||
# { "Obs" = "skills/async-fastapi-sqlmodel/references/observability.md" },
|
||||
# { "Template" = "skills/async-fastapi-sqlmodel/references/template.md" },
|
||||
# ] },
|
||||
# { "NiceGUI" = [
|
||||
# { "Overview" = "skills/nicegui/SKILL.md" },
|
||||
# { "App Architecture" = "skills/nicegui/references/architecture.md" },
|
||||
# { "Startup" = "skills/nicegui/references/fastapi-uvicorn-startup.md" },
|
||||
# { "Visual Styling" = "skills/nicegui/references/styling-and-customization.md" },
|
||||
# { "Component Mechanics" = "skills/nicegui/references/component-mechanics.md" },
|
||||
# { "Tables" = "skills/nicegui/references/tables.md" },
|
||||
# { "Binding" = "skills/nicegui/references/binding-dataclasses.md" },
|
||||
# { "Flows" = "skills/nicegui/references/interaction-patterns.md" },
|
||||
# { "Quality" = "skills/nicegui/references/troubleshooting-and-quality-gates.md" },
|
||||
# { "Sources" = "skills/nicegui/references/source-documentation.md" },
|
||||
# ] },
|
||||
# { "Pytest" = [
|
||||
# { "Overview" = "skills/pytesting/SKILL.md" },
|
||||
# { "Docs" = "skills/pytesting/references/pytest-docs.md" },
|
||||
# { "AsyncIO" = "skills/pytesting/references/asyncio-testing.md" },
|
||||
# ] },
|
||||
# { "MCP Details" = [
|
||||
# { "Overview" = "skills/mcp-details/SKILL.md" },
|
||||
# { "Protocol" = "skills/mcp-details/references/mcp-protocol-and-spec.md" },
|
||||
# { "SDKs and FastMCP" = "skills/mcp-details/references/sdk-and-fastmcp.md" },
|
||||
# { "Ecosystem" = "skills/mcp-details/references/ecosystem-and-tooling.md" },
|
||||
# ] },
|
||||
# { "Logging" = [
|
||||
# { "Overview" = "skills/python-logging/SKILL.md" },
|
||||
# { "Docs" = "skills/python-logging/references/python-logging-docs.md" },
|
||||
# { "JSON File" = "skills/python-logging/references/json-file-logging.md" },
|
||||
# { "Network" = "skills/python-logging/references/network-logging-minimal-example.md" },
|
||||
# { "HTTPX" = "skills/python-logging/references/httpx-logging-handler-example.md" },
|
||||
# ] },
|
||||
# { "Pydantic Settings" = [
|
||||
# { "Overview" = "skills/pydantic-settings/SKILL.md" },
|
||||
# { "Source Docs" = "skills/pydantic-settings/references/source-documentation.md" },
|
||||
# { "Workflow" = "skills/pydantic-settings/references/implementation-workflow.md" },
|
||||
# ] },
|
||||
# { "Ruff" = [
|
||||
# { "Overview" = "skills/ruff-linting-formating/SKILL.md" },
|
||||
# { "Docs" = "skills/ruff-linting-formating/references/ruff-docs.md" },
|
||||
# { "Integrations" = "skills/ruff-linting-formating/references/ruff-integrations.md" },
|
||||
# ] },
|
||||
# { "Zensical" = [
|
||||
# { "Overview" = "skills/zensical-docs/SKILL.md" },
|
||||
# { "Features" = "skills/zensical-docs/references/zensical-features.md" },
|
||||
# { "Theme" = "skills/zensical-docs/references/theme-customization-and-icons.md" },
|
||||
# { "Quality" = "skills/zensical-docs/references/documentation-quality.md" },
|
||||
# { "IA" = "skills/zensical-docs/references/discoverability-and-ia.md" },
|
||||
# { "API Docs" = "skills/zensical-docs/references/code-heavy-docs-and-mkdocstrings.md" },
|
||||
# ] },
|
||||
# ] },
|
||||
# ]
|
||||
|
||||
# With the "extra_css" option you can add your own CSS styling to customize
|
||||
# your Zensical project according to your needs. You can add any number of
|
||||
|
||||
Reference in New Issue
Block a user