Merge branch 'main' of github.com:proveskit/circuitpy_flight_software into sdcard_logging

Author: nateinaction

.github/workflows/ci.yaml

@@ -37,7 +37,7 @@ jobs:
           name: coverage-report
           path: .coverage-reports/coverage.xml
       - name: SonarQube Scan
-        uses: SonarSource/sonarqube-scan-action@v4.2.1
+        uses: SonarSource/sonarqube-scan-action@v5.3.1
         env:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
   archive:

.gitignore

@@ -3,6 +3,7 @@ __pycache__/
 .coverage*
 .coverage-reports/
 .DS_Store
+.hypothesis
 .venv
 artifacts/
 coverage-reports/
@@ -12,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:
@@ -120,7 +132,7 @@ The following table lists possible sensor properties, their corresponding types
 | duty_cycle       | int                  | 16-bit PWM duty cycle                        |
 | eCO2             | float                | equivalent/estimated CO₂ in ppm              |
 | frequency        | int                  | Hertz (Hz)                                   |
-| gyro             | (float, float, float)| x, y, z radians per second                   |
+| angular velocity | (float, float, float)| x, y, z radians per second                   |
 | light            | float                | non-unit-specific light levels               |
 | lux              | float                | SI lux                                       |
 | magnetic         | (float, float, float)| x, y, z micro-Tesla (uT)                     |

mocks/adafruit_lis2mdl/lis2mdl.py

@@ -5,6 +5,8 @@
 need for actual hardware.
 """
 
+from pysquared.sensor_reading.magnetic import Magnetic
+
 
 class LIS2MDL:
     """A mock LIS2MDL magnetometer."""
@@ -17,4 +19,7 @@ def __init__(self, i2c) -> None:
         """
         self.i2c = i2c
 
-    magnetic: tuple[float, float, float] = (0.0, 0.0, 0.0)
+    @property
+    async def async_magnetic(self):
+        """Asynchronously returns a mock magnetic field vector."""
+        return Magnetic(0.0, 0.0, 0.0)

mocks/adafruit_lsm6ds/lsm6dsox.py

@@ -21,5 +21,5 @@ def __init__(self, i2c_bus: I2C, address: int) -> None:
         ...
 
     acceleration: tuple[float, float, float] = (0.0, 0.0, 0.0)
-    gyro: tuple[float, float, float] = (0.0, 0.0, 0.0)
+    angular_velocity: tuple[float, float, float] = (0.0, 0.0, 0.0)
     temperature: float = 0.0

mocks/adafruit_mcp9808/mcp9808.py

@@ -0,0 +1,24 @@
+"""Mock for the Adafruit MCP9808 temperature sensor.
+
+This module provides a mock implementation of the Adafruit MCP9808 temperature sensor for
+testing purposes. It allows for simulating the behavior of the MCP9808 without the
+need for actual hardware.
+"""
+
+from busio import I2C
+
+
+class MCP9808:
+    """A mock MCP9808 temperature sensor."""
+
+    def __init__(self, i2c: I2C, addr: int) -> None:
+        """Initializes the mock MCP9808.
+
+        Args:
+            i2c: The I2C bus to use.
+            addr: The I2C address of the MCP9808.
+        """
+        self.i2c = i2c
+        self.addr = addr
+
+    temperature = 25.0

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: