ORIONIS API REFERENCE

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 documentation

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 authorizeResource Require a policy ability or abort the current operation.
Async Method can Report whether the current request grants a permission.
Async Method canAll Report whether every permission is granted.
Async Method canAny 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 createToken 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 hasRole 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 registerPolicy Bind a policy class to a resource type.
Async Method revokeCurrentToken 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_guard 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 Guard backing web authentication.
Instance Variable __tokens Store used to issue and revoke personal access tokens.
def __request() -> Request: (source)

Return the request bound to the current container scope.

Returns
orionis.http.RequestRequest being handled right now.
Raises
orionis.auth.AuthExceptionWhen the caller is not inside an HTTP request, so no session is available to log in or out.
def __init__(self, app: IApplication, authorizer: IAuthorizer, permissions: IPermissionRepository, session_guard: ISessionGuard, token_guard: TokenGuard, tokens: IAccessTokenRepository): (source)

Initialise the manager with the configured collaborators.

Parameters
app:orionis.IApplicationApplication exposing the auth configuration.
authorizer:orionis.auth.contracts.IAuthorizerComponent answering permission, role and policy questions.
permissions:orionis.auth.contracts.IPermissionRepositorySource the authorization snapshot is built from.
session_guard:orionis.auth.contracts.ISessionGuardGuard backing web authentication.
token_guard:orionis.auth.guards.TokenGuardGuard backing personal access token authentication.
tokens:orionis.auth.contracts.IAccessTokenRepositoryStore used to issue and revoke personal access tokens.
Returns
NoneNo return value.
def __rebind(self, identity: IAuthenticatable, guard: str): (source)

Bind a freshly authenticated identity to the current scope.

Parameters
identity:orionis.auth.contracts.IAuthenticatableIdentity that just authenticated.
guard:strName of the guard that authenticated it.
Returns
NoneNo return value.
async def allows(self, ability: str, resource: object) -> bool: (source)

Evaluate a policy ability against a resource.

