Reference

Extensions

webfluid.extensions — the base extension and the battery set. All of them follow the same shape: a class with an expand_fluid method, instantiated once and reachable through webfluid.core.ext.

FluidExtension

from webfluid.extensions import FluidExtension — the base class for all extensions.

  • expand_fluid(fluid, *args) — override to hook into the app; called automatically when an extension is constructed with a fluid.
  • cli_entry(app, name) — mounts the extension's _cli Typer app under wf.

SQLAlchemy

  • Model — the declarative base; resolves __tablename__ from the snake-cased class name, supports __bind_key__ and Model.set_bind(key).
  • executor(bind_key=None, model=None) / async_executor(...) — context managers yielding an executor with exec, insert, delete, flush; commit/rollback handled for you.
  • ensured_executor(...) / ensured_async_executor(...) — reuse an already-open executor or open a fresh one; current_executor / current_async_executor reach the active one.
  • The executors subclass BaseContext, so current() and outer() (see Core) work on them too; db.bind_keys lists the configured binds.
  • exec(statement, scalars=True) — returns a ScalarResult by default; pass scalars=False for the raw Result.
  • get_bind_for_model(model) / get_bind(key) — resolve the Bind (with sync_engine / async_engine and its own metadata) for a model or key.
  • Config: SQLALCHEMY_DATABASE_URI, SQLALCHEMY_BINDS. Drivers are derived; don't put them in the uri.

Babel

  • gettext, ngettext, pgettext, npgettext and their lazy_* variants.
  • locale_selector(fn) / timezone_selector(fn) — register custom resolvers.
  • force(locale, timezone) / aforce(...) — context managers to pin locale/timezone.
  • register_domain(name, package=None) / update_translations(domain, translations) — runtime, db-backed catalogs.
  • load_locale(locale), extract() (CLI), and the helpers in webfluid.extensions.babel.utils (translation_resolver, get_locale, and the format_date / format_currency / ... filters).
  • Companions: Domain, I18nKey / I18nMessage (the translation models), LazyString.

Security

Reached through webfluid.core.ext.security; needs EXT_SECURITY and EXT_SQLALCHEMY.

  • user_service — the current-user dependencies (current_user, require_user, require_2fa, require_admin) and the require_roles / require_permissions (plus _any_) guard factories.
  • hash_service — argon2 hash(password) / verify(hash, password).
  • token_service — CSRF (csrf_protect, csrf_response) and signed one-time tokens (generate_token, validate_token).
  • oauth_service — authlib-backed social login, configured with SECURITY_OAUTH_CLIENTS.
  • Models in webfluid.extensions.security.models: User, Identity, Role, Permission, TOTPSecret, WebAuthnCredential, BackupCode; validators validate_username / validate_password.

EventManager

  • create_signal(name, singleton=False, internal=False) — declare an event channel.
  • event(name, ...) / query(name, ...) — decorators registering handlers; internal=False exposes them to the browser.
  • trigger(event, data) — publish; request(query, data) — ask and await a result; listen(event) — async stream.
  • Client: window.wf.ext.events.EventManager.

Mail

  • send(to, subject, body, ...) — body is a MIME-subtype map; threads delivery by default (fake_async).
  • send_async(...) — the awaited variant. Both accept attachments, cc, bcc, from_email.
  • make_message(...), client() / async_client() — raw message building and bare SMTP connections.

Cache

  • set / get / delete / clear and the async aset / aget / adelete / aclear.
  • Backends selected by CACHE_TYPE: legacy (in-memory, needs the scheduler) or redis.

JWTManager

  • encode(payload, audience="default") / decode(token, ...) and the async aencode / adecode.
  • Requires EXT_SCHEDULING and EXT_CACHE; rotates its signing secret on a schedule and keeps recent ones in the cache.

Migrate

A CLI-only extension (wf migrate ...) wrapping Alembic:

  • init <app> — enroll the matching single- or multi-db template.
  • revision <app> [-a] [-m] — create a revision (optionally autogenerated).
  • upgrade <app> / downgrade <app> [-r] — apply / revert migrations.

Continue reading

From here you can continue straight with Surface.