openedx_authz.engine.schema.types package#

Submodules#

openedx_authz.engine.schema.types.compilation module#

Compilation-output types for the authz schema pipeline.

These dataclasses are the output of the compile step (ADR 0018): resolved definitions keyed by stable identifier, each carrying every SourceRecord that contributed to it, plus the per-grant provenance the applier persists (ADR 0025).

class openedx_authz.engine.schema.types.compilation.CompiledDefinition(key: str, definition: PermissionCategory | PermissionDefinition | RoleDefinition, sources: tuple[SourceRecord, ...])

Bases: object

A resolved definition plus every source that contributed to it.

The kind of definition is not stored: definition is a typed union and CompiledSchema already keys categories, permissions, and roles into separate dicts, so the kind is recoverable from context when needed.

key

The category id, permission identifier, or role id.

Type:

str

definition

The resolved dataclass instance (category/permission/role).

Type:

openedx_authz.engine.schema.types.definitions.PermissionCategory | openedx_authz.engine.schema.types.definitions.PermissionDefinition | openedx_authz.engine.schema.types.definitions.RoleDefinition

sources

All contributing sources, in priority-then-discovery order.

Type:

tuple[openedx_authz.engine.schema.types.loading.SourceRecord, …]

definition: PermissionCategory | PermissionDefinition | RoleDefinition
key: str
sources: tuple[SourceRecord, ...]
class openedx_authz.engine.schema.types.compilation.CompiledSchema(categories: dict[str, ~openedx_authz.engine.schema.types.compilation.CompiledDefinition] = <factory>, permissions: dict[str, ~openedx_authz.engine.schema.types.compilation.CompiledDefinition] = <factory>, roles: dict[str, ~openedx_authz.engine.schema.types.compilation.CompiledDefinition] = <factory>, role_permission_sources: dict[tuple[str, str], list[~openedx_authz.engine.schema.types.compilation.RelationshipSource]] = <factory>)

Bases: object

The full set of resolved static definitions (output of compile).

Keyed by stable identifier. This is what the renderer turns into Casbin p rows and what the applier persists alongside source records.

categories: dict[str, CompiledDefinition]
permissions: dict[str, CompiledDefinition]
role_permission_pairs() → list[tuple[str, str]]

Return (role_id, permission_identifier) pairs for every role.

This is the flattened relation the renderer maps to Casbin p rows. Pairs are returned in a deterministic order (role id, then permission id) so downstream rendering and diffing are stable across runs.

role_permission_sources: dict[tuple[str, str], list[RelationshipSource]]
roles: dict[str, CompiledDefinition]
class openedx_authz.engine.schema.types.compilation.RelationshipSource(source: SourceRecord, origin_kind: SchemaOriginKind, priority: int)

Bases: object

Provenance of a single role-permission grant (ADR 0025).

source

The contributing source record.

Type:

openedx_authz.engine.schema.types.loading.SourceRecord

origin_kind

SchemaOriginKind.BASE (from the role’s own definition) or SchemaOriginKind.EXTENSION (added by a role_extensions entry).

Type:

openedx_authz.constants.schema.SchemaOriginKind

priority

The contributing file’s priority.

Type:

int

origin_kind: SchemaOriginKind
priority: int
source: SourceRecord

openedx_authz.engine.schema.types.definitions module#

Static definition objects for the authz schema pipeline.

These dataclasses describe the author-facing schema vocabulary (ADR 0017 / docs/references/authorization-schema.rst): permission categories, permissions, static roles, and role extensions. Identifiers match [a-z][a-z0-9_]*, permission IDs join namespace and name with a period, and the internal Casbin forms (act^..., role^...) never appear here.

class openedx_authz.engine.schema.types.definitions.PermissionCategory(id: str, display_name: str, description: str, icon: str | None = None)

Bases: object

A display/grouping category for permissions. Grants no access.

description: str
display_name: str
icon: str | None = None
id: str
class openedx_authz.engine.schema.types.definitions.PermissionDefinition(namespace: str, name: str, display_name: str, description: str, category_id: str, scopes: tuple[str, ...], icon: str | None = None)

Bases: object

A single permission.

The complete permission ID (used by role definitions, extensions, app checks, and API responses) is identifier.

