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:
objectA resolved definition plus every source that contributed to it.
The kind of definition is not stored:
definitionis a typed union andCompiledSchemaalready 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:
- 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:
objectThe full set of resolved static definitions (output of
compile).Keyed by stable identifier. This is what the renderer turns into Casbin
prows and what the applier persists alongside source records.- 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
prows. Pairs are returned in a deterministic order (role id, then permission id) so downstream rendering and diffing are stable across runs.
- class openedx_authz.engine.schema.types.compilation.RelationshipSource(source: SourceRecord, origin_kind: SchemaOriginKind, priority: int)
Bases:
objectProvenance 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) orSchemaOriginKind.EXTENSION(added by arole_extensionsentry).- Type:
openedx_authz.constants.schema.SchemaOriginKind
- priority
The contributing file’s priority.
- Type:
- 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:
objectA display/grouping category for permissions. Grants no access.
- description: str
- display_name: str
- 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:
objectA 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
- property identifier: str
Complete permission ID, e.g.
"courses.view_course".
- name: str
- namespace: 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:
objectA static role listing every permission assigned to it.
hiddenmirrors 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
- id: 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:
objectA 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.hiddenis tri-state:Noneleaves the current value untouched.- 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:
objectOne 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:
objectOne loaded
.yamlschema file plus its provenance and priority.Output of the
loadstep. Still per-file: cross-file references are not yet resolved (that happens duringcompile).- 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:
SourceRecordSource record for a filesystem-path schema resource (ADR 0030).
Overrides
source_idto use the absolute path directly, since the parent’smodule.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:
objectIdentifies 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
SourceRecordthat 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:
- distribution_version
Version of that distribution.
- Type:
- module
Python module that owns the resource.
- Type:
- resource_path
Resource path within that module.
- Type:
- schema_version
The
schema_versiondeclared by the file.- Type:
- content_digest
Digest of the resource contents (change detection).
- Type:
- 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".moduleis the dotted path of the owning directory andresource_pathis 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-fileloadoutput (SchemaDocument).
compilation- the resolvedcompileoutput (CompiledSchemaand 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:
objectA resolved definition plus every source that contributed to it.
The kind of definition is not stored:
definitionis a typed union andCompiledSchemaalready 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:
- 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:
objectThe full set of resolved static definitions (output of
compile).Keyed by stable identifier. This is what the renderer turns into Casbin
prows and what the applier persists alongside source records.- 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
prows. Pairs are returned in a deterministic order (role id, then permission id) so downstream rendering and diffing are stable across runs.
- class openedx_authz.engine.schema.types.ParsedSchemaDocument(source: SourceRecord, data: object)
Bases:
objectOne 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:
objectA display/grouping category for permissions. Grants no access.
- description: str
- display_name: str
- 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:
objectA 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
- property identifier: str
Complete permission ID, e.g.
"courses.view_course".
- name: str
- namespace: str
- class openedx_authz.engine.schema.types.RelationshipSource(source: SourceRecord, origin_kind: SchemaOriginKind, priority: int)
Bases:
objectProvenance 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) orSchemaOriginKind.EXTENSION(added by arole_extensionsentry).- Type:
openedx_authz.constants.schema.SchemaOriginKind
- priority
The contributing file’s priority.
- Type:
- 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:
objectA static role listing every permission assigned to it.
hiddenmirrors 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
- id: 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:
objectA 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.hiddenis tri-state:Noneleaves the current value untouched.- 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:
objectOne loaded
.yamlschema file plus its provenance and priority.Output of the
loadstep. Still per-file: cross-file references are not yet resolved (that happens duringcompile).- 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:
SourceRecordSource record for a filesystem-path schema resource (ADR 0030).
Overrides
source_idto use the absolute path directly, since the parent’smodule.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:
objectIdentifies 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
SourceRecordthat 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:
- distribution_version
Version of that distribution.
- Type:
- module
Python module that owns the resource.
- Type:
- resource_path
Resource path within that module.
- Type:
- schema_version
The
schema_versiondeclared by the file.- Type:
- content_digest
Digest of the resource contents (change detection).
- Type:
- 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".moduleis the dotted path of the owning directory andresource_pathis anchor-relative (so it may repeat the directory); only the file name is appended here to avoid duplicating the directory segments.