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.
  • exec(statement, scalars=True) — returns a ScalarResult by default; pass scalars=False for the raw Result.
  • get_bind_for_model(model) — resolves the _Bind (with sync_engine / async_engine) for a model.
  • 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 formatting filters from webfluid.extensions.utils.babel (format_date, format_currency, ...).
  • Companions: Domain, I18nMessage (the translation model), LazyString.

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.