Data model

.gitignore

@@ -9,3 +9,6 @@ frontend/static/README.md
 .pytest_cache/
 tests/test_db/data.py
 !test_database.json
+
+# Generated test files
+test_resources/data_model_test_dir*

Pipfile

@@ -16,6 +16,8 @@ maya = "*"
 pytest = "*"
 flask = "*"
 pylint = "*"
+flask-inputs = "*"
+jsonschema = "*"
 
 
 [dev-packages]

owl/access.py

@@ -0,0 +1,231 @@
+"""
+Intermediary module facilitating access of model.
+
+Methods contained are distinct from those in owl.model because they
+are intended primarily for the convenience of the user facing module
+(server.py) and contain methods and classes that may result in user-
+feedback (eg: AccessException's user_msg and similar).
+
+Methods and classes are separate from server.py because they deal
+primarily with access and retrieval of data, and not the form of the
+response to the api user's request.
+"""
+import typing as ty
+
+import owl.model
+import owl.filter
+
+
+# Access Argument keywords
+ANY = 'any'
+ALL = 'all'
+LATEST = 'latest'
+
+
+class AccessException(ValueError):
+    """
+    Exception raised when requested data cannot be accessed, but not as
+    result of an internal error or bug, or badly a badly formed
+    request. This usually is because the requested data does not exist.
+    """
+    def __init__(self, *args, user_msg='Bad Request'):
+        super().__init__(*args)
+        self.user_msg = user_msg
+
+
+class ModelAccessor:
+    """
+    Handles access of data from a specific data model.
+    """
+    def __init__(self, model: owl.model.DataModel) -> None:
+        self.model = model
+
+    # This method may be removed in the future if the get_one
+    # method path is removed.
+    def get_one(
+            self,
+            school: str,
+            department: str,
+            course: str = ALL,
+            quarter: str = LATEST,
+            section_filter: owl.filter.SectionFilter = None
+    ) -> ty.Union[owl.model.COURSE_DATA_T, owl.model.DEPT_DATA_T]:
+        """
+        Retrieves data for a department or course, as identified by
+        the api user.
+        If no course is passed, all of the specified department's data
+        is returned.
+        :param school: str (ex: 'fh')
+        :param department: str (ex: 'CS')
+        :param course: str (ex: 1A) (optional)
+        :param quarter: str (ex: '201812')
+        :param section_filter: filter kwargs
+        :return: COURSE_DATA_T or DEPT_DATA_T
+        """
+        if course == ALL:
+            return self.get_department_data(
+                school, department, quarter, section_filter)
+        return self.get_course_data(
+            school, department, course, quarter, section_filter)
+
+    def get_department_data(
+            self,
+            school: str,
+            department: str,
+            quarter: str = LATEST,
+            section_filter: owl.filter.SectionFilter = None
+    ) -> owl.model.DEPT_DATA_T:
+        """
+        Gets data for a specific department in a single quarter.
+        :param school: str (ex: 'fh')
+        :param department: str (ex: 'CS')
+        :param quarter: str (ex: '201812')
+        :param section_filter: filter kwargs
+        :return: DEPT_DATA_T
+        """
+        # Find department view
+        department_view = self.get_department(school, department, quarter)
+
+        # get data from department view
+        return {
+            course_view.name: {
+                section_view.crn: section_view.data for
+                section_view in course_view.sections if
+                not section_filter or section_filter.check(section_view)
+            }
+            for course_view in department_view.courses
+        }
+
+    def get_course_data(
+            self,
+            school: str,
+            department: str,
+            course: str,
+            quarter: str = LATEST,
+            section_filter: owl.filter.SectionFilter = None
+    ) -> owl.model.COURSE_DATA_T:
+        """
+        Gets data for a specific course in a specific quarter.
+        :param school: str (ex: 'fh')
+        :param department: str (ex: 'CS')
+        :param course: str (ex: '1A')
+        :param quarter: str (ex: '201812')
+        :param section_filter: filter kwargs
+        :return: COURSE_DATA_T
+        """
+        # Find department view
+        course_view = self.get_course(school, department, course, quarter)
+        return {
+            section_view.crn: section_view.data for
+            section_view in course_view.sections if
+            not section_filter or section_filter.check(section_view)
+        }
+
+    def get_quarter(
+            self,
+            school: str,
+            quarter: str = LATEST,
+    ) -> 'owl.model.QuarterView':
+        """
+        Gets QuarterView, throwing readable access errors in the event
+        that a passed value is not found.
+        :param school: str (ex: 'fh')
+        :param quarter: str (ex: '201812')
+        :return: QuarterView
+        """
+        try:
+            school_view: owl.model.SchoolView = \
+                self.model.schools[school.upper()]
+        except KeyError as e:
+            raise AccessException(
+                f'No school found with identifier: {school}.') from e
+        try:
+            if quarter == LATEST:
+                quarter_view = school_view.latest_quarter
+            else:
+                quarter_view = school_view.quarters[quarter]
+        except KeyError as e:
+            raise AccessException(
+                f'No quarter in {school} with name: {quarter}.') from e
+        return quarter_view
+
+    def get_department(
+            self,
+            school: str,
+            department: str,
+            quarter: str = LATEST,
+    ) -> owl.model.DepartmentQuarterView:
+        """
+        Gets department view of department data for a specific quarter.
+        :param school: str (ex: 'fh')
+        :param department: str (ex: 'CS')
+        :param quarter: str (ex: '201812')
+        :return: DepartmentQuarterView
+        """
+        quarter_view = self.get_quarter(school, quarter)
+        try:
+            department_view = quarter_view.departments[department]
+        except KeyError as e:
+            raise AccessException(
+                f'No department in {quarter} with name: {department}.') from e
+        return department_view
+
+    def get_course(
+            self,
+            school: str,
+            department: str,
+            course: str,
+            quarter: str = LATEST,
+    ) -> owl.model.CourseQuarterView:
+        """
+        Gets view of data for a specific course in a specific quarter.
+        :param school: str (ex: 'fh')
+        :param department: str (ex: 'CS')
+        :param course: str (ex: '1A')
+        :param quarter: str (ex: '201812')
+        :return: CourseQuarterView
+        """
+        department_view = self.get_department(school, department, quarter)
+        try:
+            course_view = department_view.courses[course]
+        except KeyError as e:
+            raise AccessException(
+                f'No course in {department} with name: {course}.') from e
+        return course_view
+
+    def get_section(
+            self,
+            school: str,
+            department: str,
+            course: str,
+            section: str,
+            quarter: str = LATEST,
+    ) -> owl.model.SectionQuarterView:
+        """
+        Gets view of data for a specific section in a specific quarter.
+        :param school: str (ex: 'fh')
+        :param department: str (ex: 'CS')
+        :param course: str (ex: '1A')
+        :param quarter: str (ex: '201812')
+        :param section: str (ex: '12345')
+        :return: SectionQuarterView
+        """
+        course_view = self.get_course(school, department, course, quarter)
+        try:
+            section_view = course_view.sections[section]
+        except KeyError as e:
+            raise AccessException(
+                f'No section in {course} with name: {section}.') from e
+        return section_view
+
+    def get_urls(
+            self, school: str, quarter: str = LATEST
+    ) -> ty.Dict[str, ty.Dict[str, str]]:
+        """
+        Helps list all courses, their names and departments.
+        :param school: str (ex: 'fh')
+        :param quarter: str (ex: '201812')
+        :return: Dict[str, Dict[str, str]]
+        """
+        quarter_view = self.get_quarter(school, quarter)
+        return quarter_view.urls

owl/filter.py

@@ -0,0 +1,109 @@
+"""
+Contains classes and methods for filtering data.
+"""
+
+import typing as ty
+import maya
+
+import owl.model
+
+# Keys
+MONDAY_KEY = 'M'
+TUESDAY_KEY = 'T'
+WEDNESDAY_KEY = 'W'
+THURSDAY_KEY = 'Th'
+FRIDAY_KEY = 'F'
+SATURDAY_KEY = 'S'
+SUNDAY_KEY = 'U'
+
+# Filter Argument keywords
+ANY = 'any'
+ALL = 'all'
+
+
+class SectionFilter:
+    """
+    Filters courses based on passed parameters.
+    """
+    def __init__(
+            self,
+            status: ty.Dict[str, int] = None,
+            types: ty.Dict[str, int] = None,
+            days: ty.Dict[str, int] = None,
+            time: ty.Dict[str, str] = None,
+            instructors: ty.Dict[str, int] = None,
+            conflict_sections: ty.Set[owl.model.SectionQuarterView] = None
+    ):
+        self.status = status
+        self.types = types
+        self.days = days
+        self.time = time
+        self.instructors = instructors
+        self.conflict_sections = conflict_sections
+
+    def check(self, section: owl.model.SectionQuarterView) -> bool:
+        """
+        Determines whether passed course passes filter
+        :param section: owl.model.SectionQuarterView
+        :return: bool (True if section passes filters)
+        """
+
+        # Nested functions filter courses by taking a course key and
+        # returning a boolean indicating whether they should be included
+        # or excluded. True if they are to be included, False if excluded.
+
+        def status_filter() -> bool:
+            # {'open':0, 'waitlist':0, 'full':0}
+            if not self.status:
+                return True
+            # Create 'mask' of course statuses that are to be included.
+            status_mask = {k for (k, v) in self.status.items() if v}
+            # Return True only if course status is in mask.
+            return section.status in status_mask
+
+        def type_filter() -> bool:
+            # {'standard':1, 'online':1, 'hybrid':0}
+            if not self.types:
+                return True
+            # Get course section
+            mask = {k for (k, v) in self.types.items() if v}
+            return section.section_type in mask
+
+        def day_filter() -> bool:
+            # {'M':1, 'T':0, 'W':1, 'Th':0, 'F':0, 'S':0, 'U':0}
+            if not self.days:
+                return True
+            # create set of days that are allowed by passed filters
+            mask = {k for (k, v) in self.days.items() if v}
+            return section.days <= mask
+
+        def time_filter() -> bool:
+            # {'start':'8:30 AM', 'end':'9:40 PM'}
+            if not self.time:
+                return True
+            filter_range = maya.MayaInterval(
+                start=maya.when(self.time['start']),
+                end=maya.when(self.time['end']))
+            for duration in section.durations:
+                if not filter_range.contains(duration.interval):
+                    return False
+            return True
+
+        def instructor_filter() -> bool:
+            if not self.instructors:
+                return True
+            return section.instructor_name in \
+                {k for k, v in self.instructors.items() if v}
+
+        def conflict_filter() -> bool:
+            if not self.conflict_sections:
+                return True
+            for conflict_section in self.conflict_sections:
+                if section.conflicts(conflict_section):
+                    return False
+            return True
+
+        return all((
+            status_filter(), type_filter(), day_filter(), time_filter(),
+            instructor_filter(), conflict_filter()
+        ))