Further Python 3 type annotations on top-level files

Author: aliniknejad

nbgrader/coursedir.py

@@ -7,6 +7,9 @@
 from traitlets import Integer, Bool, Unicode, List, default, validate, TraitError
 
 from .utils import full_split, parse_utc
+from traitlets.utils.bunch import Bunch
+import datetime
+from typing import Optional
 
 
 class CourseDirectory(LoggingConfigurable):
@@ -50,7 +53,7 @@ def _validate_course_id(self, proposal):
     ).tag(config=True)
 
     @validate('student_id')
-    def _validate_student_id(self, proposal):
+    def _validate_student_id(self, proposal: Bunch) -> str:
         if proposal['value'].strip() != proposal['value']:
             self.log.warning("student_id '%s' has trailing whitespace, stripping it away", proposal['value'])
         return proposal['value'].strip()
@@ -80,7 +83,7 @@ def _validate_student_id(self, proposal):
     ).tag(config=True)
 
     @validate('assignment_id')
-    def _validate_assignment_id(self, proposal):
+    def _validate_assignment_id(self, proposal: Bunch) -> str:
         if '+' in proposal['value']:
             raise TraitError('Assignment names should not contain the following characters: +')
         if proposal['value'].strip() != proposal['value']:
@@ -98,7 +101,7 @@ def _validate_assignment_id(self, proposal):
     ).tag(config=True)
 
     @validate('notebook_id')
-    def _validate_notebook_id(self, proposal):
+    def _validate_notebook_id(self, proposal: Bunch) -> str:
         if proposal['value'].strip() != proposal['value']:
             self.log.warning("notebook_id '%s' has trailing whitespace, stripping it away", proposal['value'])
         return proposal['value'].strip()
@@ -248,11 +251,11 @@ def _db_url_default(self):
     ).tag(config=True)
 
     @default("root")
-    def _root_default(self):
+    def _root_default(self) -> str:
         return os.getcwd()
 
     @validate('root')
-    def _validate_root(self, proposal):
+    def _validate_root(self, proposal: Bunch) -> str:
         path = os.path.abspath(proposal['value'])
         if path != proposal['value']:
             self.log.warning("root '%s' is not absolute, standardizing it to '%s", proposal['value'], path)
@@ -298,7 +301,7 @@ def _validate_root(self, proposal):
         )
     ).tag(config=True)
 
