Tracking issue for overloads

[Michael0x2a]

This is an issue summarizing all remaining TODOs for the overloads overhaul.

Done

• Add support for detecting partially-overlapping arities.

  For example, disallow f(A, A) -> int and f(*A) -> str. This will likely require modifications to is_callable_compatible (or require implementing a new, similar method).

• Improve union math semantics. Related issues:

  • Support basic union math for overloaded functions
  • One more bug with union math logic
  • Wrong overload resolution with Any union item in argument (?)

• Update docs to clarify what the new overload semantics are. Related issues:

  • Docs for function overloading are made more complex by using getitem as example

• Improving how overload implementations are checked. Related issues:

  • Errors when using overloaded functions and type variables

• Add full support for partially-overlapping types.

  For example, disallow f(Union[A, B]) -> int and f(Union[B, C]) -> str. We currently support detect partially-overlapping unions and tuples on just the top-level.

  Related issues:

  • Allow overloading based on TypedDict structure
  • Overloaded function signatures 1 and 2 overlap with incompatible return types
  • Allow overloads to be distinguished by contained type of a generic
  • spurious "Need type annotation" error with overloads

  Sub-todos:

  • If all arguments in the first overload are partially overlapping with the second, report an error (even if the first return type is narrower).

    We should also probably have a custom error message, since this is technically safe when the first return type is narrower. This should also probably wait until we have more robust support for partially-overlapping types.

    Edit: We decided it wasn't worth complicating the code to handle this TODO.

In-progress

• Add union math for operators. See Mypy fails on Union[float, int] + Union[float, int] #2128.

• Error messages need a usability overhaul. Related open issues:

  • Give better error messages when calling overloaded function with invalid types
  • Ordering matters for @overload (error message could be improved)
  • More specific overlapping overload errors
  • Handling de-facto positional-only arguments with overloads

Remaining todos:

• Overload subtypes could be enhanced to use the new union math algorithms in some way. Related open issues:

  • Type inference problems with unions, overloads and map
  • Overloaded function as a subtype of function with union types args/return

• Improve test coverage:

  Sub-TODOs:

  • Add test cases for situations where the overload definitions have a type error (that may or may not have been type-ignored).

• Update PEP 484/submit a new mini-PEP or something.

Remaining todos; deprioritized

• Re-think how overloads, operator overloading, and overload subtyping interacts. Related open issues:

  • Make operator overloading overlapping checks more lenient
  • Ordering matters for @overload (one of the error messages seems like a bug)
  • Overloading function issues (incompatible with supertype).
  • Signatures of overloaded operators are incompatible with super type

  Sub-TODOs:

  • Update code for operator methods to take advantages of the overload refactorings.

    For example, I think operator methods currently might be ignoring generics when checking for overlaps (though it's unclear if this is actually an issue in real-life code). This mostly boils down to using is_callable_compatible in clever ways within is_unsafe_overlapping_operator_signatures and adding more tests.

• Enhance binder to understand how overloads and NoReturn interact. Related issues:

  • Narrow types using overload information

• General refactoring and cleanup:

  • Adjust the semantic analysis phase so we use the same binding for a typevar across all overload alternatives.

    This would let us remove merge_typevars_in_callables_by_name. Implementing this would probably require refactoring TypeVarScope?

• Improving how overloads and decorators interact. Related issues:

  • Running mypy with --disallow-untyped-decorators reports an error for overloaded decorators

Issues that need triaging

• Optional strict checking of overloads
• Refactor operator method access and protocol checks to use checkmember.py

[ilevkivskyi]

Update docs to clarify what the new overload semantics are.

Just for myself, a simple summary of current logic:

1. Definition site:

• First signature args never overlap with second signature args (either type or arity) -> Always OK
• First signature args are broader than second signature args -> Error
• First signature args are narrower than second signature args -> OK if the return is also narrower, otherwise Error
• There is a partial overlap between first and second signature args -> Error, but three exceptions where overlap is small/hard to express, so we still allow it: multiple inheritance, empty collections, descriptors.

2. Call site:

• We pick the first possible match (which would be also normally the narrowest due to above rules)
• Also if there are two matches because of an allowed partial overlap, first signature wins
• If there are two matches because of Any we return Any
• We use simple union math if it allows match/gives more precise match.

@Michael0x2a did I miss something?

[Michael0x2a]

@ilevkivskyi -- No, I think that looks good. A few tweaks:

• I would rephrase the third and fourth bullet points to read like this:

  • First signature args are narrower than or partially overlapping with second signature args -> OK if the return is also narrower, otherwise error.

    There are three exceptions where the overlap is small/hard to express, so we still allow it: multiple inheritance, empty collections, and descriptors.

  • First signature args are all partially overlapping with second args -> Error, even if the return is narrower. This would be safe if the return is narrower, but it's sloppy and probably worth warning about. (This currently isn't implemented.)

  Basically, we also need to check the return type when some of the args are narrower and some are partially overlapping.

  The last bullet point is strictly speaking unnecessary, but I believe we decided it would be a good idea because it could catch some sloppy code. (I should add this to my todo list, actually.)