Parameters
ability:strAbility declared by the policy of the resource.
resource:objectResource instance, or the resource class.
Returns
boolTrue when the policy allows the operation.
async def attempt(self, credentials: 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, optionalPersist a revocable credential for later browser sessions.
Returns
boolTrue when the credentials matched and the session started.
async def authorization(self) -> IAuthorizationSnapshot: (source)

Return the effective authorization snapshot of the request.

Returns
orionis.auth.contracts.IAuthorizationSnapshotImmutable view of permissions, roles and token abilities.
async def authorize(self, permission: str): (source)

Require a permission or abort the current operation.

Parameters
permission:strPermission name to require.
Returns
NoneNo return value.
Raises
orionis.auth.AuthenticationExceptionWhen the request carries no authenticated identity.
orionis.auth.AuthorizationExceptionWhen the identity is authenticated but lacks the permission.
async def authorizeResource(self, ability: str, resource: object): (source)

Require a policy ability or abort the current operation.

Parameters
ability:strAbility declared by the policy of the resource.
resource:objectResource instance, or the resource class.
Returns
NoneNo return value.
Raises
orionis.auth.AuthenticationExceptionWhen the request carries no authenticated identity.
orionis.auth.AuthorizationExceptionWhen the policy denies the operation.
async def can(self, permission: str) -> bool: (source)

Report whether the current request grants a permission.

Parameters
permission:strPermission name to evaluate.
Returns
boolTrue when the permission is granted.
async def canAll(self, permissions: Iterable[str]) -> bool: (source)

Report whether every permission is granted.

Parameters
permissions:collections.abc.Iterable[str]Permission names to evaluate.
Returns
boolTrue when every permission is granted.
async def canAny(self, permissions: Iterable[str]) -> bool: (source)

Report whether at least one permission is granted.

Parameters
permissions:collections.abc.Iterable[str]Permission names to evaluate.
Returns
boolTrue when at least one permission is granted.
async def cannot(self, permission: str) -> bool: (source)

Report whether the current request lacks a permission.

Parameters
permission:strPermission name to evaluate.
Returns
boolTrue when the permission is not granted.
def check(self) -> bool: (source)

Report whether the current request is authenticated.

Returns
boolTrue when an identity was resolved by a guard.
def context(self) -> IAuthenticationContext: (source)

Return the authentication context of the current request.

Returns
orionis.auth.contracts.IAuthenticationContextContext bound to the active scope, or the shared guest context outside a request.
async def createToken(self, name: str, *, tokenable: IAuthorizable | None = None, abilities: Iterable[str] | None = None, expires_at: datetime | None = None) -> NewAccessToken: (source)

Issue a personal access token.

Parameters
name:strHuman readable label describing the token.
tokenable:orionis.auth.contracts.IAuthorizable | None, optionalIdentity owning the token. None uses the identity authenticated for the current request.
abilities:collections.abc.Iterable[str] | None, optionalAbilities the token may use. None keeps the full authorization of the identity.
expires_at:datetime.datetime | None, optionalMoment the token stops being accepted.
Returns
orionis.auth.entities.NewAccessTokenStored token metadata plus its plain text value.
Raises
orionis.auth.AuthenticationExceptionWhen no identity is available to own the token.
orionis.auth.AuthorizationExceptionWhen a token-authenticated request tries to issue another token.
orionis.auth.AuthExceptionWhen the identity cannot own tokens because it does not implement orionis.auth.contracts.IAuthorizable.
async def denies(self, ability: str, resource: object) -> bool: (source)

Report whether a policy ability is denied for a resource.

Parameters
ability:strAbility declared by the policy of the resource.
resource:objectResource instance, or the resource class.
Returns
boolTrue when the policy denies the operation.
def guard(self, name: str | None = None) -> IGuard: (source)

Return a configured guard by name.

Parameters
name:str | None, optionalGuard name. None selects the configured default guard.
Returns
orionis.auth.contracts.IGuardGuard registered under the requested name.
Raises
orionis.auth.GuardNotFoundExceptionWhen no guard is registered under the given name.
def guest(self) -> bool: (source)

Report whether the current request is anonymous.

Returns
boolTrue when no identity backs the request.
async def hasRole(self, role: str) -> bool: (source)

Report whether the identity owns a role.

Parameters
role:strRole name to evaluate.
Returns
boolTrue when the role is assigned to the identity.
def identifier(self) -> object | None: (source)

Return the identifier of the authenticated identity.

Returns
object | NoneIdentifier of the identity, or None for a guest request.
async def login(self, identity: IAuthenticatable): (source)

Authenticate an identity without verifying credentials.

Parameters
identity:orionis.auth.contracts.IAuthenticatableIdentity to remember for subsequent requests.
Returns
NoneNo return value.
async def logout(self): (source)

Drop the authenticated state of the current request.

Returns
NoneNo return value.
def registerPolicy(self, resource: type, policy: type[IPolicy]): (source)

Bind a policy class to a resource type.

Parameters
resource:typeResource class protected by the policy.
policy:type[orionis.auth.contracts.IPolicy]Policy class implementing the abilities.
Returns
NoneNo return value.
async def revokeCurrentToken(self) -> bool: (source)

Revoke the token that authenticated the current request.

Returns
boolTrue when a token was revoked by this call.
def user(self) -> IAuthenticatable | None: (source)

Return the identity authenticated for the current request.

Returns
orionis.auth.contracts.IAuthenticatable | NoneAuthenticated identity, or None for a guest request.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

__authorizer = (source)

Component answering permission, role and policy questions.

__default_guard: str = (source)

Name of the authentication guard selected when none is specified.

__guards: dict[str, IGuard] = (source)

Register the configured guard classes by name.

__permissions = (source)

Source the authorization snapshot is built from.

__session_guard = (source)

Guard backing web authentication.

__tokens = (source)

Store used to issue and revoke personal access tokens.