Type checking with ty.

[filiplajszczak]

While working on the publication channels plugin interface (#2701), I leaned on Protocols and type annotations to define the plugin API. It got me thinking about whether the project could benefit from a type checker — especially now that there's a fast one available.

Type checking has come up before (#665). The response at the time was that type annotations aren't an inherent good — they can help as documentation but can also impede readability, and a broader project-wide conversation was needed.
ty might make that conversation worth revisiting.

Since the project already uses ruff and tox-uv, the Astral toolchain is familiar territory. The speed means ty can run in pre-commit without anyone noticing it's there.

I ran it on briefcase as an experiment:

• 597 diagnostics in 0.16 seconds on the full src/briefcase/ tree
• Bulk of issues (448) are unresolved-attribute — mostly from BaseConfig being loosely typed
• 56 invalid-argument-type, 24 invalid-return-type — potentially real catches
• 5 unresolved-import — conditional imports (tomli, dmgbuild)

The 597 number looks scary but the story is simple: one typing gap — BaseConfig/AppConfig attributes being set dynamically — accounts for ~75% of the noise. The top offenders are platform modules (macOS/__init__.py alone has 164). Fixing the type for AppConfig would eliminate most of these in one go. The remaining ~150 are a mix of real catches (e.g. a create() -> bool with a code path that implicitly returns None) and places where ty is stricter than the runtime.

The codebase is already in decent shape for this: ~60% of files have from __future__ import annotations. The integrations layer was typed in 2022–2023, and newer plugin interfaces (channels, debuggers) use Protocols and proper annotations.

Proposal: gradual introduction

This doesn't need to be all-or-nothing. ty supports per-rule severity (--error, --warn, --ignore), file exclusions, and configuration via pyproject.toml — so it can be introduced gradually:

1. Start informational add ty to CI as a non-blocking step, so everyone can see what it catches without it getting in the way.
2. Pick a clean module to gate first something like channels/ or integrations/base.py that's already well-typed, and make ty enforced just there.
3. Track progress with a checklist issue a single issue with a per-module checklist showing which modules are fully checked, which are in progress, and what known blockers remain (e.g. BaseConfig attribute access patterns). Gives contributors a clear picture of what's expected where.
4. Expand module by module as modules get cleaned up (whether through dedicated typing PRs or as a side effect of other work), add them to the enforced set.

Is there appetite for exploring this? Happy to propose more detailed roadmap.

[freakboy3742]

I think the key difference between now and #665 is the existence of ty - being able to run over all of Briefcase in 0.16s is... a lot faster than mypy :-)

I have some reservations based on the maturity of ty - I'm a fan of boring tools, and tools that are still in the early phases of development tend to be a little too "spicy". Any bug they have may be fixed quickly - but while it's present, we need to deal with it, and our contributors need to deal with it, and so on. The current state of their version policy suggests that even Astral thinks ty is an unstable platform at this point.

I also have some reservations based on the fact that the thing typing finds abhorrent - dynamic attributes - is something that is extremely useful. As you've noted, the platform module is a particular edge case here, because each backend has properties and attributes that are extremely platform specific. We don't really want to annotate all the Linux-specific properties onto a base class so that macOS/Windows users have to navigate around them - if only because there will almost certainly be cases where the types are inconsistent between platforms. My concern here is typing become a "technically correct" straightjacket where our lives as developers becomes unwieldy just to keep a type checker happy.

However - if there is a path to progressively introducing type checks, and the tool won't be cumbersome until we choose to enforce it in the places where we can, then I think it's at least worth the experiment.

[filiplajszczak]

Thanks for the honest response. Addressing the two concerns directly:

ty maturity

Agreed — the version policy is honest about where ty is right now.

The mitigation is straightforward: run ty as an experimental non-blocking CI step. In tox that's ignore_outcome = true, the job runs, the output is visible, but it never gates a merge. Contributors see what ty catches without ever being blocked by a ty bug.

Pin to a specific version and upgrade deliberately. That way, if a ty release introduces a regression, it doesn't touch the project until someone reviews and bumps it. By the time we'd consider making anything enforced, ty will have had months of real-world use on our codebase and we'll know exactly how stable it is in practice.

Before we start using it as a real gate I would expect it to mature significantly like it was with ruff and uv.

Dynamic attributes

This is the more interesting concern (bit similar to the one raised in Django about dynamic attributes on models).
The dynamic attribute pattern is well established in Briefcase and the type checker should adapt to it, not the other way around.

My proposed approaches would be:

1. Exclude platform modules entirely at first. Don't run ty enforcement on platform backends at all. Gate only the clean, Protocol-based modules first (channels/, integrations/). Platform modules stay warn-only or excluded until there's a pattern that works without forcing false consistency.

2. Declare dynamic access explicitly. Two options here:

Option A: __getattr__ stub on the base class. Tell the type checker that dynamic attribute access is intentional:

class BaseConfig:
    def __getattr__(self, name: str) -> Any: ...
    def __setattr__(self, name: str, value: Any) -> None: ...

Simple, one-line change, documents the intent in the code itself rather than in suppression comments. Each platform subclass stays free to set whatever attributes it needs without declaring them on the base.

Option B: a Protocol expressing the same intent. Same idea, but without modifying BaseConfig itself:

from typing import TYPE_CHECKING, Any, Protocol

if TYPE_CHECKING:
    class DynamicConfig(Protocol):
        def __getattr__(self, name: str) -> Any: ...
        def __setattr__(self, name: str, value: Any) -> None: ...

Functions that consume a config can type their parameter as DynamicConfig. The checker sees "dynamic access is expected here" without touching the actual class hierarchy.

Option A is the simpler change (one-line addition to BaseConfig). Option B keeps the intent separate from the runtime class, though I'm not sure the extra indirection is worth it — it might just be adding a layer of abstraction for something that's clearer stated directly on the class.

Experiment

Tried Option A locally — diagnostics dropped to 488. The remaining unresolved-attribute bulk is self.tools/self.console in platform mixins that access BaseCommand attributes without declaring the dependency. The ~140 non-attribute diagnostics (invalid-argument-type, invalid-return-type, etc.) are worth reviewing for real catches.

Proposed first steps

A tracking issue:

• current intent
• progress so far
• the pending next step.

A single PR that:

• Adds a [testenv:ty] to tox with ignore_outcome = true
• Adds a minimal [tool.ty] section to pyproject.toml with everything set to warn
• Pins ty to the current release

[freakboy3742]

The mitigation is straightforward: run ty as an experimental non-blocking CI step. In tox that's ignore_outcome = true, the job runs, the output is visible, but it never gates a merge. Contributors see what ty catches without ever being blocked by a ty bug.

I guess adding a configuration, and adding a tox target so we can easily "opt in" to a hard type check is probably worth it.

I'm less convinced about the value of running it in CI if any error state is ignored - I don't look at the output of a CI job unless it fails, but having a single typing CI check fail will be confusing to contributors, as we'll be merging "non-green" jobs. I guess it doesn't hurt to have the check in place, though.

Pin to a specific version and upgrade deliberately. That way, if a ty release introduces a regression, it doesn't touch the project until someone reviews and bumps it. By the time we'd consider making anything enforced, ty will have had months of real-world use on our codebase and we'll know exactly how stable it is in practice.

Also fair. Alternatively, we could put it into our usual Dependabot upgrade cycle, but actually use the Dependabot update to check if there's been any breaking changes, and be much more aggressive about skipping versions.

Dynamic attributes

Annotating __getattr__/__setattr__ definitely makes the errors goes away, but it feels like adhering to the letter of the law, not the spirit of the law. In the places where we're using dynamic attributes, it's less to do with being completely dynamic, and more about "local adaptation" - that there really is a LinuxSystemAppConfig, which is a subprotocol of AppConfig, but we only know we have (or require that we have) a LinuxSystemAppConfig when we're in that backend.

However, that means having a base class that knows it has an AppConfig, calling a class that requires a LinuxSystemAppConfig. I guess there might be some sort of "type-checking casting decorator" approach that we can build and apply?

Proposed first steps

A tracking issue:

• current intent
• progress so far
• the pending next step.

+1 to this. Signalling intent (or at least interest) is definitely worthwhile.

A single PR that:

• Adds a [testenv:ty] to tox with ignore_outcome = true
• Adds a minimal [tool.ty] section to pyproject.toml with everything set to warn
• Pins ty to the current release

+1. I think this is definitely at the "show us the code stage".