• Regarding definition sites in general: we pretend that strict optional is always enabled at that stage. Idk if that's a super important detail though, especially since strict-optional is the default now.

[ilevkivskyi]

The last bullet point is strictly speaking unnecessary, but I believe we decided it would be a good idea because it could catch some sloppy code. (I should add this to my todo list, actually.)

Yes, I remember we discussed this, we can do this is mypy, but this doesn't need to be in spec/PEP 484 just to make the mental model more "compact".

[ilevkivskyi]

@Michael0x2a what is your timeline for working on this? 0.620 release will be around June 29 (right after Python 3.7) and I will be the release manager. I will be glad to see better support for overloads in (since this is a big and long awaited feature). Do you think we can make it? If needed, I can review the PRs faster/devote more time to this.

[Michael0x2a]

@ilevkivskyi: In short, I think I can have the overload TODOs and the bulk of the issues ready by then; I'm a bit less certain about operator methods.

Specifically:

• I'm currently working on the first two TODOs. Progress has been a bit slow due to unrelated reasons, but I'm planning on having the first set of PRs for those ready sometime this upcoming week.

• The third issue is a bit iffier, mostly because I haven't given much thought to operator methods. I think it'll be relatively trivial to add support for generics in a way that preserves the existing semantics; refactoring and removing unnecessary checks will probably require more thought. That said, I don't think this is as big of a todo, so I'm planning on deprioritizing this until overloads are solid.

• I also briefly took a look at the overload-related issues on the tracker: I think we can close roughly half of the issues atm; resolving the other half will probably take up the rest of the month.

  I plan on stepping through the issues more carefully and closing the resolved ones once 0.610 is released. (I know the blog announcement likes to list issues that were closed and I don't want to muddy matters by closing a bunch of issues unrelated to that release.)

• The other TODOs look either trivial or non-essential.

[ilevkivskyi]

I think I can have the overload TODOs and the bulk of the issues ready by then;

OK, this is perfect.

The third issue is a bit iffier, mostly because I haven't given much thought to operator methods.

There is also a related issue that dunder code is quite old, most of it is not using checkmember functions, instead duplicating it in some special ways. I will open a dedicated issue for this now.

I think we can close roughly half of the issues atm;

This is great!

[ilevkivskyi]

If all arguments in the first overload are partially overlapping with the second, report an error (even if the first return type is narrower).

On a second thought, I think we can just skip this. Although it would flag some weird definitions, this is not technically type unsafe, and unlike the "... will be never matched" error (which is also technically not type unsafe, but is obvious) may only confuse users.

[ilevkivskyi]

I just read again through the list and propose to focus on three things before the next release (apart from finishing the existing PRs):

• Add better support for partially-overlapping types. We don't need to go really far here, just have a bit more complete implementation (btw there is a function in meet.py called is_overlapping_types you can maybe re-use some code from it). Also I would completely remove the plan to error even if returns are subtypes. IIRC I proposed this, but now I see that people aren't happy when mypy is prohibiting weird but safe code ("function doesn't return a value").
• Improve error messages (mostly fix the "no overload variant matches", plus maybe few smaller improvements).
• Improve interaction between dunders and overloads. I see you listed it in deprioritized, but I think there may be few low hanging fruits here. For example it is straight prohibited to override an overloaded dunder with another overload (even with the same type!) In my experience dunders are actually often overloaded and people can be very surprised.