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.

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 create each attribute in the provided payload.

Checks create permission for every key in data using the given manager. 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 update the given fields on an existing manager instance.

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 = {}

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