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

class PermissionRegistrar: (source)

Constructor: PermissionRegistrar(db)

View In Hierarchy

Create permissions and roles, and attach them to identities.

Database unique constraints decide concurrent insertions. Duplicate recovery uses a transaction or savepoint and verifies that the desired row exists before treating the operation as idempotent.

Concurrency

The registrar is stateless and safe as a singleton. Duplicate inserts lose against the primary or unique key and are resolved by reading the row that won.

Async Method __attach Insert a pivot row, ignoring an already existing one.
Async Method __findId Return the identifier of a named permission or role.
Async Method __firstOrCreate Return the identifier of a row, inserting it when missing.
Method __init__ Initialise the registrar with the model-less query gateway.
Async Method __recover Observe a failed recovery query while preserving the write failure.
Async Method assignRole Attach roles to an identity.
Async Method createPermission Create a permission, or return the existing one.
Async Method createRole Create a role, or return the existing one.
Async Method givePermissionTo Attach direct permissions to an identity.
Async Method grantToRole Attach permissions to a role.
Async Method removeRole Detach roles from an identity.
Async Method revokeFromRole Detach permissions from a role.
Async Method revokePermissionFrom Detach direct permissions from an identity.
Class Variable __slots__ Declare the instance attribute slots reserved by this class.
Instance Variable __db Gateway used to build queries over the authorization tables.
async def __attach(self, table: str, values: dict[str, object]): (source)

Insert a pivot row, ignoring an already existing one.

Parameters
table:strPivot table receiving the row.
values:dict[str, object]Columns forming the composite primary key.
Returns
NoneNo return value.
Raises
orionis.database.QueryExceptionIf insertion fails and no identical pivot row exists.
async def __findId(self, table: str, name: str) -> object | None: (source)

Return the identifier of a named permission or role.

Parameters
table:strTable to search in.
name:strName of the row.
Returns
object | NoneIdentifier of the row, or None when it does not exist.
async def __firstOrCreate(self, table: str, name: str) -> object: (source)

Return the identifier of a row, inserting it when missing.

The unique key decides concurrent insertions. A nested transaction rolls back a losing insert before the winning row is read, without aborting the caller's transaction.

Parameters
table:strTable holding the named rows.
name:strName of the row.
Returns
objectIdentifier of the existing or freshly created row.
Raises
orionis.database.QueryExceptionWhen the insert fails for a reason other than a duplicate.
orionis.auth.AuthExceptionWhen the name is empty, padded or longer than the schema permits.
def __init__(self, db: IQueryBuilder): (source)

Initialise the registrar with the model-less query gateway.

Parameters
db:orionis.orm.contracts.query_builder.IQueryBuilderGateway used to build queries over the authorization tables.
Returns
NoneNo return value.
async def __recover(self, lookup: Awaitable[object], operation: str) -> object | None: (source)

Observe a failed recovery query while preserving the write failure.

Parameters
lookup:collections.abc.Awaitable[object]Read that determines whether a concurrent writer created the row.
operation:strAuthorization operation associated with the recovery attempt.
Returns
object or NoneLookup result, or None when an observed query failure prevents duplicate confirmation and the caller must re-raise its write error.
async def assignRole(self, authorizable: IAuthorizable, *roles: str): (source)

Attach roles to an identity.

Parameters
authorizable:orionis.auth.contracts.IAuthorizableIdentity receiving the roles.
*roles:strRole names. Missing roles are created.
Returns
NoneNo return value.
async def createPermission(self, name: str) -> object: (source)

Create a permission, or return the existing one.

Parameters
name:strPermission name, such as "users.view".
Returns
objectIdentifier of the permission row.
async def createRole(self, name: str) -> object: (source)

Create a role, or return the existing one.

Parameters
name:strRole name, such as "admin".
Returns
objectIdentifier of the role row.
async def givePermissionTo(self, authorizable: IAuthorizable, *permissions: str): (source)

Attach direct permissions to an identity.

Parameters
authorizable:orionis.auth.contracts.IAuthorizableIdentity receiving the permissions.
*permissions:strPermission names. Missing permissions are created.
Returns
NoneNo return value.
async def grantToRole(self, role: str, *permissions: str): (source)

Attach permissions to a role.

Parameters
role:strRole name. It is created when missing.
*permissions:strPermission names. Missing permissions are created.
Returns
NoneNo return value.
async def removeRole(self, authorizable: IAuthorizable, *roles: str): (source)

Detach roles from an identity.

Parameters
authorizable:orionis.auth.contracts.IAuthorizableIdentity losing the roles.
*roles:strRole names. Unknown names are ignored.
Returns
NoneNo return value.
async def revokeFromRole(self, role: str, *permissions: str): (source)

Detach permissions from a role.

Parameters
role:strRole name. Unknown roles are ignored.
*permissions:strPermission names. Unknown names are ignored.
Returns
NoneNo return value.
async def revokePermissionFrom(self, authorizable: IAuthorizable, *permissions: str): (source)

Detach direct permissions from an identity.

Parameters
authorizable:orionis.auth.contracts.IAuthorizableIdentity losing the permissions.
*permissions:strPermission names. Unknown names are ignored.
Returns
NoneNo return value.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

Gateway used to build queries over the authorization tables.