lms.model.groups

 1import typing
 2
 3import lms.model.base
 4import lms.model.query
 5import lms.model.users
 6
 7class GroupQuery(lms.model.query.BaseQuery):
 8    """
 9    A class for the different ways one can attempt to reference an LMS group.
10    In general, a group can be queried by:
11     - LMS Group ID (`id`)
12     - Full Name (`name`)
13     - f"{name} ({id})"
14    """
15
16    _include_email = False
17
18class ResolvedGroupQuery(lms.model.query.ResolvedBaseQuery, GroupQuery):
19    """
20    A GroupQuery that has been resolved (verified) from a real group instance.
21    """
22
23    _include_email = False
24
25    def __init__(self,
26            group: 'Group',
27            **kwargs: typing.Any) -> None:
28        super().__init__(id = group.id, name = group.name, **kwargs)
29
30class Group(lms.model.base.BaseType):
31    """
32    A formal collection of users.
33    """
34
35    CORE_FIELDS = [
36        'id', 'name',
37    ]
38
39    def __init__(self,
40            id: typing.Union[str, int, None] = None,
41            name: typing.Union[str, None] = None,
42            **kwargs: typing.Any) -> None:
43        super().__init__(**kwargs)
44
45        if (id is None):
46            raise ValueError("Groups must have an id.")
47
48        self.id: str = str(id)
49        """ The LMS's identifier for this group. """
50
51        self.name: typing.Union[str, None] = name
52        """ The display name of this group. """
53
54    def to_query(self) -> ResolvedGroupQuery:
55        """ Get a query representation of this group. """
56
57        return ResolvedGroupQuery(self)
58
59class GroupMembership(lms.model.base.BaseType):
60    """
61    An instance of a user being in a group.
62    """
63
64    CORE_FIELDS = [
65        'group', 'user',
66    ]
67
68    def __init__(self,
69            user: lms.model.users.UserQuery,
70            group: GroupQuery,
71            **kwargs: typing.Any) -> None:
72        super().__init__(**kwargs)
73
74        self.group: GroupQuery = group
75        """ The group the user belongs to. """
76
77        self.user: lms.model.users.UserQuery = user
78        """ The user in a group. """
79
80    def update_queries(self,
81            users: typing.Union[typing.Dict[str, lms.model.users.ResolvedUserQuery], None] = None,
82            groups: typing.Union[typing.Dict[str, ResolvedGroupQuery], None] = None,
83            ) -> None:
84        """
85        Update the queries with resolved variants.
86        The maps should be keyed by respective ids.
87        """
88
89        if ((users is not None) and (self.user.id in users)):
90            self.user = users[self.user.id]
91
92        if ((groups is not None) and (self.group.id in groups)):
93            self.group = groups[self.group.id]