`
c.Table(
data=users,
# define two columns for the table
columns=[
# the first is the users, name rendered as a link to their profile
DisplayLookup(field='name', on_click=GoToEvent(url='/user/{id}/')),
# the second is the date of birth, rendered as a date
DisplayLookup(field='dob', mode=DisplayMode.date),
],
),
]
),
]
@app.get("/api/user/{user_id}/", response_model=FastUI, response_model_exclude_none=True)
def user_profile(user_id: int) -> list[AnyComponent]:
"""
User profile page, the frontend will fetch this when the user visits `/user/{id}/`.
"""
try:
user = next(u for u in users if u.id == user_id)
except StopIteration:
raise HTTPException(status_code=404, detail="User not found")
return [
c.Page(
components=[
c.Heading(text=user.name, level=2),
c.Link(components=[c.Text(text='Back')], on_click=BackEvent()),
c.Details(data=user),
]
),
]
@app.get('/{path:path}')
async def html_landing() -> HTMLResponse:
"""Simple HTML page which serves the React app, comes last as it matches all paths."""
return HTMLResponse(prebuilt_html(title='FastUI Demo'))
```
Which renders like this:
Of course, that's a very simple application, the [full demo](https://fastui-demo.onrender.com) is more complete.
### The Principle (long version)
FastUI is an implementation of the RESTful principle; but not as it's usually understood, instead I mean the principle defined in the original [PhD dissertation](https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) by Roy Fielding, and excellently summarised in [this essay on htmx.org](https://htmx.org/essays/how-did-rest-come-to-mean-the-opposite-of-rest/) (HTMX people, I'm sorry to use your article to promote React which I know you despise 🙏).
The RESTful principle as described in the HTMX article is that the frontend doesn't need to (and shouldn't) know anything about the application you're building. Instead, it should just provide all the components you need to construct the interface, the backend can then tell the frontend what to do.
Think of your frontend as a puppet, and the backend as the hand within it — the puppet doesn't need to know what to say, that's kind of the point.
Building an application this way has a number of significant advantages:
- You only need to write code in one place to build a new feature — add a new view, change the behavior of an existing view or alter the URL structure
- Deploying the front and backend can be completely decoupled, provided the frontend knows how to render all the components the backend is going to ask it to use, you're good to go
- You should be able to reuse a rich set of opensource components, they should end up being better tested and more reliable than anything you could build yourself, this is possible because the components need no context about how they're going to be used (note: since FastUI is brand new, this isn't true yet, hopefully we get there)
- We can use Pydantic, TypeScript and JSON Schema to provide guarantees that the two sides are communicating with an agreed schema
In the abstract, FastUI is like the opposite of GraphQL but with the same goal — GraphQL lets frontend developers extend an application without any new backend development; FastUI lets backend developers extend an application without any new frontend development.
#### Beyond Python and React
Of course, this principle shouldn't be limited to Python and React applications — provided we use the same set of agreed schemas and encoding to communicate, we should be able to use any frontend and backend that implements the schema. Interchangeably.
This could mean:
- Implementing a web frontend using another JS framework like Vue — lots of work, limited value
- Implementing a web frontend using an edge server, so the browser just sees HTML — lots of work but very valuable
- Implementing frontends for other platforms like mobile or IOT — lots of work, no idea if it's actually a good idea?
- Implementing the component models in another language like Rust or Go — since there's actually not that much code in the backend, so this would be a relatively small and mechanical task
================================================
FILE: docs/plugins.py
================================================
import os
import re
from typing import Match
from mkdocs.config import Config
from mkdocs.structure.files import Files
from mkdocs.structure.pages import Page
try:
import pytest
except ImportError:
pytest = None
def on_pre_build(config: Config):
pass
def on_files(files: Files, config: Config) -> Files:
return remove_files(files)
def remove_files(files: Files) -> Files:
to_remove = []
for file in files:
if file.src_path in {'plugins.py'}:
to_remove.append(file)
elif file.src_path.startswith('__pycache__/'):
to_remove.append(file)
for f in to_remove:
files.remove(f)
return files
def on_page_markdown(markdown: str, page: Page, config: Config, files: Files) -> str:
markdown = remove_code_fence_attributes(markdown)
return add_version(markdown, page)
def add_version(markdown: str, page: Page) -> str:
if page.file.src_uri == 'index.md':
version_ref = os.getenv('GITHUB_REF')
if version_ref and version_ref.startswith('refs/tags/'):
version = re.sub('^refs/tags/', '', version_ref.lower())
url = f'https://github.com/pydantic/FastUI/releases/tag/{version}'
version_str = f'Documentation for version: [{version}]({url})'
elif sha := os.getenv('GITHUB_SHA'):
sha = sha[:7]
url = f'https://github.com/pydantic/FastUI/commit/{sha}'
version_str = f'Documentation for development version: [{sha}]({url})'
else:
version_str = 'Documentation for development version'
markdown = re.sub(r'{{ *version *}}', version_str, markdown)
return markdown
def remove_code_fence_attributes(markdown: str) -> str:
"""
There's no way to add attributes to code fences that works with both pycharm and mkdocs, hence we use
`py key="value"` to provide attributes to pytest-examples, then remove those attributes here.
https://youtrack.jetbrains.com/issue/IDEA-297873 & https://python-markdown.github.io/extensions/fenced_code_blocks/
"""
def remove_attrs(match: Match[str]) -> str:
suffix = re.sub(
r' (?:test|lint|upgrade|group|requires|output|rewrite_assert)=".+?"', '', match.group(2), flags=re.M
)
return f'{match.group(1)}{suffix}'
return re.sub(r'^( *``` *py)(.*)', remove_attrs, markdown, flags=re.M)
================================================
FILE: mkdocs.yml
================================================
site_name: FastUI
site_description: Build web application user interfaces defined by declarative Python code.
site_url: https://docs.pydantic.dev/fastui/
theme:
name: 'material'
palette:
- media: "(prefers-color-scheme: light)"
scheme: default
primary: pink
accent: pink
toggle:
icon: material/lightbulb-outline
name: "Switch to dark mode"
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: pink
accent: pink
toggle:
icon: material/lightbulb
name: "Switch to light mode"
features:
- content.code.annotate
- content.tabs.link
- content.code.copy
- announce.dismiss
- navigation.tabs
- search.suggest
- search.highlight
logo: assets/logo-white.svg
favicon: assets/favicon.png
repo_name: pydantic/FastUI
repo_url: https://github.com/pydantic/FastUI
edit_uri: ''
# https://www.mkdocs.org/user-guide/configuration/#validation
validation:
omitted_files: warn
absolute_links: warn
unrecognized_links: warn
extra_css:
- 'extra/tweaks.css'
# TODO: add flarelytics support
# extra_javascript:
# - '/flarelytics/client.js'
markdown_extensions:
- toc:
permalink: true
- admonition
- pymdownx.details
- pymdownx.extra
- pymdownx.superfences
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- attr_list
- md_in_html
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
watch:
- src
plugins:
- search
- mkdocstrings:
handlers:
python:
paths:
- src/python-fastui
options:
members_order: source
separate_signature: true
docstring_options:
ignore_init_summary: true
merge_init_into_class: true
show_signature_annotations: true
signature_crossrefs: true
- mkdocs-simple-hooks:
hooks:
on_pre_build: 'docs.plugins:on_pre_build'
on_files: 'docs.plugins:on_files'
on_page_markdown: 'docs.plugins:on_page_markdown'
nav:
- Introduction: index.md
- Guide: guide.md
- API Documentation:
- Python Components: api/python_components.md
- TypeScript Components: api/typescript_components.md
================================================
FILE: package.json
================================================
{
"name": "FastUI",
"private": true,
"type": "module",
"workspaces": [
"src/*"
],
"scripts": {
"dev": "npm run --workspace=@pydantic/fastui-prebuilt dev",
"build": "npm run --workspaces prepublishOnly",
"typecheck": "npm run --workspaces typecheck",
"lint": "eslint src --ext .ts,.tsx --report-unused-disable-directives --max-warnings 0",
"lint-fix": "npm run lint -- --fix",
"prettier": "prettier --write",
"format": "npm run prettier -- . && npm run lint-fix",
"generate-json-schema": "./src/python-fastui/tests/react-fastui-json-schema.sh"
},
"prettier": {
"singleQuote": true,
"semi": false,
"trailingComma": "all",
"tabWidth": 2,
"printWidth": 119,
"bracketSpacing": true
},
"devDependencies": {
"@types/node": "^20.9.1",
"@types/react": "^18.2.15",
"@types/react-dom": "^18.2.7",
"@typescript-eslint/eslint-plugin": "^6.0.0",
"@typescript-eslint/parser": "^6.0.0",
"eslint": "^8.53.0",
"eslint-config-prettier": "^9.0.0",
"eslint-config-standard": "^17.1.0",
"eslint-plugin-react": "^7.33.2",
"eslint-plugin-react-hooks": "^4.6.0",
"eslint-plugin-react-refresh": "^0.4.4",
"eslint-plugin-simple-import-sort": "^10.0.0",
"json-schema-to-typescript": "^15.0.4",
"typescript": "^5.0.2"
},
"dependencies": {
"prettier": "^3.2.5",
"typedoc": "^0.25.13"
}
}
================================================
FILE: pyproject.toml
================================================
# this is not the used for the python package "fastui",
# for that see packages/python-fastui/pyproject.toml
[tool.ruff]
line-length = 120
extend-select = ["Q", "RUF100", "UP", "I"]
flake8-quotes = {inline-quotes = "single", multiline-quotes = "double"}
format.quote-style="single"
target-version = "py310"
[tool.pyright]
include = ["src/python-fastui/fastui"]
[tool.pytest.ini_options]
testpaths = [
"src/python-fastui/tests",
"demo/tests.py",
]
xfail_strict = true
filterwarnings = ["error"]
asyncio_mode = "auto"
[tool.coverage.run]
source = ["src/python-fastui/fastui"]
omit = [
"src/python-fastui/fastui/__main__.py",
"src/python-fastui/fastui/generate_typescript.py",
]
[tool.coverage.report]
precision = 2
exclude_lines = [
'pragma: no cover',
'raise NotImplementedError',
'if TYPE_CHECKING:',
'if typing.TYPE_CHECKING:',
'@overload',
'@typing.overload',
'\(Protocol\):$',
]
================================================
FILE: requirements/docs.in
================================================
mkdocs
mkdocs-material
mkdocs-simple-hooks
mkdocstrings[python]
mkdocs-redirects
mkdocs-material-extensions
================================================
FILE: requirements/docs.txt
================================================
#
# This file is autogenerated by pip-compile with Python 3.11
# by the following command:
#
# pip-compile --output-file=requirements/docs.txt requirements/docs.in
#
babel==2.14.0
# via mkdocs-material
certifi==2024.2.2
# via requests
charset-normalizer==3.3.2
# via requests
click==8.1.7
# via
# mkdocs
# mkdocstrings
colorama==0.4.6
# via
# griffe
# mkdocs-material
ghp-import==2.1.0
# via mkdocs
griffe==0.44.0
# via mkdocstrings-python
idna==3.7
# via requests
jinja2==3.1.3
# via
# mkdocs
# mkdocs-material
# mkdocstrings
markdown==3.6
# via
# mkdocs
# mkdocs-autorefs
# mkdocs-material
# mkdocstrings
# pymdown-extensions
markupsafe==2.1.5
# via
# jinja2
# mkdocs
# mkdocs-autorefs
# mkdocstrings
mergedeep==1.3.4
# via mkdocs
mkdocs==1.5.3
# via
# -r requirements/docs.in
# mkdocs-autorefs
# mkdocs-material
# mkdocs-redirects
# mkdocs-simple-hooks
# mkdocstrings
mkdocs-autorefs==1.0.1
# via mkdocstrings
mkdocs-material==9.5.18
# via -r requirements/docs.in
mkdocs-material-extensions==1.3.1
# via
# -r requirements/docs.in
# mkdocs-material
mkdocs-redirects==1.2.1
# via -r requirements/docs.in
mkdocs-simple-hooks==0.1.5
# via -r requirements/docs.in
mkdocstrings[python]==0.24.3
# via
# -r requirements/docs.in
# mkdocstrings-python
mkdocstrings-python==1.10.0
# via mkdocstrings
packaging==24.0
# via mkdocs
paginate==0.5.6
# via mkdocs-material
pathspec==0.12.1
# via mkdocs
platformdirs==4.2.0
# via
# mkdocs
# mkdocstrings
pygments==2.17.2
# via mkdocs-material
pymdown-extensions==10.8
# via
# mkdocs-material
# mkdocstrings
python-dateutil==2.9.0.post0
# via ghp-import
pyyaml==6.0.1
# via
# mkdocs
# pymdown-extensions
# pyyaml-env-tag
pyyaml-env-tag==0.1
# via mkdocs
regex==2024.4.16
# via mkdocs-material
requests==2.31.0
# via mkdocs-material
six==1.16.0
# via python-dateutil
urllib3==2.2.1
# via requests
watchdog==4.0.0
# via mkdocs
================================================
FILE: src/npm-fastui/LICENSE
================================================
The MIT License (MIT)
Copyright (c) 2023 to present Pydantic Services inc.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================
FILE: src/npm-fastui/README.md
================================================
# FastUI
React frontend for [FastUI](https://github.com/pydantic/FastUI).
================================================
FILE: src/npm-fastui/package.json
================================================
{
"name": "@pydantic/fastui",
"version": "0.0.26",
"description": "Build better UIs faster.",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"author": "Samuel Colvin",
"license": "MIT",
"homepage": "https://github.com/pydantic/fastui",
"private": false,
"keywords": [
"fastui",
"jsx",
"typescript",
"react",
"fastapi"
],
"scripts": {
"prepublishOnly": "rm -rf dist && tsc",
"typecheck": "tsc --noEmit",
"typewatch": "tsc --noEmit --watch"
},
"dependencies": {
"@microsoft/fetch-event-source": "^2.0.1",
"react": "^18.2.0",
"react-dom": "^18.2.0",
"react-markdown": "^9.0.1",
"react-select": "^5.8.0",
"react-syntax-highlighter": "^15.5.0",
"remark-gfm": "^4.0.0"
},
"devDependencies": {
"@types/react-syntax-highlighter": "^15.5.10"
}
}
================================================
FILE: src/npm-fastui/src/Defaults.tsx
================================================
import { FC, ReactNode } from 'react'
export const DefaultNotFound: FC<{ url: string }> = ({ url }) =>
Page not found: {url}
// default here does nothing
export const DefaultTransition: FC<{ children: ReactNode; transitioning: boolean }> = ({ children }) => (
{children}
)
================================================
FILE: src/npm-fastui/src/components/Code.tsx
================================================
import { lazy } from 'react'
export const CodeComp = lazy(() => import('./CodeLazy'))
================================================
FILE: src/npm-fastui/src/components/CodeLazy.tsx
================================================
import * as codeStyles from 'react-syntax-highlighter/dist/esm/styles/prism'
import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter'
import type { Code } from '../models'
import { useClassName } from '../hooks/className'
export default function (props: Code) {
const { text, language, codeStyle } = props
const codeLookup = codeStyle as keyof typeof codeStyles
const style = (codeStyle && codeStyles[codeLookup]) || codeStyles.coldarkCold
return (
{text}
)
}
================================================
FILE: src/npm-fastui/src/components/Custom.tsx
================================================
import { FC } from 'react'
import type { Custom } from '../models'
import { DisplayError } from '../hooks/error'
import { JsonComp } from './Json'
export const CustomComp: FC = (props) => {
const { data, subType, library } = props
const description = [`The custom component "${subType}"`]
if (library) {
description.push(`from library "${library}"`)
}
description.push(`has no implementation with this frontend app.`)
return (
Custom component data:
)
}
================================================
FILE: src/npm-fastui/src/components/FireEvent.tsx
================================================
import { FC, useEffect } from 'react'
import type { FireEvent } from '../models'
import { useFireEvent } from '../events'
export const FireEventComp: FC = ({ event, message }) => {
const { fireEvent } = useFireEvent()
useEffect(() => {
// debounce the event so changes to fireEvent (from location changes) don't trigger the event many times
const clear = setTimeout(() => fireEvent(event), 50)
return () => clearTimeout(clear)
}, [fireEvent, event])
return <>{message}
}
================================================
FILE: src/npm-fastui/src/components/FormField.tsx
================================================
import { FC, useState } from 'react'
import AsyncSelect from 'react-select/async'
import Select, { StylesConfig } from 'react-select'
import type {
FormFieldInput,
FormFieldTextarea,
FormFieldBoolean,
FormFieldFile,
FormFieldSelect,
FormFieldSelectSearch,
SelectOption,
SelectOptions,
SelectGroup,
} from '../models'
import { useClassName } from '../hooks/className'
import { debounce, useRequest } from '../tools'
type PrivateOnChange = () => void
interface FormFieldInputProps extends FormFieldInput {
onChange?: PrivateOnChange
}
export const FormFieldInputComp: FC = (props) => {
const { name, placeholder, required, htmlType, locked, autocomplete, onChange } = props
return (