Multi-platform checking

[MichaReiser]

Calling a platform-specific method with no python-platform set currently always emits a possibly-unbound warning (playground), even if the branch is guarded by an explicit sys.platform check.

The only way around the possibly-unbound warning seems to be to

1. Use a suppression comment
2. Only check for a specific platform, but that's not an option for everyone

Ideally, the sys.platform narrowing would be sufficient but that's probably non-trivial. A more short-term solution would be to explore ways to avoid the possibly-unbound false positive.

[carljm]

Effectively, fixing this properly means reviving the work we'd planned to do for multi-version-checking, but applying it only to multi-platform-checking for now. Because what we are wanting here is the ability to check for multiple platforms at once, and validate that you aren't using a platform-specific API without checking the platform first.

I think that might not actually be too hard? It just means introducing a ExistsOnPlatform type and having sys.platform checks do narrowing and visibility constraints as intersections with that type.

But there might also be a shorter-term fix that silences the false positives without actually giving us the ability to error if you use a platform-specific API without checking the platform.

[AlexWaygood]

the easiest fix here might be to just default to platform = "linux", which I believe is what all other type checkers do. Then we'd always understand sys.platform-guarded branches as either definitely-reachable or definitely-unreachable, the same as we do for sys.version_info guarded branches.

I know this is not the behaviour we'd like in the long term, but I think making this change would be pretty easy; it might be the best course of action for the alpha.

[MichaReiser]

This sounds like a reasonable solution for the alpha. We could consider defaulting to the current platform which gives better editor experience but might not necessarily be the right choice for the cli

[AlexWaygood]

Oh, sorry, I think that's what most other type checkers do: default to the current platform, not default to "linux". So I don't think that behaviour would come as a surprise to users

[MichaReiser]

Slightly different but related (but might be worth its own issue):

Something that astral-sh/ruff#17183 showed is that some projects have platform specific files. E.g. rich has a file specific to windows. I'm not sure how best to support this use case because it would require overriding platform at a per file level

Pyright supports this by allowing multiple execution environments https://microsoft.github.io/pyright/#/configuration?id=sample-config-file

[carljm]

I agree that in the short term we should just always have a single configured (or defaulted) platform and not attempt multi-platform checking. Ignore the rest of this comment for short-term :)

If/when we do aim for multi-platform (and possibly multi-version?) checking, after chatting with @sharkdp today I have an updated understanding of how that could work. I don't think we need the PlatformIs style types to intersect with, now that we have visibility constraints. Instead we can record a visibility constraint (as we already do) for a test like sys.platform == "win32", and when evaluating visibility constraints we can pass in a context which contains a potentially-updated value for sys.platform, which would come from narrowing constraints at the usage site. So for example, given

if sys.platform == "win32":
    def win_only_function(): ...

# later, maybe even in a different file...

if sys.platform == "win32":
    win_only_function()

The definition of win_only_function would come with a visibility constraint of sys.platform == "win32". This already happens today, we just aren't able to evaluate that constraint to a known truthiness if we don't have a single platform configured. But what we can do in future is record a narrowing on the second if sys.platform == "win32" check so that within that block we understand that sys.platform is now "win32". And we can include that information in the context for evaluating the visibility constraints on the definition of win_only_function(), so that we are able to evaluate it as definitely-truthy (but only within that context.)