This was discussed on the typing-sig mailing list and in
python/peps#1218, has met the approval of the steering council, and
was incorporated into PEP 484.
This pull request is a follow-up to https://github.com/python/mypy/issues/7214.
In short, within that mypy issue, we found it would be helpful to
determine between contextmanagers that can "swallow" exceptions vs ones
that can't. This helps prevent some false positive when using flags that
analyze control flow such as `--warn-unreachable`. To do this,
Jelle proposed assuming that only contextmanagers where the `__exit__`
returns `bool` are assumed to swallow exceptions.
This unfortunately required the following typeshed changes:
1. The typing.IO, threading.Lock, and concurrent.futures.Executor
were all modified so `__exit__` returns `Optional[None]` instead
of None -- along with all of their subclasses.
I believe these three types are meant to be subclassed, so I felt
picking the more general type was correct.
2. There were also a few concrete types (e.g. see socketserver,
subprocess, ftplib...) that I modified to return `None` -- I checked
the source code, and these all seem to return None (and don't appear
to be meant to be subclassable).
3. contextlib.suppress was changed to return bool. I also double-checked
the unittest modules and modified a subset of those contextmanagers,
leaving ones like `_AssertRaisesContext` alone.
We get quite a few bug reports where after a maintainer writes
"Pull Requests Welcome" we get a PR by the submitter. Maybe this
badge will help a bit to encourage people directly submit PRs,
reducing maintainer workload.
This pull request modifies the contribution guidelines to clarify
when and where 'Any' should be used.
In particular, it clarifies that 'Any' is meant mainly to be used as
a "fallback" -- if it's not possible to express a certain type, if we're not
sure what the correct type in some case is, to avoid Union returns, etc...
It also explicitly notes that 'object' should be used over 'Any' when we
want to indicate that some function can accept literally anything.
Typing stubs this way probably won't impact most people, but does make
life a bit easier for people (like me) who want to restrict/forbid the
use of Any as much as possible.
Fixes#2124.
As mentioned in the issue, the current guidelines lead to extremely long lines of many hundreds of characters, which make code hard to read and review. I think there should be some limit to line length, but it's OK for stubs to have somewhat longer lines than normal code.
For reference, there are currently 115 lines in typeshed over 200 characters; 523 over 120 characters; and 2980 over 79 characters.
We picked 130 because that's the longest line GitHub displays on a 13" laptop in a unified diff without folding. There are currently 382 lines in typeshed that are over 130 characters.
We (I) introduced the BLOCKED label ~2 years ago, but it never got much usage, and I remember it startled some developers (Ivan may recall...). A better convention seems to put [WIP] in the subject, so let's standardize on that and get rid of the BLOCKED label.
I already removed the BLOCKED label and edited the subject of the one issue under it.
We also don't make good use of the other labels, but they seem more useful and less controversial.
I disagree with the recommendation that users create incomplete stubs, because such stubs lead to false positive type checker errors (see for example #525). I would like to instead set a norm that all stubs should contain all public objects in the library they cover.
- Removes references to 'runtests.sh', as it has been removed
- Adds links from the contributing file to the readme - testing section
- Updates flake8 stats
- Updates documentation related to previously required comment headers.
- Removes all comment headers from stubs
- Occasionally included a header for stubs that were noted to be incomplete or contained todo's.
I've seen some stubs like
```
class X:
def __init__(self, x: str) -> None:
self.x = x
self.y = 0
```
I think this should be written instead as
```
class X:
x: str
y: int
def __init__(self, x: str) -> None: ...
```
1. Mentioned review requirement for core contributors.
2. Made stub coding style on par with requirements specified on
the Mypy wiki (we can merge them now).
