[POC] Typing ergonomics and guarantees

changes/2252.misc.rst

@@ -0,0 +1 @@
+Toga's API typing is now tested.

core/pyproject.toml

@@ -66,13 +66,16 @@ dependencies = [
 # ensure environment consistency.
 dev = [
     "coverage[toml] == 7.3.2",
+    "mypy == 1.7.1",
     "Pillow == 10.1.0",
     "pre-commit == 3.5.0",
     "pytest == 7.4.3",
     "pytest-asyncio == 0.21.1",
     "pytest-freezer == 0.4.8",
     "setuptools-scm == 8.0.4",
     "tox == 4.11.3",
+    "types-Pillow == 10.1.0.2",
+    "typing-extensions == 4.8.0",
 ]
 docs = [
     "furo == 2023.9.10",

core/src/toga/images.py

@@ -103,9 +103,9 @@ def __init__(
             raise TypeError("Unsupported source type for Image")
 
     @property
-    def size(self) -> (int, int):
+    def size(self) -> tuple[int, int]:
         """The size of the image, as a (width, height) tuple."""
-        return (self._impl.get_width(), self._impl.get_height())
+        return self._impl.get_width(), self._impl.get_height()
 
     @property
     def width(self) -> int:

core/src/toga/style/__init__.py

@@ -1,2 +1,2 @@
 from toga.style.applicator import TogaApplicator  # noqa: F401
-from toga.style.pack import Pack  # noqa: F401
+from toga.style.pack import Pack as Pack  # noqa: F401

core/src/toga/style/pack.py

@@ -2,7 +2,7 @@
     BOLD,
     BOTTOM,
     CENTER,
-    COLUMN,
+    COLUMN as COLUMN,
     CURSIVE,
     FANTASY,
     HIDDEN,
@@ -15,7 +15,7 @@
     NORMAL,
     OBLIQUE,
     RIGHT,
-    ROW,
+    ROW as ROW,
     RTL,
     SANS_SERIF,
     SERIF,

core/tests/api_interface/images.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import PIL.Image
+from typing_extensions import assert_type
+
+import toga
+
+assert_type(toga.Image().size, tuple[int, int])
+
+assert_type(toga.Image().width, int)
+
+assert_type(toga.Image().height, int)
+
+assert_type(toga.Image().data, bytes)
+
+assert_type(toga.Image().path, "Path | None")
+
+assert_type(toga.Image().save(path="/data"), None)
+assert_type(toga.Image().save(path=Path("/data")), None)
+
+assert_type(toga.Image().as_format(toga.Image), toga.Image)
+assert_type(toga.Image().as_format(PIL.Image.Image), PIL.Image.Image)

pyproject.toml

@@ -72,3 +72,27 @@ type = [
 # We're not doing anything Python-related at the root level of the repo, but if this
 # declaration isn't here, tox commands run from the root directory raise a warning that
 # pyproject.toml doesn't contain a setuptools_scm section.
+
+[tool.mypy]
+python_version = 3.8
+check_untyped_defs = true
+disallow_any_decorated = true
+disallow_any_explicit = true
+disallow_any_expr = false  # can be difficult...
+disallow_any_generics = true
+disallow_any_unimported = true
+disallow_incomplete_defs = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+disallow_untyped_decorators = true
+disallow_untyped_defs = true
+implicit_reexport = false
+no_implicit_optional = true
+no_warn_no_return = true
+strict_equality = true
+strict = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unreachable = true
+warn_unused_configs = true
+warn_unused_ignores = true

tox.ini

@@ -17,6 +17,7 @@ allowlist_externals =
 commands =
     # TOGA_INSTALL_COMMAND is set to a bash command by the CI workflow.
     {env:TOGA_INSTALL_COMMAND:python -m pip install .[dev] ../dummy}
+    mypy --config ../pyproject.toml ./tests/api_interface/
     {env:test_command_prefix:} coverage run -m pytest -vv {posargs}
     coverage combine
     coverage report --rcfile ../pyproject.toml