"""The module that defines the ``RestrictionExamEnvironment`` model.
SPDX-License-Identifier: AGPL-3.0-only OR BSD-3-Clause-Clear
"""
from __future__ import annotations
import typing as t
from dataclasses import dataclass, field
import cg_request_args as rqa
from .. import parsers
from ..utils import to_dict
from .exam_environment_provider_description import (
ExamEnvironmentProviderDescription,
)
from .restriction_exam_environment_artifact_preparation import (
RestrictionExamEnvironmentArtifactPreparation,
)
from .restriction_exam_environment_no_preparation import (
RestrictionExamEnvironmentNoPreparation,
)
from .restriction_exam_environment_not_attached import (
RestrictionExamEnvironmentNotAttached,
)
from .restriction_exam_environment_redirect_preparation import (
RestrictionExamEnvironmentRedirectPreparation,
)
[docs]
@dataclass(kw_only=True)
class RestrictionExamEnvironment:
"""The JSON representation of a RestrictionExamEnvironment."""
#: The exam environment the viewer must prepare for before entering,
#: carrying the moment from which preparing is allowed.
preparation: t.Union[
RestrictionExamEnvironmentNoPreparation,
RestrictionExamEnvironmentRedirectPreparation,
RestrictionExamEnvironmentArtifactPreparation,
]
#: The live attached provider's capability description. `not-set` for an
#: anonymous viewer, while the tenant's release flag is off, or when
#: nothing is attached — an archived (detached) config is retained state,
#: not an attached provider.
attached: t.Union[
ExamEnvironmentProviderDescription,
RestrictionExamEnvironmentNotAttached,
]
#: Whether the attached provider's checks are enforced. Turning this off is
#: the escape hatch for a provider outage: verification is skipped at every
#: call site while the provider stays attached, so a running exam continues
#: as a normal locked-down exam. `null` when the viewer is not told:
#: either nothing is attached, so there is no enforcement to report, or
#: they may not edit the restriction. A student who learned an exam was
#: running unenforced would learn they could leave the kiosk unnoticed, so
#: the answer is withheld rather than softened — it is never reported as
#: anything but what it is. A client that offers the setting supplies its
#: own default for `null`; attaching a provider always starts enforced.
verification_enforced: t.Optional[bool]
raw_data: t.Optional[t.Dict[str, t.Any]] = field(init=False, repr=False)
data_parser: t.ClassVar[t.Any] = rqa.Lazy(
lambda: rqa.FixedMapping(
rqa.RequiredArgument(
"preparation",
parsers.make_union(
parsers.ParserFor.make(
RestrictionExamEnvironmentNoPreparation
),
parsers.ParserFor.make(
RestrictionExamEnvironmentRedirectPreparation
),
parsers.ParserFor.make(
RestrictionExamEnvironmentArtifactPreparation
),
),
doc="The exam environment the viewer must prepare for before entering, carrying the moment from which preparing is allowed.",
),
rqa.RequiredArgument(
"attached",
parsers.make_union(
parsers.ParserFor.make(ExamEnvironmentProviderDescription),
parsers.ParserFor.make(
RestrictionExamEnvironmentNotAttached
),
),
doc="The live attached provider's capability description. `not-set` for an anonymous viewer, while the tenant's release flag is off, or when nothing is attached — an archived (detached) config is retained state, not an attached provider.",
),
rqa.RequiredArgument(
"verification_enforced",
rqa.Nullable(rqa.SimpleValue.bool),
doc="Whether the attached provider's checks are enforced. Turning this off is the escape hatch for a provider outage: verification is skipped at every call site while the provider stays attached, so a running exam continues as a normal locked-down exam. `null` when the viewer is not told: either nothing is attached, so there is no enforcement to report, or they may not edit the restriction. A student who learned an exam was running unenforced would learn they could leave the kiosk unnoticed, so the answer is withheld rather than softened — it is never reported as anything but what it is. A client that offers the setting supplies its own default for `null`; attaching a provider always starts enforced.",
),
)
)
def to_dict(self) -> t.Dict[str, t.Any]:
res: t.Dict[str, t.Any] = {
"preparation": to_dict(self.preparation),
"attached": to_dict(self.attached),
"verification_enforced": to_dict(self.verification_enforced),
}
return res
@classmethod
def from_dict(
cls: t.Type[RestrictionExamEnvironment], d: t.Dict[str, t.Any]
) -> RestrictionExamEnvironment:
parsed = cls.data_parser.try_parse(d)
res = cls(
preparation=parsed.preparation,
attached=parsed.attached,
verification_enforced=parsed.verification_enforced,
)
res.raw_data = d
return res