Reference

Utils

webfluid.utils — the grab bag the framework leans on internally and exposes for your own use: small helpers, the log factory and the exception hierarchy.

webfluid.utils (framework helpers)

  • enabled(key) — read a truthy environment switch.
  • safe_string(text) / camel_to_snake(text) / random_code(length) — string helpers.
  • async_result(value) — await it if awaitable, otherwise return as-is.
  • safe_execute(fn, reraise, *args) — call sync/async, optionally swallowing and logging exceptions.
  • run_in_executor(fn, *args, executor=None) — run a blocking call off the event loop, optionally on a pool of your own.
  • required_arg_count(fn) — the introspection behind the hook arity checks.
  • get_root_path(import_name), try_import(name) — import-location helpers. try_import returns None for a missing module but still raises when the module exists and its own imports fail.
  • parse_config(key, value) — the *_FILE resolution shared by wf run and the migration environment; read_config(path) — the parser both use, UTF-8 with a locale fallback and an empty parser for a missing file.
  • Version, check_required_version(requirement, version_type="framework", additive_version=None), check_priority(priority), build_sorted_tuple(data) — version and config plumbing.
  • add_proxy(target, base_url, ...), get_proxy(...), get_websocket_proxy(...), close_proxy_client() — the reverse-proxy utilities behind HMR. The HTTP one drops the upstream's hop-by-hop and encoding headers and recomputes the length for the body it forwards, while repeated headers such as Set-Cookie survive as separate lines. The websocket one awaits its cancelled pump tasks, so a dropped upstream is not an unretrieved task exception.

webfluid.utils.logging

The shared log factory:

example python 
from webfluid.utils.logging import factory as log

log.log("info line")
log.debug("...")
log.warning("...")
log.error("...")
log.exception(exc, "optional message")
  • factory — the singleton LogFactory. Logs only while a run is in execution, coloured to stdout and plain to stderr.
  • additive_context(fn) — routes a callable's logs through the Additive logger.
  • start_session() — sets up handlers and log level (called by the runtime).

webfluid.utils.cli

  • progress_bar(description, length, **kwargs) — a tqdm bar sized to the terminal. While one is open, log lines are written through it instead of over it.
  • download_file(url, dest) — a streamed download with a bar attached.

webfluid.utils.additives

  • id_check, version_check, type_check — the manifest field validators.
  • require_extensions(*names) — decorator that asserts the named extensions are enabled.
  • register_additives, installed_additives, installed_bases, import_base — the discovery and registry helpers (see the Additives reference).

webfluid.utils.countries

  • Country — an ISO 3166-1 alpha-2 StrEnum; DEFAULT_COUNTRY is the fallback code.
  • is_valid(code), coerce(code), normalize(code) — validate and canonicalise a code.
  • localized_names(locale=None) / options(locale=None) — Babel-localized country names / select options.
  • country_from_request(request=None, fallback=DEFAULT_COUNTRY) — resolve the visitor's country from geo headers.

webfluid.utils.ocean

  • Ocean — the HTTP client behind wf ocean (search, resolve, download, publish, ...).
  • load_token / save_token / delete_token / token_file — the token stored at ~/.wf-ocean.
  • extract_archive(data, target), humanize_error(detail) — archive extraction and human-readable error-code messages.

webfluid.exceptions

  • FrameworkException — the root of all framework errors.
  • FrontendException → NodeError, TailwindError.
  • AdditiveException → ManifestError.
  • OceanError — raised by the Ocean client; carries status and detail.

That's a wrap

You've gone from a single main.py to the full surface of WebFluid. Keep the overview handy for the known issues this beta ships with, pin your version, and go build something liquid.