category_id: str
description: str
display_name: str
icon: str | None = None
property identifier: str

Complete permission ID, e.g. "courses.view_course".

name: str
namespace: str
scopes: tuple[str, ...]
class openedx_authz.engine.schema.types.definitions.RoleDefinition(id: str, display_name: str, description: str, scopes: tuple[str, ...], permissions: tuple[str, ...], icon: str | None = None, hidden: bool = False)

Bases: object

A static role listing every permission assigned to it.

hidden mirrors ADR 0023: a hidden role is excluded from normal role discovery/selection but keeps its assignments, permission checks, and reserved ID.

description: str
display_name: str
hidden: bool = False
icon: str | None = None
id: str
permissions: tuple[str, ...]
scopes: tuple[str, ...]
class openedx_authz.engine.schema.types.definitions.RoleExtension(role_id: str, add_permissions: tuple[str, ...] = (), remove_permissions: tuple[str, ...] = (), display_name: str | None = None, description: str | None = None, icon: str | None = None, hidden: bool | None = None)

Bases: object

A change to an existing static role (ADR 0023).

Only the included fields change; None/empty means “leave unchanged”. An extension can never change the role ID or replace the whole definition. hidden is tri-state: None leaves the current value untouched.

add_permissions: tuple[str, ...] = ()
description: str | None = None
display_name: str | None = None
hidden: bool | None = None
icon: str | None = None
remove_permissions: tuple[str, ...] = ()
role_id: str

openedx_authz.engine.schema.types.loading module#

Provenance and loading-output types for the authz schema pipeline.

SourceRecord identifies where a schema contribution came from (ADR 0019), and SchemaDocument is the per-file output of the load step (ADR 0018). A loaded document carries the source that produced it, which is why both live together here.

class openedx_authz.engine.schema.types.loading.ParsedSchemaDocument(source: SourceRecord, data: object)

Bases: object

One parsed YAML value and the provenance of the resource that supplied it.

data: object
source: SourceRecord
class openedx_authz.engine.schema.types.loading.SchemaDocument(source: SourceRecord, priority: int, categories: list[PermissionCategory] = <factory>, permissions: list[PermissionDefinition] = <factory>, roles: list[RoleDefinition] = <factory>, role_extensions: list[RoleExtension] = <factory>)

Bases: object

One loaded .yaml schema file plus its provenance and priority.

Output of the load step. Still per-file: cross-file references are not yet resolved (that happens during compile).

categories: list[PermissionCategory]
permissions: list[PermissionDefinition]
priority: int
role_extensions: list[RoleExtension]
roles: list[RoleDefinition]
source: SourceRecord
class openedx_authz.engine.schema.types.loading.SourceFileRecord(distribution: str, distribution_version: str, module: str, resource_path: str, schema_version: str, content_digest: str)

Bases: SourceRecord

Source record for a filesystem-path schema resource (ADR 0030).

Overrides source_id to use the absolute path directly, since the parent’s module.replace(".", "/") convention assumes dotted Python module paths and would corrupt a filesystem path containing a file extension.

property source_id: str

Return "<distribution>:<absolute_path>".

class openedx_authz.engine.schema.types.loading.SourceRecord(distribution: str, distribution_version: str, module: str, resource_path: str, schema_version: str, content_digest: str)

Bases: object

Identifies a single schema contribution across deployment layouts.

Per ADR 0019 §2, these packaging-based values (not filesystem paths) must identify the same source under Tutor, native, and local deployments. A compiled definition retains every SourceRecord that contributed to it, so a role assembled from a base definition plus one or more extensions keeps all of its sources.

distribution

Installed distribution name, e.g. "openedx-authz".

Type:

str

distribution_version

Version of that distribution.

Type:

str

module

Python module that owns the resource.

Type:

str

resource_path

Resource path within that module.

Type:

str

schema_version

The schema_version declared by the file.

Type:

str

content_digest

Digest of the resource contents (change detection).

Type:

str

content_digest: str
distribution: str
distribution_version: str
module: str
resource_path: str
schema_version: str
property source_id: str

Stable, human-readable id.

Combines the distribution with the module directory path and the file name, e.g. "openedx-authz:openedx_authz/applets/course_team_roles/schema/roles.yaml".

