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) — run a blocking call off the event loop.
  • required_arg_count(fn) / is_async_function(fn) — introspection used by the hook validators.
  • get_root_path(import_name), try_import(name) — import-location helpers.
  • check_required_version(requirement, ...), 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.

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.
  • 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.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 alpha ships with, pin your version, and go build something liquid.