Permission API

Core classes

general_manager.permission.base_permission.BasePermission

Bases: ABC

Abstract base class defining CRUD permission checks for managers.

instance property

instance

Return the object against which permission checks are performed.

request_user property

request_user

Return the user being evaluated for permission checks.

__init__

__init__(instance, request_user)

Initialise the permission context for a specific manager and user.

describe_permissions

describe_permissions(action, attribute)

Return permission expressions associated with an action/attribute pair.

describe_operation_permissions abstractmethod

describe_operation_permissions(action)

Return permission expressions associated with an action-level check.

check_operation_permission abstractmethod

check_operation_permission(action)

Return whether an action without attribute payload is allowed.

can_read_instance

can_read_instance()

Return whether the current user may see that the instance exists.

check_create_permission classmethod

check_create_permission(data, manager, request_user)

Validate that the requesting user is allowed to perform the create operation.

Checks create permission for every key in data using the given manager. Empty payloads still evaluate the create-level permission gate once. If any attribute is not permitted, raises a PermissionCheckError that includes the evaluated user and a list of denial messages.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Mapping of attribute names to the values intended for creation.	required
manager	type[GeneralManager]	Manager class that defines the model/schema against which permissions are checked.	required
request_user	UserLike | Any	User instance or user id (will be resolved to a user or AnonymousUser).	required

Raises:

Type	Description
PermissionCheckError	If one or more attributes in data are denied for the resolved request_user.

check_update_permission classmethod

check_update_permission(
    data, old_manager_instance, request_user
)

Validate whether the request_user can perform the update operation.

Checks update permission for every key in data against the existing manager instance. Empty payloads still evaluate the update-level permission gate once.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Mapping of attribute names to new values to be applied.	required
old_manager_instance	GeneralManager	Existing manager instance whose current state is used to evaluate update permissions.	required
request_user	UserLike | Any	User instance or user id; non-user values will be resolved to a User or AnonymousUser via get_user_with_id.	required

Raises:

Type	Description
PermissionCheckError	Raised with a list of error messages when one or more fields are not permitted to be updated.

check_delete_permission classmethod

check_delete_permission(manager_instance, request_user)

Validate that the request_user has delete permission for every attribute of the given manager instance.

This resolves the provided request_user to a User/AnonymousUser, evaluates delete permission for each attribute present on manager_instance, collects any denied attributes into error messages, and raises PermissionCheckError if any permissions are denied.

Parameters:

Name	Type	Description	Default
manager_instance	GeneralManager	The manager object whose attributes will be checked for delete permission.	required
request_user	UserLike | Any	The user (or user id) to evaluate; non-user values will be resolved to AnonymousUser.	required

Raises:

Type	Description
PermissionCheckError	If one or more attributes are not permitted for deletion by request_user. The exception carries the user and the list of denial messages.

get_user_with_id staticmethod

get_user_with_id(user)

Resolve a user identifier or user-like object to a Django User or AnonymousUser instance.

If the input is already an AbstractBaseUser or AnonymousUser, it is returned unchanged. If the input is a primary key (or other value used to look up a User by id), the corresponding User is returned; if no such User exists, an AnonymousUser is returned.

Parameters:

Name	Type	Description	Default
user	Any | UserLike	A user object or a value to look up a User by primary key.	required

Returns:

Name	Type	Description
UserLike	UserLike	The resolved User instance, or an AnonymousUser when no matching User is found.

check_permission abstractmethod

check_permission(action, attribute)

Determine whether the given action is permitted on the specified attribute.

Parameters:

Name	Type	Description	Default
action	Literal['create', 'read', 'update', 'delete']	Operation being checked.	required
attribute	str	Attribute name subject to the permission check.	required

Returns:

Name	Type	Description
bool	bool	True when the action is allowed.

get_permission_filter

get_permission_filter()

Return the filter/exclude constraints associated with this permission.

get_read_permission_plan

get_read_permission_plan()

Return read-query prefilters plus whether instance checks must still run.

validate_permission_string

validate_permission_string(permission)

Validate complex permission expressions joined by & operators.

Parameters:

Name	Type	Description	Default
permission	str	Permission expression (for example, isAuthenticated&isMatchingKeyAccount).	required

Returns:

Name	Type	Description
bool	bool	True when every sub-permission evaluates to True for the current user.

general_manager.permission.manager_based_permission.AdditiveManagerPermission

Bases: _ConfiguredManagerPermission

Manager-based permissions where attribute rules add an extra gate.

general_manager.permission.manager_based_permission.OverrideManagerPermission

Bases: _ConfiguredManagerPermission

Manager-based permissions where attribute rules replace the CRUD base rule.

general_manager.permission.manager_based_permission.ManagerBasedPermission

Bases: AdditiveManagerPermission

Deprecated compatibility alias for AdditiveManagerPermission.

general_manager.permission.mutation_permission.MutationPermission

Evaluate mutation permissions using class-level configuration.

data property

data

Return wrapped permission data.

request_user property

request_user

Return the user whose permissions are being evaluated.

__init__

__init__(data, request_user)

Create a mutation permission context for the given data and user.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Input payload for the mutation.	required
request_user	AbstractBaseUser | AnonymousUser	User attempting the mutation.	required

__get_attribute_permissions

__get_attribute_permissions()

Collect attribute-specific permission expressions declared on the class.

describe_permissions

describe_permissions(attribute)

Return mutate-level and attribute-specific permissions for the field.

check classmethod

check(data, request_user)

Validate that the given user is authorized to perform the mutation described by data.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Mutation payload mapping field names to values.	required
request_user	AbstractBaseUser | AnonymousUser | Any	A user object or a user identifier; if an identifier is provided it will be resolved to a user.	required

Raises:

Type	Description
PermissionCheckError	Raised with the request_user and a list of field-level error messages when one or more fields fail their permission checks.

check_permission

check_permission(attribute)

Determine whether the request user is allowed to modify a specific attribute in the mutation payload.

Updates the instance's cached overall permission result based on the class-level mutate permissions.

Parameters:

Name	Type	Description	Default
attribute	str	Name of the attribute to validate.	required

Returns:

Type	Description
bool	True if modification of the attribute is allowed, False otherwise.

__check_specific_permission

__check_specific_permission(permissions)

Return True when any permission expression evaluates to True.

Data access helpers

general_manager.permission.permission_data_manager.PermissionDataManager

Bases: Generic[GeneralManagerData]

Adapter that exposes permission-related data as a unified interface.

permission_data property

permission_data

Return the underlying permission payload.

manager property

manager

Return the manager class associated with the permission data.

__init__

__init__(permission_data, manager=None)

Wrap a mapping or GeneralManager instance to expose permission-related fields via attribute access.

Parameters:

Name	Type	Description	Default
permission_data	dict[str, object] | GeneralManager	Either a dict mapping field names to values or a GeneralManager instance whose attributes provide field values.	required
manager	type[GeneralManager] | None	When permission_data is a dict, the manager class associated with that data; otherwise ignored.	None

Raises:

Type	Description
InvalidPermissionDataError	If permission_data is neither a dict nor an instance of GeneralManager.

for_update classmethod

for_update(base_data, update_data)

Create a PermissionDataManager representing base_data with update_data applied.

Parameters:

Name	Type	Description	Default
base_data	GeneralManagerData	Existing manager instance whose data will serve as the base.	required
update_data	dict[str, object]	Fields to add or override on the base data.	required

Returns:

Name	Type	Description
PermissionDataManager	PermissionDataManager	Wrapper exposing the merged data where keys in update_data override those from base_data.

__getattr__

__getattr__(name)

Proxy attribute access to the wrapped permission data.

Registry and reusable checks

general_manager.permission.permission_checks.register_permission

register_permission(name, *, permission_filter=None)

Register a permission function in the global registry.

Parameters:

Name	Type	Description	Default
name	str	Identifier used in permission expressions.	required
permission_filter	permission_filter | None	Optional callable that provides queryset filters corresponding to the permission.	None

Returns:

Type	Description
Callable[[permission_method], permission_method]	Callable[[permission_method], permission_method]: Decorator that
Callable[[permission_method], permission_method]	registers the decorated function and returns it unchanged.

Raises:

Type	Description
ValueError	If another permission with the same name has already been registered.

