Use typeshed stubs for more complete static analysis of CircuitPython code (#304)

Author: nateinaction

.gitignore

@@ -13,3 +13,4 @@ build/
 pysquared.egg-info/
 **/*.mpy
 site/
+typeshed/

.pre-commit-config.yaml

@@ -21,6 +21,18 @@ repos:
         entry: '# type:? *ignore'
         language: pygrep
         types: [python]
+        files: ^pysquared/
+        exclude: ^pysquared/beacon\.py|^pysquared/logger\.py|^pysquared/rtc/manager/microcontroller\.py
+
+  - repo: local
+    hooks:
+      - id: prevent-pyright-ignore
+        name: prevent pyright ignore annotations
+        description: 'Enforce that no `# type: ignore` annotations exist in the codebase.'
+        entry: '# pyright:? *.*false'
+        language: pygrep
+        types: [python]
+        files: ^pysquared/
 
   - repo: https://github.com/codespell-project/codespell
     rev: v2.4.1

Makefile

@@ -1,5 +1,5 @@
 .PHONY: all
-all: .venv pre-commit-install
+all: .venv typeshed pre-commit-install
 
 .PHONY: help
 help: ## Display this help.
@@ -13,6 +13,11 @@ help: ## Display this help.
 	@$(UV) venv
 	@$(UV) pip install --requirement pyproject.toml
 
+typeshed: ## Install CircuitPython typeshed stubs
+	@echo "Installing CircuitPython typeshed stubs..."
+	@$(MAKE) uv
+	@$(UV) pip install circuitpython-typeshed==0.1.0 --target typeshed
+
 .PHONY: pre-commit-install
 pre-commit-install: uv
 	@echo "Installing pre-commit hooks..."
@@ -22,7 +27,8 @@ pre-commit-install: uv
 fmt: pre-commit-install ## Lint and format files
 	$(UVX) pre-commit run --all-files
 
-typecheck: .venv ## Run type check
+.PHONY: typecheck
+typecheck: .venv typeshed ## Run type check
 	@$(UV) run -m pyright .
 
 .PHONY: test
@@ -68,7 +74,7 @@ $(TOOLS_DIR):
 	mkdir -p $(TOOLS_DIR)
 
 ### Tool Versions
-UV_VERSION ?= 0.7.13
+UV_VERSION ?= 0.8.14
 MPY_CROSS_VERSION ?= 9.0.5
 
 UV_DIR ?= $(TOOLS_DIR)/uv-$(UV_VERSION)

docs/design-guide.md

@@ -19,7 +19,19 @@ PySquared is built on top of CircuitPython, which is a version of Python designe
 
 We use type hints throughout the PySquared codebase to ensure that our code is clear and maintainable. Type hints help us catch errors early and make it easier to understand the expected types of variables and function parameters.
 
-We do not accept changes with lines that are ignored the type checker i.e. `# type: ignore`. If you run into an issue where you think you need to ignore a type, it is likely a problem with the design of your component. Please take a moment to think about how you can fix the type error instead. If you need help, please reach out for assistance.
+We use [typeshed](https://peps.python.org/pep-0561/) stubs to provide more accurate type hints for CircuitPython, replacing the default Python standard library type hints. These CircuitPython-specific stubs are located in the `typeshed/` directory. This helps the typechecker catch compatibility issues with CircuitPython code before running it on a device.
+
+However, using these stubs means that type hints in test files also reference CircuitPython types, not the standard Python types available in the test environment. As a workaround, we add pyright ignore comments (e.g., `# pyright: reportOptionalMemberAccess=false`) when necessary at the top of test files to suppress related errors. This workaround isn’t ideal. If you have suggestions for handling this issue more effectively, please share your feedback.
+
+We do not accept changes to files in the `pysquared/` directory that include lines ignoring the type checker (e.g., `# type: ignore`). The only exceptions are:
+
+- **Upstream Fix in Progress:** If a type error is caused by a bug or limitation in an external dependency, you may ignore the line only when leaving a comment with a link to the issue or PR where it is fixed or a fix is in progress. A valid type hint might look like this:
+
+    ```python
+    some_variable = some_function()  # type: ignore  # PR https://github.com/adafruit/circuitpython/pull/10603
+    ```
+
+If you encounter a type error, first consider if it can be resolved by improving your code's design. If you believe an exception is necessary, please reach out for assistance before proceeding.
 
 ??? note "Using the Typing Module"
     For more advanced type hinting we can use the Python standard library's `typing` module which was introduced in Python 3.5. This module provides a variety of type hints that can be used to specify more complex types, such as `List`, `Dict`, and `Optional`. CircuitPython does not support the `typing` module so we must wrap the import in a try/except block to avoid import errors. For example:

mocks/circuitpython/busio.py

@@ -5,11 +5,9 @@
 the need for actual hardware.
 """
 
-from __future__ import annotations
-
 from typing import Optional
 
-import mocks.circuitpython.microcontroller as microcontroller
+import microcontroller
 
 
 class SPI:

mocks/circuitpython/digitalio.py

@@ -5,9 +5,7 @@
 the need for actual hardware.
 """
 
-from __future__ import annotations
-
-import mocks.circuitpython.microcontroller as microcontroller
+import microcontroller
 
 
 class DriveMode:

pyproject.toml

@@ -29,7 +29,7 @@ dev = [
     "coverage==7.9.1",
     "freezegun>=1.5.2",
     "pre-commit==4.2.0",
-    "pyright[nodejs]==1.1.402",
+    "pyright[nodejs]==1.1.404",
     "pytest==8.4.1",
     "hypothesis==6.136.7",
 ]
@@ -92,15 +92,18 @@ directory = ".coverage-reports/html"
 [tool.coverage.xml]
 output = ".coverage-reports/coverage.xml"
 
+[tool.ty.environment]
+typeshed = "./typeshed"
+
 [tool.pyright]
 include = ["pysquared"]
 exclude = [
     "**/__pycache__",
     ".venv",
     ".git",
-    "typings",
+    "typeshed",
 ]
