API Reference¶

Register a BaseService into the managed lifecycle.

connect() runs at boot (registration order); disconnect() at shutdown (reverse). Registering after boot connects immediately is not supported — register before boot().

Bootstrap the framework's baseline providers without a project base_path.

Convenience for test setups that need a minimal Application with container bindings but don't need a full project directory. Production code should use Application.configure(base_path).create() instead.

Resolve a named binding from the container.

Yield each registered ServiceProvider instance, in registration order.

Used by ConsoleServiceProvider.boot to collect commands from every provider without reaching into _provider_instances directly.

Produce a fully wired ASGI app. The framework owns the lifecycle.

Boot and shutdown are driven by the ASGI lifespan protocol, not by this factory call. That keeps the method loop-agnostic — it works the same whether called from a plain sync entrypoint or from inside a uvicorn --factory callback (which uvicorn invokes from within its own running event loop).

Behaviour:

• Always returns a configured FastAPI instance (re-exported as arvel.ASGIApp). Routes are mounted, the exception handler is wired, and the container is stashed on app.state.arvel_container.
• When lifespan is omitted, wires a default lifespan that calls await self.boot() on startup (skipped if already booted) and await self.shutdown() on graceful exit.
• When lifespan is provided, uses it verbatim — the caller takes ownership of boot and shutdown.
• **fastapi_kwargs are forwarded verbatim to the FastAPI constructor (e.g. docs_url, redoc_url, openapi_url, title, version).

The returned app expects to be driven by a lifespan-aware ASGI host (uvicorn, hypercorn, Starlette TestClient used as a context manager). Routing still works without a lifespan, but providers will not have booted.

Register routing file paths to be loaded at register time.

   ``web`` and ``api`` are loaded by ``HttpServiceProvider.register``.
   ``console`` is stored on the application but not loaded until the
   Console provider ships.

   At least one of the three must be non-None. Subsequent calls

accumulate (last-write-wins per key).

Discover and load every .py config file in path at register() time.

See arvel.application._loader.discover_config_files for the discovery rules and arvel.config.lookup for the runtime accessor. Files are loaded under namespaced module names so a user's config/logging.py never shadows stdlib logging.

Resolve cls from the container, then call method with injected params.

Parameters are resolved from the container; overrides bypass injection for the specified parameter names. If cls is not bound, instantiates it directly (no-arg constructor assumed).

Async variant of call() — supports async methods and async-resolved deps.

Snapshot of currently registered global parameter resolvers.

Register a named middleware group.

Register a single named middleware.

Return Laravel-style rules applied after Pydantic parsing.

Custom messages keyed as field.rule (e.g. email.unique).

Human-readable field names substituted into error messages.

Register conditional rules on validator (e.g. Rule.sometimes).

Merge extra root-level keys into the dict returned by to_dict.

Extras win on key clashes. Chainable.

Wrap resources (a list or any paginator) in a ResourceCollection.

With a list, the output is {"data": [...]} — overridable via ResourceCollection.wrap. With a paginator, the output mirrors the paginator's own {data, meta, links} envelope with each item transformed by this resource class.

Return value when condition is truthy, otherwise a missing sentinel.

The sentinel is stripped from the dict returned by to_dict() automatically.

Return the relation value if it's already in the resource's __dict__.

Never triggers a lazy load — safe to call on SQLAlchemy models.

Return data when condition is truthy, otherwise an empty dict.

Build a Starlette JSON response from to_dict(request).

Merge extra root-level keys into the envelope returned by to_dict.

Extras win on key clashes — they merge after the default envelope (or the paginator's envelope) is built. Chainable.

Build a Starlette JSON response from to_dict(request).

Override in stateful guards. Stateless guards (JWT, Token) ignore this.

Override in stateful guards. Stateless guards ignore this.

Mint a short-lived access JWT (typ=access).

Used by the upcoming AuthBroker to mint the access leg of the access+refresh token pair. Refresh tokens are opaque (not JWTs) and live in the refresh_tokens table via :class:RefreshToken.

Register a foreign exception → HttpException translator.

Resolve a config class from the container; return default on any failure.

Use this when config is optional — the provider falls back to a safe default when the application hasn't registered the settings class.

Sync. Container bindings only — no I/O, no other providers.

Async. May do I/O. Runs after every provider's register().

Async. Tear down resources. Runs in reverse registration order.

Console commands shipped by this provider.

Each item may be either a Command subclass (instantiated with no args by ConsoleServiceProvider.boot) or a pre-built Command instance (used when the provider needs to inject dependencies that come from the container).

Abstracts this provider promises to bind. Used by deferred-provider logic (future WI).

Register source-to-destination publishables under tag.

Mirrors Laravel's $this->publishes([...], 'tag'). Consumers run arvel vendor:publish --tag=<tag> (or --provider=<class>) to copy the registered files into their app.

Parameters¶

paths: Mapping of source file path → destination path. Both may be str or Path. Relative destinations resolve against Application.base_path. tag: Group label used by vendor:publish --tag=.... is_migrations: When True, each destination is treated as a target directory and the basename is rewritten with a UTC timestamp at publish time so the file lands chronologically in database/migrations/.

Flatten nested lists/tuples. depth=-1 (default) flattens fully.

Flatten a nested mapping into a.b.c keys.

Inverse of :meth:dot — rebuild nested dicts from dotted keys.

Normalize None/scalar/tuple to a list. Returns list[Any] by design.

Cryptographically secure shuffle. For deterministic shuffles use random.Random.

PascalCase; Laravel calls this Str::studly.

Naive English pluralization used by the code generators.

post → posts, category → categories. Already-plural words (trailing s) are left alone. Irregulars (person, child) aren't handled — override the table name when it matters.

hello_world_greeting / helloWorld → Hello World ….

Generate a cryptographically secure random password string.

Matches Laravel's Str::password — returns the password plaintext, not a hash. Pass the result to Hash.make() to store it.