general_manager.permission.permission_checks.permission_functions module-attribute

permission_functions = {}

GraphQL permission capabilities

general_manager.permission.graphql_capabilities.object_capability

object_capability(name, evaluator, *, batch_evaluator=None)

Declare a domain-specific object capability.

general_manager.permission.graphql_capabilities.permission_capability

permission_capability(
    target, action, *, name=None, payload=None
)

Declare a capability backed by a manager Permission CRUD check.

general_manager.permission.graphql_capabilities.mutation_capability

mutation_capability(mutation, *, name=None, payload=None)

Declare a capability backed by a custom MutationPermission class.

general_manager.permission.graphql_capabilities.CapabilityEvaluationContext

Operation-scoped cache for GraphQL permission capability evaluation.

evaluate

evaluate(declaration, instance)

Evaluate a capability and cache deny-on-error results for the operation.

warm

warm(declarations, instances)

Warm cached capability values for a page of instances when possible.

general_manager.permission.graphql_capabilities.GraphQLPermissionCapability dataclass

Declarative permission capability exposed as a GraphQL boolean field.

Audit logging

general_manager.permission.audit.AuditLogger

Bases: Protocol

Protocol describing the expected behaviour of an audit logger implementation.

record

record(event)

Persist or forward a permission audit event.

general_manager.permission.audit.FileAuditLogger

Bases: _BufferedAuditLogger

Persist audit events as newline-delimited JSON records in a file.

general_manager.permission.audit.DatabaseAuditLogger

Bases: _BufferedAuditLogger

Store audit events inside a dedicated database table using Django connections.

general_manager.permission.audit.configure_audit_logger

configure_audit_logger(logger)

Configure the audit logger used by permission checks.

Parameters:

Name	Type	Description	Default
logger	AuditLogger | None	Concrete logger implementation. Passing None resets the logger to a no-op implementation.	required

general_manager.permission.audit.configure_audit_logger_from_settings

configure_audit_logger_from_settings(django_settings)

Configure the audit logger based on Django settings.

Expects either settings.GENERAL_MANAGER['AUDIT_LOGGER'] or a top-level settings.AUDIT_LOGGER value pointing to an audit logger implementation (instance, callable, or dotted import path).

general_manager.permission.audit.emit_permission_audit_event

emit_permission_audit_event(event)

Forward an audit event to the configured logger when logging is enabled.

Parameters:

Name	Type	Description	Default
event	PermissionAuditEvent	Event payload to record.	required

general_manager.permission.audit.PermissionAuditEvent dataclass

Payload describing a permission evaluation outcome.

Attributes:

Name	Type	Description
action	AuditAction	CRUD or mutation action that was evaluated.
attributes	tuple[str, ...]	Collection of attribute names covered by this evaluation.
granted	bool	True when the action was permitted.
user	Any	User object involved in the evaluation; consumers may extract ids.
manager	str | None	Name of the manager class (when applicable).
permissions	tuple[str, ...]	Permission expressions that were considered.
bypassed	bool	True when the decision relied on a superuser bypass.
metadata	Mapping[str, Any] | None	Optional additional context.

Utility functions

general_manager.permission.utils.validate_permission_string

validate_permission_string(permission, data, request_user)

Evaluate a compound permission expression joined by '&' operators.

Parameters:

Name	Type	Description	Default
permission	str	Permission expression where sub-permissions are joined with '&'. Individual sub-permissions may include ':'-separated configuration parts (for example, "isAuthenticated&admin:level").	required
data	PermissionDataManager | GeneralManager | GeneralManagerMeta	Object passed to each permission function.	required
request_user	AbstractBaseUser | AnonymousUser	User for whom permissions are evaluated.	required

Returns:

Type	Description
bool	true if every sub-permission evaluates to True, false otherwise.

Raises:

Type	Description
PermissionNotFoundError	If a referenced permission function is not registered.

general_manager.permission.utils.PermissionNotFoundError

Bases: ValueError

Raised when a referenced permission function is not registered.

__init__

__init__(permission)

Exception raised when a referenced permission function cannot be found.

Parameters:

Name	Type	Description	Default
permission	str	The permission identifier that was not found; used to format the exception message.	required