--- title: "Reference" section: "Reference" framework: WebFluid package: webfluid version: "1.0.0b3" stage: "beta" released: "August 17, 2026" canonical: "https://docs.webfluid.dev/latest/ref.md" html: "https://docs.webfluid.dev/latest/ref" audience: ai-agent format: markdown --- # Reference A terse map of every name WebFluid exports, grouped by where it lives. Use it to look a symbol up without reading prose. The five sub-pages are [Core](/latest/ref/core.md), [Extensions](/latest/ref/extensions.md), [Surface](/latest/ref/surface.md), [Additives](/latest/ref/additives.md) and [Utils](/latest/ref/utils.md). ## Stability contract > **RULE** — From this beta onwards, everything listed in a package's __all__ follows semantic versioning. Anything else — module layout, private attributes, helpers that are not exported — is internal and may move in any release. Import from the documented paths, and keep your version pinned while the beta runs. ## Lazy exports Every package in the tree resolves its exports through a module-level `__getattr__`: ```python def __getattr__(name): if name == "Fluid": from .fluid import Fluid return Fluid ... raise AttributeError(name) def __dir__(): return sorted(__all__) ``` Three consequences: 1. `import webfluid` does not drag the whole framework into memory. 2. An extension you never enable is never instantiated. 3. `dir(package)` is the honest list of what it offers — use it to discover the surface. ## The import tree ```text webfluid ├── Fluid, Additive, Manifest, version ├── core │ ├── Fluid, Additive, Manifest │ ├── config register_config, Config, DefaultConfig │ ├── context BaseContext, FluidContext │ ├── ext scheduler, db, babel, security, events, cache, mail, jwt │ └── constants DEBUG, EXECUTION, the EXT_*/WF_* flags, static prefixes, hub urls ├── extensions │ ├── FluidExtension │ ├── SQLAlchemy, Babel, Security, EventManager, Mail, Cache, JWTManager │ ├── babel Domain, Translations, I18nMessage, LazyString, the formatters │ ├── cache BaseCache, Cache │ ├── sqlalchemy Model, Bind, Executor, AsyncExecutor, database_uris │ └── security services, models, utils ├── surface │ ├── dist, Frontend │ ├── load_node, node_cli, node_cmd, node_proc │ └── load_tailwind, generate_tailwind_css, generate_tailwind_asset, tailwind_cmd, tailwind_cli ├── utils │ ├── enabled, safe_string, camel_to_snake, random_code, get_root_path, parse_config │ ├── required_arg_count, async_result, safe_execute, run_in_executor │ ├── check_priority, build_sorted_tuple, try_import, read_config, in_running_loop │ ├── Version, check_required_version │ ├── get_proxy, get_websocket_proxy, add_proxy, close_proxy_client │ ├── additives, ocean, countries, logging, cli, surface ├── fluid the framework's own templates, static and i18n └── exceptions FrameworkException and its children ``` ## Top-level exports ```python from webfluid import Fluid, Additive, Manifest, version from webfluid import utils, fluid, extensions, exceptions ``` | Name | What it is | |------------|----------------------------------------------------------------------------| | `Fluid` | The application class, a `FastAPI` subclass. [Core](/latest/ref/core.md) | | `Additive` | A self-contained sub-app. [Additives](/latest/ref/additives.md) | | `Manifest` | A parsed `manifest.json`. [Additives](/latest/ref/additives.md) | | `version` | A callable returning the running framework version as a `Version` | ## Where to import what | You need | Import from | |-------------------------------------|--------------------------------------------------| | The app class | `webfluid` | | A battery instance | `webfluid.core.ext` | | The request context | `webfluid.core.context` | | Config registration | `webfluid.core.config` | | Runtime flags | `webfluid.core.constants` | | `Model`, executors, `database_uris` | `webfluid.extensions.sqlalchemy` | | Security models and validators | `webfluid.extensions.security.models` / `.utils` | | Babel helpers and formatters | `webfluid.extensions.babel.utils` | | The log factory | `webfluid.utils.logging` | | Additive registry helpers | `webfluid.utils.additives` | | Exceptions | `webfluid.exceptions` | > **WARNING** — Do not import from a module path that is not in the tree above — for example webfluid.core.fluid.main or webfluid.extensions.security.services.user.gating. Those are internal and are free to move between releases. ## The agent skill in the package `webfluid/.agents/skills/webfluid` ships inside the distribution: a `SKILL.md` plus `references/project-setup.md`, `runtime.md`, `batteries.md`, `additives.md`, `frontend.md` and `pitfalls.md`. If you are working in a repository where `webfluid` is installed, that is the local copy of this material, cut for editing a codebase rather than reading one. > **RULE** — These docs are the authority on exhaustive detail (full config tables, complete API surfaces, the release-accurate defect list); the packaged skill is the authority on what the installed version does. When the installed version is newer than the published latest, the package's own CHANGELOG.md is the authority on the delta. ## Next - [`ref/core.md`](/latest/ref/core.md) — `Fluid`, config, context, `core.ext`, constants. --- ## Navigation - [Overview](/latest/.md) — what WebFluid is, how to navigate these docs, release state and known bugs - [Getting Started](/latest/get-started.md) — install, minimal app, the layout the framework expects **Configuration** - [App configs](/latest/config/app-config.md) — `app_configs/.ini`, switches, `*_FILE` secrets, `[dev]` - [Config classes](/latest/config/config-class.md) — `register_config`, `DefaultConfig`, every framework key **Extensions** - [Introduction](/latest/ext/base.md) — `FluidExtension`, entry points, `expand_fluid` - [Scheduling](/latest/ext/scheduling.md) — APScheduler `AsyncIOScheduler` - [SQLAlchemy](/latest/ext/sqlalchemy.md) — `Model`, executors, binds, sessions - [Migrate](/latest/ext/migrate.md) — Alembic wrapper, `prepare_fluid`, single/multi-db - [Mail](/latest/ext/mailman.md) — SMTP, sync/async, batching, attachments - [Babel](/latest/ext/babel.md) — gettext, domains, locale selection, formatters - [Security](/latest/ext/security.md) — users, gates, CSRF, tokens, OAuth, bearer grants - [Events](/latest/ext/events.md) — signals, events, queries, browser socket - [Cache](/latest/ext/cache.md) — redis / legacy backends - [JWTManager](/latest/ext/jwt.md) — encode/decode, rotation, revocation **Frontend (surface)** - [Introduction](/latest/surface/tooling.md) — feature switches, `fluid_base.html`, Tailwind, themes - [Integration](/latest/surface/frontend.md) — `APP_FRONTEND`, htmx, Vite workspaces - [Template resolution](/latest/surface/jinja.md) — loader order, namespaces, overriding **Additives** - [Introduction](/latest/additives/intro.md) — manifest, routers, enabling - [Base Additives](/latest/additives/base.md) — `type: base`, `import_base`, extension semantics - [Interaction between](/latest/additives/contract.md) — events/queries as contracts, requirements, packaging **Framework utility** - [Lifecycle](/latest/utils/lifecycle.md) — `mix()`, startup/shutdown hooks, graceful stop - [Runtime](/latest/utils/runtime.md) — `FluidContext`, request hooks, themes, proxy, rate limits - [Logging](/latest/utils/logging.md) — the log factory, levels, files, additive attribution **CLI** - [Introduction](/latest/cli/wf.md) — command tree, extension CLIs - [Create](/latest/cli/create.md) — `wf create project/app/additive` - [Run](/latest/cli/run.md) — `wf run`, flags, debug and interactive mode - [Ocean](/latest/cli/ocean.md) — search, install, publish **Reference** - [Overview](/latest/ref.md) — package layout, stability contract - [Core](/latest/ref/core.md) — `Fluid`, config, context, `core.ext`, constants - [Extensions](/latest/ref/extensions.md) — the battery API surface - [Surface](/latest/ref/surface.md) — `Frontend`, Node and Tailwind tooling - [Additives](/latest/ref/additives.md) — `Additive`, `Router`, `Manifest`, registry helpers - [Utils](/latest/ref/utils.md) — helpers, logging, exceptions