-    def format_path(self, nbgrader_step, student_id, assignment_id, escape=False):
+    def format_path(self, nbgrader_step: str, student_id: str, assignment_id: str, escape: bool = False) -> str:
         kwargs = dict(
             nbgrader_step=nbgrader_step,
             student_id=student_id,
@@ -314,7 +317,7 @@ def format_path(self, nbgrader_step, student_id, assignment_id, escape=False):
 
         return path
 
-    def get_existing_timestamp(self, dest_path):
+    def get_existing_timestamp(self, dest_path: str) -> Optional[datetime.datetime]:
         """Get the timestamp, as a datetime object, of an existing submission."""
         timestamp_path = os.path.join(dest_path, 'timestamp.txt')
         if os.path.exists(timestamp_path):

nbgrader/dbutil.py

@@ -8,14 +8,15 @@
 
 from contextlib import contextmanager
 from subprocess import check_call
+from typing import Iterator
 
 _here = os.path.abspath(os.path.dirname(__file__))
 
 ALEMBIC_INI_TEMPLATE_PATH = os.path.join(_here, 'alembic.ini')
 ALEMBIC_DIR = os.path.join(_here, 'alembic')
 
 
-def write_alembic_ini(alembic_ini='alembic.ini', db_url='sqlite:///gradebook.db'):
+def write_alembic_ini(alembic_ini: str = 'alembic.ini', db_url: str = 'sqlite:///gradebook.db') -> None:
     """Write a complete alembic.ini from our template.
     Parameters
     ----------
@@ -37,17 +38,17 @@ def write_alembic_ini(alembic_ini='alembic.ini', db_url='sqlite:///gradebook.db'
 
 
 @contextmanager
-def _temp_alembic_ini(db_url):
+def _temp_alembic_ini(db_url: str) -> Iterator[str]:
     """Context manager for temporary JupyterHub alembic directory
     Temporarily write an alembic.ini file for use with alembic migration scripts.
     Context manager yields alembic.ini path.
     Parameters
     ----------
-    db_url: str
+    db_url:
         The SQLAlchemy database url, e.g. `sqlite:///gradebook.db`.
     Returns
     -------
-    alembic_ini: str
+    alembic_ini:
         The path to the temporary alembic.ini that we have created.
         This file will be cleaned up on exit from the context manager.
     """

nbgrader/utils.py

@@ -17,6 +17,9 @@
 from tornado.log import LogFormatter
 from dateutil.tz import gettz
 from datetime import datetime
+from nbformat.notebooknode import NotebookNode
+from logging import Logger
+from typing import Optional, Tuple, Union, List, Iterator, Any
 
 # pwd is for unix passwords only, so we shouldn't import it on
 # windows machines
@@ -26,28 +29,28 @@
     pwd = None
 
 
-def is_task(cell):
+def is_task(cell: NotebookNode) -> bool:
     """Returns True if the cell is a task cell."""
     if 'nbgrader' not in cell.metadata:
         return False
     return cell.metadata['nbgrader'].get('task', False)
 
 
-def is_grade(cell):
+def is_grade(cell: NotebookNode) -> bool:
     """Returns True if the cell is a grade cell."""
     if 'nbgrader' not in cell.metadata:
         return False
     return cell.metadata['nbgrader'].get('grade', False)
 
 
-def is_solution(cell):
+def is_solution(cell: NotebookNode) -> bool:
     """Returns True if the cell is a solution cell."""
     if 'nbgrader' not in cell.metadata:
         return False
     return cell.metadata['nbgrader'].get('solution', False)
 
 
-def is_locked(cell):
+def is_locked(cell: NotebookNode) -> bool:
     """Returns True if the cell source is locked (will be overwritten)."""
     if 'nbgrader' not in cell.metadata:
         return False
@@ -90,7 +93,8 @@ def get_partial_grade(output, max_points, log=None):
             log.warning(warning_msg)
         return max_points
 
-def determine_grade(cell, log=None):
+
+def determine_grade(cell: NotebookNode, log: Logger = None) -> Tuple[Optional[float], float]:
     if not is_grade(cell):
         raise ValueError("cell is not a grade cell")
 
@@ -126,12 +130,12 @@ def determine_grade(cell, log=None):
         return None, max_points
 
 
-def to_bytes(string):
+def to_bytes(string: str) -> bytes:
     """A helper function for converting a string to bytes with utf-8 encoding."""
     return bytes(string.encode('utf-8'))
 
 
-def compute_checksum(cell):
+def compute_checksum(cell: NotebookNode) -> str:
     m = hashlib.md5()
     # add the cell source and type
     m.update(to_bytes(cell.source))
@@ -152,7 +156,7 @@ def compute_checksum(cell):
     return m.hexdigest()
 
 
-def parse_utc(ts):
+def parse_utc(ts: Union[datetime, str]) -> datetime:
     """Parses a timestamp into datetime format, converting it to UTC if necessary."""
     if ts is None:
         return None
@@ -237,7 +241,7 @@ def self_owned(path):
     return get_osusername() == find_owner(os.path.abspath(path))
 
 
-def is_ignored(filename, ignore_globs=None):
+def is_ignored(filename: str, ignore_globs: List[str] = None) -> bool:
     """Determines whether a filename should be ignored, based on whether it
     matches any file glob in the given list. Note that this only matches on the
     base filename itself, not the full path."""
@@ -304,7 +308,7 @@ def ignore_patterns(directory, filelist):
     return ignore_patterns
 
 
-def find_all_files(path, exclude=None):
+def find_all_files(path: str, exclude: List[str] = None) -> List[str]:
     """Recursively finds all filenames rooted at `path`, optionally excluding
     some based on filename globs."""
     files = []
@@ -333,7 +337,7 @@ def find_all_notebooks(path):
     return notebooks
 
 
-def full_split(path):
+def full_split(path: str) -> Tuple[str, ...]:
     rest, last = os.path.split(path)
     if last == path:
         return (path,)
@@ -344,7 +348,7 @@ def full_split(path):
 
 
 @contextlib.contextmanager
-def chdir(dirname):
+def chdir(dirname: str) -> Iterator:
     currdir = os.getcwd()
     if dirname:
         os.chdir(dirname)
@@ -355,8 +359,8 @@ def chdir(dirname):
 
 
 @contextlib.contextmanager
-def setenv(**kwargs):
-    previous_env = { }
+def setenv(**kwargs: Any) -> Iterator:
+    previous_env = {}
     for key, value in kwargs.items():
         previous_env[key] = os.environ.get(value)
         os.environ[key] = value
@@ -368,7 +372,7 @@ def setenv(**kwargs):
             os.environ[key] = previous_env[key]
 
 
-def rmtree(path):
+def rmtree(path: str) -> None:
     # for windows, we need to go through and make sure everything
     # is writeable, otherwise rmtree will fail
     if sys.platform == 'win32':
@@ -381,7 +385,7 @@ def rmtree(path):
     shutil.rmtree(path)
 
 
-def remove(path):
+def remove(path: str) -> None:
     # for windows, we need to make sure that the file is writeable,
     # otherwise remove will fail
     if sys.platform == 'win32':

nbgrader/validator.py

@@ -9,6 +9,8 @@
 
 from .preprocessors import Execute, ClearOutput, CheckCellMetadata
 from . import utils
+from nbformat.notebooknode import NotebookNode
+import typing
 
 
 class Validator(LoggingConfigurable):
@@ -94,7 +96,7 @@ class Validator(LoggingConfigurable):
 
     stream = sys.stdout
 
-    def _indent(self, val):
+    def _indent(self, val: str) -> str:
         lines = val.split("\n")
         new_lines = []
         for line in lines:
@@ -104,7 +106,7 @@ def _indent(self, val):
             new_lines.append(new_line)
         return "\n".join(new_lines)
 
-    def _extract_error(self, cell):
+    def _extract_error(self, cell: NotebookNode) -> str:
         errors = []
 
         # possibilities:
@@ -129,7 +131,7 @@ def _extract_error(self, cell):
 
         return "\n".join(errors)
 
-    def _print_type_changed(self, old_type, new_type, source):
+    def _print_type_changed(self, old_type: str, new_type: str, source: str) -> None:
         self.stream.write("\n" + "=" * self.width + "\n")
         self.stream.write(
             "The following {} cell has changed to a {} cell:\n\n".format(
@@ -141,7 +143,7 @@ def _print_changed(self, source):
         self.stream.write("The following cell has changed:\n\n")
         self.stream.write(self._indent(source) + "\n\n")
 
-    def _print_error(self, source, error):
+    def _print_error(self, source: str, error: str) -> None:
         self.stream.write("\n" + "=" * self.width + "\n")
         self.stream.write("The following cell failed:\n\n")
         self.stream.write(self._indent(source) + "\n\n")
@@ -153,7 +155,7 @@ def _print_pass(self, source):
         self.stream.write("The following cell passed:\n\n")
         self.stream.write(self._indent(source) + "\n\n")
 
-    def _print_num_type_changed(self, num_changed):
+    def _print_num_type_changed(self, num_changed: int) -> None:
         if num_changed == 0:
             return
 
@@ -165,7 +167,7 @@ def _print_num_type_changed(self, num_changed):
                 )
             )
 
-    def _print_num_changed(self, num_changed):
+    def _print_num_changed(self, num_changed: int) -> None:
         if num_changed == 0:
             return
 
@@ -177,7 +179,7 @@ def _print_num_changed(self, num_changed):
                 )
             )
 
-    def _print_num_failed(self, num_failed):
+    def _print_num_failed(self, num_failed: int) -> None:
         if num_failed == 0:
             self.stream.write("Success! Your notebook passes all the tests.\n")
 
@@ -201,7 +203,7 @@ def _print_num_passed(self, num_passed):
                 )
             )
 
-    def _get_type_changed_cells(self, nb):
+    def _get_type_changed_cells(self, nb: NotebookNode) -> typing.List[NotebookNode]:
         changed = []
 
         for cell in nb.cells:
@@ -217,7 +219,7 @@ def _get_type_changed_cells(self, nb):
 
         return changed
 
-    def _get_changed_cells(self, nb):
+    def _get_changed_cells(self, nb: NotebookNode) -> typing.List:
         changed = []
         for cell in nb.cells:
             if not (utils.is_grade(cell) or utils.is_locked(cell)):
@@ -237,7 +239,7 @@ def _get_changed_cells(self, nb):
 
         return changed
 
-    def _get_failed_cells(self, nb):
+    def _get_failed_cells(self, nb: NotebookNode) -> typing.List[NotebookNode]:
         failed = []
         for cell in nb.cells:
             if not (self.validate_all or utils.is_grade(cell) or utils.is_locked(cell)):
@@ -260,7 +262,7 @@ def _get_failed_cells(self, nb):
 
         return failed
 
-    def _get_passed_cells(self, nb):
+    def _get_passed_cells(self, nb: NotebookNode) -> typing.List[NotebookNode]:
         passed = []
         for cell in nb.cells:
             if not (utils.is_grade(cell) or utils.is_locked(cell)):
@@ -278,7 +280,7 @@ def _get_passed_cells(self, nb):
 
         return passed
 
-    def _preprocess(self, nb):
+    def _preprocess(self, nb: NotebookNode) -> NotebookNode:
         resources = {}
         with utils.setenv(NBGRADER_VALIDATING='1'):
             for preprocessor in self.preprocessors:
@@ -290,7 +292,7 @@ def _preprocess(self, nb):
                 nb, resources = pp.preprocess(nb, resources)
         return nb
 
-    def validate(self, filename):
+    def validate(self, filename: str) -> typing.Dict[str, typing.List[typing.Dict[str, str]]]:
         self.log.info("Validating '{}'".format(os.path.abspath(filename)))
         basename = os.path.basename(filename)
         dirname = os.path.dirname(filename)
@@ -336,7 +338,7 @@ def validate(self, filename):
 
         return results
 
-    def validate_and_print(self, filename):
+    def validate_and_print(self, filename: str) -> None:
         results = self.validate(filename)
         type_changed = results.get('type_changed', [])
         changed = results.get('changed', [])