Add the ty type checker (#1116)

nathanjmcdougall · web-flow · commit ec090b51b3b4 · 2025-11-09T11:32:29.000+13:00
* Add the `ty` type checker

Now used in prek instead of pyright. Pyright is still enabled in CI.

* Use consistent return type across all file manager `.read_file` methods

* Fix bug introduced when refactoring in function associated with Bitbucket pipeline anchors

* Revert change in pydantic model dumping utility and disable false positive ty diagnostic

* Remove debug assert statements
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -51,10 +51,11 @@ jobs:
           CI_UV_UPGRADE_ARG: ${{ matrix.dependencies == 'max' && '--upgrade' || '' }}
           UV_RESOLUTION: ${{ matrix.dependencies == 'min' && 'lowest-direct' || 'highest' }}
 
-      - name: Run prek
-        if: ${{ matrix.pre_commit == null || matrix.pre_commit == 'true' }}
+      - name: Run checks
+        if: ${{ matrix.checks == null || matrix.checks == 'true' }}
         run: |
           uv run --frozen prek run --all-files
+          uv run --frozen pyright
 
       - name: Run pytest
         uses: pavelzw/pytest-action@510c5e90c360a185039bea56ce8b3e7e51a16507 # v2.2.0
@@ -105,16 +106,16 @@ jobs:
           - dependencies: "min"
             python_version: "3.10"
             uv_version: "0.6.8"
-            pre_commit: "false"
+            checks: "false"
           - dependencies: "max"
             python_version: "3.14"
-            pre_commit: "false"
+            checks: "false"
           - codecov: "true"
             python_version: "3.14"
 
-            pre_commit: "false"
+            checks: "false"
           - codspeed: "true"
             python_version: "3.13"
 
-            pre_commit: "false"
+            checks: "false"
             pytest: "false"
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -84,9 +84,9 @@ repos:
         pass_filenames: false
   - repo: local
     hooks:
-      - id: pyright
-        name: pyright
-        entry: uv run --frozen --offline pyright
+      - id: ty
+        name: ty
+        entry: uv run --frozen --offline ty check
         language: system
         types_or: [python, pyi]
         always_run: true
diff --git a/pyproject.toml b/pyproject.toml
@@ -62,6 +62,7 @@ dev = [
   "pyinstrument>=5.1.1",
   "pyright[nodejs]>=1.1.399",
   "ruff>=0.14.3",
+  "ty>=0.0.1a25",
 ]
 test = [
   "click>=8.1.8",
@@ -179,6 +180,17 @@ exclude_also = [
 ]
 omit = [ "*/pytest-of-*/*", "*/_temp/*" ]
 
+[tool.ty]
+environment.python-platform = "all"
+rules.type-assertion-failure = "ignore"
+
+[[tool.ty.overrides]]
+include = [ "src/usethis/_integrations/file/**" ]
+rules.invalid-argument-type = "ignore"
+rules.invalid-return-type = "ignore"
+rules.invalid-assignment = "ignore"
+rules.possibly-missing-attribute = "ignore"
+
 [tool.uv]
 required-version = ">=0.6.8"              # Sync with README
 default-groups = [ "test", "dev", "doc" ]
diff --git a/requirements.txt b/requirements.txt
@@ -970,6 +970,25 @@ tomlkit==0.13.3 \
     --hash=sha256:430cf247ee57df2b94ee3fbe588e71d362a941ebb545dec29b53961d61add2a1 \
     --hash=sha256:c89c649d79ee40629a9fda55f8ace8c6a1b42deb912b2a8fd8d942ddadb606b0
     # via usethis
+ty==0.0.1a25 \
+    --hash=sha256:0a90d897a7c1a5ae9b41a4c7b0a42262a06361476ad88d783dbedd7913edadbc \
+    --hash=sha256:168fc8aee396d617451acc44cd28baffa47359777342836060c27aa6f37e2445 \
+    --hash=sha256:1711dd587eccf04fd50c494dc39babe38f4cb345bc3901bf1d8149cac570e979 \
+    --hash=sha256:192edac94675a468bac7f6e04687a77a64698e4e1fe01f6a048bf9b6dde5b703 \
+    --hash=sha256:4a247061bd32bae3865a236d7f8b6c9916c80995db30ae1600999010f90623a9 \
+    --hash=sha256:5550b24b9dd0e0f8b4b2c1f0fcc608a55d0421dd67b6c364bc7bf25762334511 \
+    --hash=sha256:5f4c9b0cf7995e2e3de9bab4d066063dea92019f2f62673b7574e3612643dd35 \
+    --hash=sha256:93c7e7ab2859af0f866d34d27f4ae70dd4fb95b847387f082de1197f9f34e068 \
+    --hash=sha256:949523621f336e01bc7d687b7bd08fe838edadbdb6563c2c057ed1d264e820cf \
+    --hash=sha256:94f78f621458c05e59e890061021198197f29a7b51a33eda82bbb036e7ed73d7 \
+    --hash=sha256:a2fad3d8e92bb4d57a8872a6f56b1aef54539d36f23ebb01abe88ac4338efafb \
+    --hash=sha256:a9f3bbf523b49935bbd76e230408d858dce0d614f44f5807bbbd0954f64e0f01 \
+    --hash=sha256:d35b2c1f94a014a22875d2745aa0432761d2a9a8eb7212630d5caf547daeef6d \
+    --hash=sha256:d9656fca8062a2c6709c30d76d662c96d2e7dbfee8f70e55ec6b6afd67b5d447 \
+    --hash=sha256:dde2962d448ed87c48736e9a4bb13715a4cced705525e732b1c0dac1d4c66e3d \
+    --hash=sha256:eab6e33ebe202a71a50c3d5a5580e3bc1a85cda3ffcdc48cec3f1c693b7a873b \
+    --hash=sha256:f13ea9815f4a54a0a303ca7bf411b0650e3c2a24fc6c7889ffba2c94f5e97a6a \
+    --hash=sha256:f6b9a31da43424cdab483703a54a561b93aabba84630788505329fc5294a9c62
 typer==0.15.2 \
     --hash=sha256:46a499c6107d645a9c13f7ee46c5d5096cae6f5fc57dd11eccbbb9ae3e44ddfc \
     --hash=sha256:ab2fab47533a813c49fe1f16b1a370fd5819099c00b119e0633df65f22144ba5
diff --git a/src/usethis/_integrations/ci/bitbucket/steps.py b/src/usethis/_integrations/ci/bitbucket/steps.py
@@ -137,7 +137,7 @@ def _add_step_in_default_via_doc(
             if script_item.name not in defined_script_item_by_name:
                 script_item_name = script_item.name
                 try:
-                    script_item = _SCRIPT_ITEM_LOOKUP[script_item.name]
+                    resolved_script_item = _SCRIPT_ITEM_LOOKUP[script_item.name]
                 except KeyError:
                     msg = f"Unrecognized script item anchor: '{script_item.name}'."
                     raise NotImplementedError(msg) from None
@@ -156,14 +156,14 @@ def _add_step_in_default_via_doc(
                     script_item_name=script_item_name,
                     doc=doc,
                 )
-                existing_script_items.insert(insertion_index, script_item)
+                existing_script_items.insert(insertion_index, resolved_script_item)
                 existing_script_items = CommentedSeq(existing_script_items)
             else:
                 # Otherwise, if the anchor is already defined, we need to use the
                 # reference
-                script_item = defined_script_item_by_name[script_item.name]
+                resolved_script_item = defined_script_item_by_name[script_item.name]
 
-            step.script.root[idx] = script_item
+            step.script.root[idx] = resolved_script_item
 
     # If the step is unrecognized, it will go at the end.
     prerequisites: set[str] = set()
@@ -435,7 +435,8 @@ def _get_steps_in_pipeline(pipeline: Pipeline) -> list[Step]:
 
 
 @singledispatch
-def get_steps_in_pipeline_item(item) -> list[Step]: ...
+def get_steps_in_pipeline_item(item) -> list[Step]:
+    raise NotImplementedError
 
 
 @get_steps_in_pipeline_item.register(StepItem)
diff --git a/src/usethis/_integrations/ci/github/tags.py b/src/usethis/_integrations/ci/github/tags.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import requests
+from requests.exceptions import RequestException
 
 from usethis._integrations.ci.github.errors import (
     GitHubTagError,
@@ -29,7 +30,7 @@ def get_github_latest_tag(owner: str, repo: str) -> str:
     try:
         response = requests.get(api_url, timeout=1)
         response.raise_for_status()  # Raise an error for HTTP issues
-    except (requests.exceptions.HTTPError, requests.exceptions.ConnectionError) as err:
+    except RequestException as err:
         msg = f"Failed to fetch tags from GitHub API:\n{err}"
         raise GitHubTagError(msg) from None
 
diff --git a/src/usethis/_integrations/file/ini/io_.py b/src/usethis/_integrations/file/ini/io_.py
@@ -48,9 +48,9 @@ def __enter__(self) -> Self:
         except UnexpectedFileOpenError as err:
             raise UnexpectedINIOpenError(err) from None
 
-    def read_file(self) -> None:
+    def read_file(self) -> INIDocument:
         try:
-            super().read_file()
+            return super().read_file()
         except FileNotFoundError as err:
             raise ININotFoundError(err) from None
         except UnexpectedFileIOError as err:
diff --git a/src/usethis/_integrations/file/pyproject_toml/io_.py b/src/usethis/_integrations/file/pyproject_toml/io_.py
@@ -25,6 +25,7 @@
     from collections.abc import Sequence
     from typing import Any
 
+    from tomlkit import TOMLDocument
     from typing_extensions import Self
 
     from usethis._io import Key
@@ -43,9 +44,9 @@ def __enter__(self) -> Self:
         except UnexpectedTOMLOpenError as err:
             raise UnexpectedPyprojectTOMLOpenError(err) from None
 
-    def read_file(self) -> None:
+    def read_file(self) -> TOMLDocument:
         try:
-            super().read_file()
+            return super().read_file()
         except TOMLNotFoundError as err:
             raise PyprojectTOMLNotFoundError(err) from None
         except UnexpectedTOMLIOError as err:
diff --git a/src/usethis/_integrations/file/setup_cfg/io_.py b/src/usethis/_integrations/file/setup_cfg/io_.py
@@ -25,6 +25,7 @@
     from collections.abc import Sequence
     from typing import Any
 
+    from configupdater import ConfigUpdater as INIDocument
     from typing_extensions import Self
 
     from usethis._io import Key
@@ -43,9 +44,9 @@ def __enter__(self) -> Self:
         except UnexpectedINIOpenError as err:
             raise UnexpectedSetupCFGOpenError(err) from None
 
-    def read_file(self) -> None:
+    def read_file(self) -> INIDocument:
         try:
-            super().read_file()
+            return super().read_file()
         except ININotFoundError as err:
             raise SetupCFGNotFoundError(err) from None
         except UnexpectedINIIOError as err:
diff --git a/src/usethis/_integrations/file/toml/io_.py b/src/usethis/_integrations/file/toml/io_.py
@@ -53,9 +53,9 @@ def __enter__(self) -> Self:
         except UnexpectedFileOpenError as err:
             raise UnexpectedTOMLOpenError(err) from None
 
-    def read_file(self) -> None:
+    def read_file(self) -> TOMLDocument:
         try:
-            super().read_file()
+            return super().read_file()
         except FileNotFoundError as err:
             raise TOMLNotFoundError(err) from None
         except UnexpectedFileIOError as err:
diff --git a/src/usethis/_integrations/file/yaml/io_.py b/src/usethis/_integrations/file/yaml/io_.py
@@ -90,9 +90,9 @@ def __enter__(self) -> Self:
         except UnexpectedFileOpenError as err:
             raise UnexpectedYAMLOpenError(err) from None
 
-    def read_file(self) -> None:
+    def read_file(self) -> YAMLDocument:
         try:
-            super().read_file()
+            return super().read_file()
         except FileNotFoundError as err:
             raise YAMLNotFoundError(err) from None
         except UnexpectedFileIOError as err:
diff --git a/src/usethis/_integrations/pydantic/dump.py b/src/usethis/_integrations/pydantic/dump.py
@@ -172,14 +172,8 @@ def _(
     for key, value in model:
         default_value = model.__class__.model_fields[key].default
 
-        # The reference for the value (for recursion)
-        if isinstance(reference, dict | BaseModel):
-            try:
-                value_ref = dict(reference)[key]
-            except KeyError:
-                value_ref = None
-        else:
-            value_ref = None
+        # The value for the reference (for recursion)
+        value_ref = _get_value_ref(reference, key=key)
 
         # If the model has default value, we usually won't dump it.
         # There is an exception though: if we have a reference which we are trying
@@ -217,3 +211,18 @@ def _(
     ordered_d.update(d)
 
     return ordered_d
+
+
+def _get_value_ref(
+    reference: ModelRepresentation | None, *, key: str
+) -> ModelRepresentation | None:
+    # The reference for the value (for recursion)
+    if isinstance(reference, dict | BaseModel):
+        try:
+            value_ref = dict(reference)[key]  # ty: ignore[no-matching-overload]
+        except KeyError:
+            value_ref = None
+    else:
+        value_ref = None
+
+    return value_ref
diff --git a/src/usethis/_io.py b/src/usethis/_io.py
@@ -95,10 +95,9 @@ def get(self) -> DocumentT:
         self._validate_lock()
 
         if self._content is None:
-            self.read_file()
-            assert self._content is not None
-
-        return self._content
+            return self.read_file()
+        else:
+            return self._content
 
     def commit(self, document: DocumentT) -> None:
         """Store the given document in memory for deferred writing."""
@@ -119,8 +118,11 @@ def write_file(self) -> None:
 
         self.path.write_text(self._dump_content())
 
-    def read_file(self) -> None:
-        """Read the document from disk and store it in memory."""
+    def read_file(self) -> DocumentT:
+        """Read the document from disk and store it in memory.
+
+        Also returns the document.
+        """
         self._validate_lock()
 
         if self._content is not None:
@@ -130,11 +132,15 @@ def read_file(self) -> None:
             )
             raise UnexpectedFileIOError(msg)
         try:
-            self._content = self._parse_content(self.path.read_text())
+            document = self._parse_content(self.path.read_text())
         except FileNotFoundError:
             msg = f"'{self.name}' not found in the current directory at '{self.path}'."
             raise FileNotFoundError(msg) from None
 
+        self._content = document
+
+        return document
+
     @abstractmethod
     def _dump_content(self) -> str:
         """Return the content of the document as a string."""
diff --git a/src/usethis/_pipeweld/func.py b/src/usethis/_pipeweld/func.py
@@ -280,7 +280,7 @@ def _has_any_steps(
     if isinstance(component, str):
         return component in steps
     elif isinstance(component, Parallel | Series):
-        for subcomponent in component.root:
+        for subcomponent in component.root:  # ty: ignore[possibly-missing-attribute]
             if _has_any_steps(subcomponent, steps=steps):
                 return True
         return False
diff --git a/src/usethis/_tool/rule.py b/src/usethis/_tool/rule.py
@@ -89,11 +89,12 @@ def __or__(self, other: Self) -> Self:
             )
             raise NotImplementedError(msg)
 
-        return type(self)(
-            selected=self.selected + other.selected,
-            ignored=self.ignored + other.ignored,
-            unmanaged_selected=self.unmanaged_selected + other.unmanaged_selected,
-            unmanaged_ignored=self.unmanaged_ignored + other.unmanaged_ignored,
-            tests_unmanaged_ignored=self.tests_unmanaged_ignored
-            + other.tests_unmanaged_ignored,
+        new = self.model_copy()
+        new.selected = self.selected + other.selected
+        new.ignored = self.ignored + other.ignored
+        new.unmanaged_selected = self.unmanaged_selected + other.unmanaged_selected
+        new.unmanaged_ignored = self.unmanaged_ignored + other.unmanaged_ignored
+        new.tests_unmanaged_ignored = (
+            self.tests_unmanaged_ignored + other.tests_unmanaged_ignored
         )
+        return new
diff --git a/src/usethis/_ui/interface/version.py b/src/usethis/_ui/interface/version.py
@@ -9,9 +9,6 @@ def version() -> None:
     try:
         from usethis._version import __version__
     except ImportError:
-        __version__ = None
-
-    if __version__ is not None:
-        plain_print(__version__)
+        raise typer.Exit(code=1) from None
     else:
-        raise typer.Exit(code=1)
+        plain_print(__version__)
diff --git a/tests/usethis/_integrations/ci/bitbucket/test_bitbucket_schema.py b/tests/usethis/_integrations/ci/bitbucket/test_bitbucket_schema.py
@@ -3,6 +3,7 @@
 
 import pytest
 import requests
+from requests.exceptions import RequestException
 
 from usethis._integrations.ci.bitbucket.schema import Script, Step, Step2, StepBase
 from usethis._integrations.file.pyproject_toml.io_ import PyprojectTOMLManager
@@ -31,7 +32,7 @@ def test_matches_schema_store(self):
             online_schema_json = requests.get(
                 "https://api.bitbucket.org/schemas/pipelines-configuration", timeout=5
             ).text
-        except requests.exceptions.RequestException as err:
+        except RequestException as err:
             if os.getenv("CI"):
                 pytest.skip(
                     "Failed to fetch JSON schema (connection issues); skipping test"
diff --git a/tests/usethis/_integrations/ci/github/test_tags.py b/tests/usethis/_integrations/ci/github/test_tags.py
@@ -1,5 +1,5 @@
 import pytest
-import requests
+from requests.exceptions import HTTPError
 
 from usethis._integrations.ci.github.tags import (
     GitHubTagError,
@@ -29,7 +29,7 @@ def mock_get(*_, **__):
             class MockResponse:
                 def raise_for_status(self):
                     msg = "Failed to fetch tags."
-                    raise requests.exceptions.HTTPError(msg)
+                    raise HTTPError(msg)
 
             return MockResponse()
 
diff --git a/tests/usethis/_integrations/pre_commit/test_pre_commit_schema.py b/tests/usethis/_integrations/pre_commit/test_pre_commit_schema.py
diff --git a/uv.lock b/uv.lock
