lms.model.users

  1import enum
  2import typing
  3
  4import lms.model.base
  5import lms.model.query
  6
  7class UserQuery(lms.model.query.BaseQuery):
  8    """
  9    A class for the different ways one can attempt to reference an LMS user.
 10    In general, a user can be queried by:
 11     - LMS User ID (`id`)
 12     - Email (`email`)
 13     - Full Name (`name`)
 14     - f"{email} ({id})"
 15     - f"{name} ({id})"
 16    """
 17
 18    _include_email = True
 19
 20class ResolvedUserQuery(lms.model.query.ResolvedBaseQuery, UserQuery):
 21    """
 22    A UserQuery that has been resolved (verified) from a real user instance.
 23    """
 24
 25    _include_email = True
 26
 27    def __init__(self,
 28            user: 'ServerUser',
 29            **kwargs: typing.Any) -> None:
 30        super().__init__(id = user.id, name = user.name, email = user.email, **kwargs)
 31
 32class CourseRole(enum.Enum):
 33    """
 34    Different roles a user can have in a course.
 35    LMSs represent this information very differently, so this is only a general collection of roles.
 36    """
 37
 38    OTHER = 'other'
 39    STUDENT = 'student'
 40    GRADER = 'grader'
 41    ADMIN = 'admin'
 42    OWNER = 'owner'
 43
 44    def __str__(self) -> str:
 45        return str(self.value)
 46
 47class ServerUser(lms.model.base.BaseType):
 48    """
 49    A user associated with an LMS server.
 50    """
 51
 52    CORE_FIELDS = ['id', 'name', 'email']
 53    """ The common fields shared across backends for this type. """
 54
 55    def __init__(self,
 56            id: typing.Union[str, int, None] = None,
 57            email: typing.Union[str, None] = None,
 58            name: typing.Union[str, None] = None,
 59            **kwargs: typing.Any) -> None:
 60        super().__init__(**kwargs)
 61
 62        if (id is None):
 63            raise ValueError("User must have an id.")
 64
 65        self.id: str = str(id)
 66        """ The LMS's identifier for this user. """
 67
 68        self.name: typing.Union[str, None] = name
 69        """ The display name of this user. """
 70
 71        self.email: typing.Union[str, None] = email
 72        """ The email address of this user. """
 73
 74    def to_query(self) -> ResolvedUserQuery:
 75        """ Get a query representation of this user. """
 76
 77        return ResolvedUserQuery(self)
 78
 79class CourseUser(ServerUser):
 80    """
 81    A user associated with a course, e.g., an instructor or student.
 82    """
 83
 84    CORE_FIELDS = ServerUser.CORE_FIELDS + ['role']
 85    """ The common fields shared across backends for this type. """
 86
 87    def __init__(self,
 88            role: typing.Union[CourseRole, None] = None,
 89            raw_role: typing.Union[str, None] = None,
 90            **kwargs: typing.Any) -> None:
 91        super().__init__(**kwargs)
 92
 93        self.role: typing.Union[CourseRole, None] = role
 94        """ The role of this user within this course (e.g., owner, student). """
 95
 96        self.raw_role: typing.Union[str, None] = raw_role
 97        """
 98        The raw role string from the LMS.
 99        This may not translate nicely into one of our known roles.
100        """
101
102    def is_student(self) -> bool:
103        """
104        Check if this course user is a student (and therefore be included in graded components like gradebooks).
105        Backends should implement this method.
106        """
107
108        return (self.role == CourseRole.STUDENT)