module is the dotted path of the owning directory and resource_path is anchor-relative (so it may repeat the directory); only the file name is appended here to avoid duplicating the directory segments.

Module contents#

Typed schema objects and source records for the authz schema pipeline.

These dataclasses are the data contract passed between lifecycle steps (ADR 0018): discovery produces DiscoveredResource, loading produces SchemaDocument, and compilation produces CompiledSchema.

The types are split into category modules for readability, but the package preserves a flat public surface: import everything directly from openedx_authz.engine.schema.types.

  • definitions - author-facing definition objects (categories, permissions, roles, role extensions).

  • loading - provenance (SourceRecord) and the per-file load output (SchemaDocument).

  • compilation - the resolved compile output (CompiledSchema and friends).

Definition field shapes follow docs/references/authorization-schema.rst (reference PR): identifiers match [a-z][a-z0-9_]*, permission IDs join namespace and name with a period, and the internal Casbin forms (act^..., role^...) never appear here.

class openedx_authz.engine.schema.types.CompiledDefinition(key: str, definition: PermissionCategory | PermissionDefinition | RoleDefinition, sources: tuple[SourceRecord, ...])

Bases: object

A resolved definition plus every source that contributed to it.

The kind of definition is not stored: definition is a typed union and CompiledSchema already keys categories, permissions, and roles into separate dicts, so the kind is recoverable from context when needed.

key

The category id, permission identifier, or role id.

Type:

str

definition

The resolved dataclass instance (category/permission/role).

Type:

openedx_authz.engine.schema.types.definitions.PermissionCategory | openedx_authz.engine.schema.types.definitions.PermissionDefinition | openedx_authz.engine.schema.types.definitions.RoleDefinition

sources

All contributing sources, in priority-then-discovery order.

Type:

tuple[openedx_authz.engine.schema.types.loading.SourceRecord, …]

definition: PermissionCategory | PermissionDefinition | RoleDefinition
key: str
sources: tuple[SourceRecord, ...]
class openedx_authz.engine.schema.types.CompiledSchema(categories: dict[str, ~openedx_authz.engine.schema.types.compilation.CompiledDefinition] = <factory>, permissions: dict[str, ~openedx_authz.engine.schema.types.compilation.CompiledDefinition] = <factory>, roles: dict[str, ~openedx_authz.engine.schema.types.compilation.CompiledDefinition] = <factory>, role_permission_sources: dict[tuple[str, str], list[~openedx_authz.engine.schema.types.compilation.RelationshipSource]] = <factory>)

Bases: object

The full set of resolved static definitions (output of compile).

Keyed by stable identifier. This is what the renderer turns into Casbin p rows and what the applier persists alongside source records.

categories: dict[str, CompiledDefinition]
permissions: dict[str, CompiledDefinition]
role_permission_pairs() → list[tuple[str, str]]

Return (role_id, permission_identifier) pairs for every role.

This is the flattened relation the renderer maps to Casbin p rows. Pairs are returned in a deterministic order (role id, then permission id) so downstream rendering and diffing are stable across runs.

role_permission_sources: dict[tuple[str, str], list[RelationshipSource]]
roles: dict[str, CompiledDefinition]
class openedx_authz.engine.schema.types.ParsedSchemaDocument(source: SourceRecord, data: object)

Bases: object

One parsed YAML value and the provenance of the resource that supplied it.

data: object
source: SourceRecord
class openedx_authz.engine.schema.types.PermissionCategory(id: str, display_name: str, description: str, icon: str | None = None)

Bases: object

A display/grouping category for permissions. Grants no access.

description: str
display_name: str
icon: str | None = None
id: str
class openedx_authz.engine.schema.types.PermissionDefinition(namespace: str, name: str, display_name: str, description: str, category_id: str, scopes: tuple[str, ...], icon: str | None = None)

Bases: object

A single permission.

The complete permission ID (used by role definitions, extensions, app checks, and API responses) is identifier.

category_id: str
description: str
display_name: str
icon: str | None = None
property identifier: str

Complete permission ID, e.g. "courses.view_course".

name: str
namespace: str
scopes: tuple[str, ...]
class openedx_authz.engine.schema.types.RelationshipSource(source: SourceRecord, origin_kind: SchemaOriginKind, priority: int)

