feat!: annotate types

BREAKING CHANGE: [Developers only]
Type-checked Python code using the XBlock API will likely need to be
updated in order to continue passing type-checking, since XBlock's
new annotations will trigger mypy (et al) to behave much more strictly.

NO BREAKING CHANGES for site operators, authors, learners, etc.

Author: kdmccormick

CHANGELOG.rst

@@ -5,13 +5,17 @@ Change history for XBlock
 Unreleased
 ----------
 
+6.0.0 - 2024-08-20
+------------------
+
+* added type hints to all public classes, methods, and functions
+
 5.1.0 - 2024-08-07
 ------------------
 
 * added ability to override an XBlock with the 'xblock.v1.overrides' entry point
 * added ability to override an XBlock Aside with the 'xblock_asides.v1.overrides' entry point
 
-
 5.0.0 - 2024-05-30
 ------------------
 

mypy.ini

@@ -4,6 +4,8 @@ ignore_missing_imports = False
 allow_untyped_globals = False
 files =
 	xblock
+exclude =
+	xblock.test
 
 # Ignore web_fragments typing until it has hints.
 [mypy-web_fragments.*]

xblock/__init__.py

@@ -2,4 +2,4 @@
 XBlock Courseware Components
 """
 
-__version__ = '5.1.0'
+__version__ = '6.0.0'

xblock/completable.py

@@ -1,6 +1,7 @@
 """
 This module defines CompletableXBlockMixin and completion mode enumeration.
 """
+from xblock.core import Blocklike, XBlockMixin
 
 
 class XBlockCompletionMode:
@@ -12,7 +13,7 @@ class XBlockCompletionMode:
     EXCLUDED = "excluded"
 
     @classmethod
-    def get_mode(cls, block_class):
+    def get_mode(cls, block_class: Blocklike | type[Blocklike]) -> str:
         """
         Return the effective completion mode for a given block.
 
@@ -21,17 +22,17 @@ def get_mode(cls, block_class):
         return getattr(block_class, 'completion_mode', cls.COMPLETABLE)
 
 
-class CompletableXBlockMixin:
+class CompletableXBlockMixin(XBlockMixin):
     """
     This mixin sets attributes and provides helper method to integrate XBlock with Completion API.
     """
 
-    has_custom_completion = True
-    completion_mode = XBlockCompletionMode.COMPLETABLE
+    has_custom_completion: bool = True
+    completion_mode: str = XBlockCompletionMode.COMPLETABLE
 
     # To read more on the debate about using the terms percent vs ratio, see:
     # https://openedx.atlassian.net/wiki/spaces/OpenDev/pages/245465398/Naming+with+Percent+or+Ratio
-    def emit_completion(self, completion_percent):
+    def emit_completion(self, completion_percent: float) -> None:
         """
         Emits completion event through Completion API.