THE ORIONIS API
Build with clarity.
Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.
class AuthManager(IAuthManager): (source)
Constructor: AuthManager(app, authorizer, permissions, session_guard, ...)
Expose authentication and authorization to application code.
The manager owns no per request state. user(), can() and friends read the context bound to the container scope of the running request, so registering the manager as a singleton is safe even though several requests share it concurrently.
Concurrency
Guards, the authorizer and the repositories are stateless. Login and logout mutate the session of their own request and rebind the context of that scope only, so a request can never observe the identity of another one.
| Static Method | __request |
Return the request bound to the current container scope. |
| Method | __init__ |
Initialise the manager with the configured collaborators. |
| Method | __rebind |
Bind a freshly authenticated identity to the current scope. |
| Async Method | allows |
Evaluate a policy ability against a resource. |
| Async Method | attempt |
Authenticate the current request from submitted credentials. |
| Async Method | authorization |
Return the effective authorization snapshot of the request. |
| Async Method | authorize |
Require a permission or abort the current operation. |
| Async Method | authorize |
Require a policy ability or abort the current operation. |
| Async Method | can |
Report whether the current request grants a permission. |
| Async Method | can |
Report whether every permission is granted. |
| Async Method | can |
Report whether at least one permission is granted. |
| Async Method | cannot |
Report whether the current request lacks a permission. |
| Method | check |
Report whether the current request is authenticated. |
| Method | context |
Return the authentication context of the current request. |
| Async Method | create |
Issue a personal access token. |
| Async Method | denies |
Report whether a policy ability is denied for a resource. |
| Method | guard |
Return a configured guard by name. |
| Method | guest |
Report whether the current request is anonymous. |
| Async Method | has |
Report whether the identity owns a role. |
| Method | identifier |
Return the identifier of the authenticated identity. |
| Async Method | login |
Authenticate an identity without verifying credentials. |
| Async Method | logout |
Drop the authenticated state of the current request. |
| Method | register |
Bind a policy class to a resource type. |
| Async Method | revoke |
Revoke the token that authenticated the current request. |
| Method | user |
Return the identity authenticated for the current request. |
| Class Variable | __slots__ |
Declare the instance attribute slots reserved by this class. |
| Instance Variable | __authorizer |
Component answering permission, role and policy questions. |
| Instance Variable | __default |
Name of the authentication guard selected when none is specified. |
| Instance Variable | __guards |
Register the configured guard classes by name. |
| Instance Variable | __permissions |
Source the authorization snapshot is built from. |
| Instance Variable | __session |
Guard backing web authentication. |
| Instance Variable | __tokens |
Store used to issue and revoke personal access tokens. |
Return the request bound to the current container scope.
| Returns | |
orionis.http.Request | Request being handled right now. |
| Raises | |
orionis.auth.AuthException | When the caller is not inside an HTTP request, so no session is available to log in or out. |
IApplication, authorizer: IAuthorizer, permissions: IPermissionRepository, session_guard: ISessionGuard, token_guard: TokenGuard, tokens: IAccessTokenRepository):
(source)
¶
Initialise the manager with the configured collaborators.
| Parameters | |
app:orionis.IApplication | Application exposing the auth configuration. |
authorizer:orionis.auth.contracts.IAuthorizer | Component answering permission, role and policy questions. |
permissions:orionis.auth.contracts.IPermissionRepository | Source the authorization snapshot is built from. |
sessionorionis.auth.contracts.ISessionGuard | Guard backing web authentication. |
tokenorionis.auth.guards.TokenGuard | Guard backing personal access token authentication. |
tokens:orionis.auth.contracts.IAccessTokenRepository | Store used to issue and revoke personal access tokens. |
| Returns | |
None | No return value. |
Bind a freshly authenticated identity to the current scope.
| Parameters | |
identity:orionis.auth.contracts.IAuthenticatable | Identity that just authenticated. |
guard:str | Name of the guard that authenticated it. |
| Returns | |
None | No return value. |
Mapping[ str, object], *, remember: bool = False) -> bool:
(source)
¶
Authenticate the current request from submitted credentials.
Credential based login is a session operation, so it always runs through the session guard regardless of the default guard.
| Parameters | |
credentials:collections.abc.Mapping[str, object] | Submitted credentials, typically username and password. |
remember:bool, optional | Persist a revocable credential for later browser sessions. |
| Returns | |
bool | True when the credentials matched and the session started. |
Return the effective authorization snapshot of the request.
| Returns | |
orionis.auth.contracts.IAuthorizationSnapshot | Immutable view of permissions, roles and token abilities. |
Require a permission or abort the current operation.
| Parameters | |
permission:str | Permission name to require. |
| Returns | |
None | No return value. |
| Raises | |
orionis.auth.AuthenticationException | When the request carries no authenticated identity. |
orionis.auth.AuthorizationException | When the identity is authenticated but lacks the permission. |
Require a policy ability or abort the current operation.
| Parameters | |
ability:str | Ability declared by the policy of the resource. |
resource:object | Resource instance, or the resource class. |
| Returns | |
None | No return value. |
| Raises | |
orionis.auth.AuthenticationException | When the request carries no authenticated identity. |
orionis.auth.AuthorizationException | When the policy denies the operation. |
Report whether every permission is granted.
| Parameters | |
permissions:collections.abc.Iterable[str] | Permission names to evaluate. |
| Returns | |
bool | True when every permission is granted. |
Report whether at least one permission is granted.
| Parameters | |
permissions:collections.abc.Iterable[str] | Permission names to evaluate. |
| Returns | |
bool | True when at least one permission is granted. |
Report whether the current request is authenticated.
| Returns | |
bool | True when an identity was resolved by a guard. |
Return the authentication context of the current request.
| Returns | |
orionis.auth.contracts.IAuthenticationContext | Context bound to the active scope, or the shared guest context outside a request. |
str, *, tokenable: IAuthorizable | None = None, abilities: Iterable[ str] | None = None, expires_at: datetime | None = None) -> NewAccessToken:
(source)
¶
Issue a personal access token.
| Parameters | |
name:str | Human readable label describing the token. |
tokenable:orionis.auth.contracts.IAuthorizable | None, optional | Identity owning the token. None uses the identity authenticated for the current request. |
abilities:collections.abc.Iterable[str] | None, optional | Abilities the token may use. None keeps the full authorization of the identity. |
expiresdatetime.datetime | None, optional | Moment the token stops being accepted. |
| Returns | |
orionis.auth.entities.NewAccessToken | Stored token metadata plus its plain text value. |
| Raises | |
orionis.auth.AuthenticationException | When no identity is available to own the token. |
orionis.auth.AuthorizationException | When a token-authenticated request tries to issue another token. |
orionis.auth.AuthException | When the identity cannot own tokens because it does not
implement orionis.auth.contracts.IAuthorizable. |
Return a configured guard by name.
| Parameters | |
name:str | None, optional | Guard name. None selects the configured default guard. |
| Returns | |
orionis.auth.contracts.IGuard | Guard registered under the requested name. |
| Raises | |
orionis.auth.GuardNotFoundException | When no guard is registered under the given name. |
Return the identifier of the authenticated identity.
| Returns | |
object | None | Identifier of the identity, or None for a guest request. |
Authenticate an identity without verifying credentials.
| Parameters | |
identity:orionis.auth.contracts.IAuthenticatable | Identity to remember for subsequent requests. |
| Returns | |
None | No return value. |
Bind a policy class to a resource type.
| Parameters | |
resource:type | Resource class protected by the policy. |
policy:type[orionis.auth.contracts.IPolicy] | Policy class implementing the abilities. |
| Returns | |
None | No return value. |
Revoke the token that authenticated the current request.
| Returns | |
bool | True when a token was revoked by this call. |
Return the identity authenticated for the current request.
| Returns | |
orionis.auth.contracts.IAuthenticatable | None | Authenticated identity, or None for a guest request. |