Bases: object

Provenance of a single role-permission grant (ADR 0025).

source

The contributing source record.

Type:

openedx_authz.engine.schema.types.loading.SourceRecord

origin_kind

SchemaOriginKind.BASE (from the role’s own definition) or SchemaOriginKind.EXTENSION (added by a role_extensions entry).

Type:

openedx_authz.constants.schema.SchemaOriginKind

priority

The contributing file’s priority.

Type:

int

origin_kind: SchemaOriginKind
priority: int
source: SourceRecord
class openedx_authz.engine.schema.types.RoleDefinition(id: str, display_name: str, description: str, scopes: tuple[str, ...], permissions: tuple[str, ...], icon: str | None = None, hidden: bool = False)

Bases: object

A static role listing every permission assigned to it.

hidden mirrors ADR 0023: a hidden role is excluded from normal role discovery/selection but keeps its assignments, permission checks, and reserved ID.

description: str
display_name: str
hidden: bool = False
icon: str | None = None
id: str
permissions: tuple[str, ...]
scopes: tuple[str, ...]
class openedx_authz.engine.schema.types.RoleExtension(role_id: str, add_permissions: tuple[str, ...] = (), remove_permissions: tuple[str, ...] = (), display_name: str | None = None, description: str | None = None, icon: str | None = None, hidden: bool | None = None)

Bases: object

A change to an existing static role (ADR 0023).

Only the included fields change; None/empty means “leave unchanged”. An extension can never change the role ID or replace the whole definition. hidden is tri-state: None leaves the current value untouched.

add_permissions: tuple[str, ...] = ()
description: str | None = None
display_name: str | None = None
hidden: bool | None = None
icon: str | None = None
remove_permissions: tuple[str, ...] = ()
role_id: str
class openedx_authz.engine.schema.types.SchemaDocument(source: SourceRecord, priority: int, categories: list[PermissionCategory] = <factory>, permissions: list[PermissionDefinition] = <factory>, roles: list[RoleDefinition] = <factory>, role_extensions: list[RoleExtension] = <factory>)

Bases: object

One loaded .yaml schema file plus its provenance and priority.

Output of the load step. Still per-file: cross-file references are not yet resolved (that happens during compile).

categories: list[PermissionCategory]
permissions: list[PermissionDefinition]
priority: int
role_extensions: list[RoleExtension]
roles: list[RoleDefinition]
source: SourceRecord
class openedx_authz.engine.schema.types.SourceFileRecord(distribution: str, distribution_version: str, module: str, resource_path: str, schema_version: str, content_digest: str)

Bases: SourceRecord

Source record for a filesystem-path schema resource (ADR 0030).

Overrides source_id to use the absolute path directly, since the parent’s module.replace(".", "/") convention assumes dotted Python module paths and would corrupt a filesystem path containing a file extension.

property source_id: str

Return "<distribution>:<absolute_path>".

class openedx_authz.engine.schema.types.SourceRecord(distribution: str, distribution_version: str, module: str, resource_path: str, schema_version: str, content_digest: str)

Bases: object

Identifies a single schema contribution across deployment layouts.

Per ADR 0019 §2, these packaging-based values (not filesystem paths) must identify the same source under Tutor, native, and local deployments. A compiled definition retains every SourceRecord that contributed to it, so a role assembled from a base definition plus one or more extensions keeps all of its sources.

distribution

Installed distribution name, e.g. "openedx-authz".

Type:

str

distribution_version

Version of that distribution.

Type:

str

module

Python module that owns the resource.

Type:

str

resource_path

Resource path within that module.

Type:

str

schema_version

The schema_version declared by the file.

Type:

str

content_digest

Digest of the resource contents (change detection).

Type:

str

content_digest: str
distribution: str
distribution_version: str
module: str
resource_path: str
schema_version: str
property source_id: str

Stable, human-readable id.

Combines the distribution with the module directory path and the file name, e.g. "openedx-authz:openedx_authz/applets/course_team_roles/schema/roles.yaml".

module is the dotted path of the owning directory and resource_path is anchor-relative (so it may repeat the directory); only the file name is appended here to avoid duplicating the directory segments.