-stubPath = "./typings"
+typeshedPath = "./typeshed"
 reportMissingModuleSource = false
 
 [tool.interrogate]
@@ -109,3 +112,6 @@ omit-covered-files = true
 fail-under = 100
 verbose = 2
 color = true
+exclude = [
+    "typeshed",
+]

pysquared/beacon.py

@@ -109,10 +109,9 @@ def _add_system_info(self, state: OrderedDict[str, object]) -> None:
         """
         state["name"] = self._name
 
-        # Warning: CircuitPython does not support time.gmtime(), when testing this code it will use your local timezone
-        now = time.localtime()
+        now = time.localtime()  # type: ignore # PR: https://github.com/adafruit/circuitpython/pull/10603
         state["time"] = (
-            f"{now.tm_year}-{now.tm_mon:02d}-{now.tm_mday:02d} {now.tm_hour:02d}:{now.tm_min:02d}:{now.tm_sec:02d}"
+            f"{now.tm_year}-{now.tm_mon:02d}-{now.tm_mday:02d} {now.tm_hour:02d}:{now.tm_min:02d}:{now.tm_sec:02d}"  # type: ignore # PR: https://github.com/adafruit/circuitpython/pull/10603
         )
 
         state["uptime"] = time.time() - self._boot_time

pysquared/logger.py

@@ -129,8 +129,8 @@ def _log(self, level: str, level_value: int, message: str, **kwargs) -> None:
             message (str): The log message.
             **kwargs: Additional key/value pairs to include in the log.
         """
-        now = time.localtime()
-        asctime = f"{now.tm_year}-{now.tm_mon:02d}-{now.tm_mday:02d} {now.tm_hour:02d}:{now.tm_min:02d}:{now.tm_sec:02d}"
+        now = time.localtime()  # type: ignore # PR: https://github.com/adafruit/circuitpython/pull/10603
+        asctime = f"{now.tm_year}-{now.tm_mon:02d}-{now.tm_mday:02d} {now.tm_hour:02d}:{now.tm_min:02d}:{now.tm_sec:02d}"  # type: ignore # PR: https://github.com/adafruit/circuitpython/pull/10603
 
         # case where someone used debug, info, or warning yet also provides an 'err' kwarg with an Exception
         if (

pysquared/rtc/manager/microcontroller.py

@@ -30,7 +30,7 @@ def __init__(self) -> None:
         This method is required on every boot to ensure the RTC is ready for use.
         """
         microcontroller_rtc = rtc.RTC()
-        microcontroller_rtc.datetime = time.localtime()
+        microcontroller_rtc.datetime = time.localtime()  # type: ignore # PR: https://github.com/adafruit/circuitpython/pull/10603
 
     def set_time(
         self,