This is a follow-up on #4232. memoryview, hashlib, and hmac are updated
to use ReadableBuffer type instead of their own home-spun unions of
bytes, bytearray and whatever else each use case used. mmap is being
handled in #4244, and I'll leave BinaryIO for another day (or possibly
another person) because it's going to require some messy code
duplication because the relevant methods are defined in IO[AnyStr].
There's one corner case I'm not quite sure how best to handle: the
documentation for hmac.digest claim that the parmaeters have the same
meanings as in hmac.new, but in CPython the latter has an explicit check
that `key` is bytes or bytearray while the former works with a
memory-view. For now I've matched the documentation.
Also, the documentation for HMAC.update says that `msg` can be any type
supported by hashlib from Python 3.4; but I can't see anything in the
Python 2.7 implementation that would prevent it also taking bytes-like
objects, so I've not tried to treat Python 2 any different to Python 3.
* Update mmap stubs for newer Python versions
Based on the Python stdlib documentation:
- Since Python 3.5, mmap.{find,rfind,write} all accept any bytes-like.
I've used the _typeshed.ReadableBuffer alias defined in #4232.
- Since Python 3.6, mmap.write returns the number of bytes written.
- Since Python 3.3, mmap.read allows None as the parameter; while in
Python 2 the argument cannot be omitted.
* Further clean up mmap.pyi
Use the fact that Python 3.0-3.4 are no longer supported to clean up the
version-dependent logic. Functions that always have different signatures
in Python 2/3 are moved from the base _mmap[bytes] to the mmap subclass.
Since typing doesn't yet have a way to express buffer protocol objects
(python/typing#593), various interfaces have ended up with a mish-mash
of options: some list just bytes (or just bytearray, when writable),
some include mmap, some include memoryview, I think none of them include
array.array even though it's explicitly mentioned as bytes-like, etc. I
ran into problems because RawIOBase.readinto didn't allow for
memoryview.
To allow for some uniformity until the fundamental issue is resolved,
I've introduced _typeshed.ReadableBuffer and _typeshed.WriteableBuffer,
and applied them in stdlib/3/io.pyi as an example. If these get rolled
out in more places, it will mean that we have only one place where they
have to get tweaked in future, or swapped out for a public protocol.
This unfortunately does have the potential to break code that inherits
from RawIOBase/BufferedIOBase and overrides these methods, because the
base method is now more general and so the override now needs to accept
these types as well (which is why I've also updated gzip and lzma).
However, it should be a reasonably easy fix, and will make the
downstream annotations more correct.
A few comments between imports were removed or moved to the top of the
import block, due to behavioral differences between black and isort. See
psf/black#251 for details.
In two instances @overloads at the top of the file needed to be moved
due to psf/black#1490.
The CPython _lsprof module implementation uses the keyword arguments
'timer' and 'timeunit' instead of 'custom_timer' and 'time_unit' for
__init__. In profiler_init, the keyword argument parsing looks like the
following:
static char *kwlist[] = {"timer", "timeunit",
"subcalls", "builtins", 0};
This is the case ever since _lsprof was added in version 2.5.
Re-export the types from wsgiref.types for now to avoid breaking
existing code. wsgiref.types should be removed eventually.
Also, reduce the boilerplate description in _typeshed/wsgi.pyi as it
mirrors the description in _typeshed/__init__.pyi.
In Python 3.6, the SSLContext.options flags were converted from int to
EnumFlag values.
In addition, add the missing OP_ENABLE_MIDDLEBOX_COMPAT constant
introduced in version 3.6.
In addition, add the missing OP_NO_RENEGOTIATION constant introduced in
version 3.7.
The SocketCAN BCM option flag constants were added in version 3.9,
and only backported to version 3.8, despite the documentation's claims
of supporting all BCM-related constants starting from version 3.4.
Note: The CAN_FD_FRAME flag option was only introduced in the 4.8.x
kernel series, while the rest of the constants were available since the
Broadcast Manager was mainlined in the kernel as part of the SocketCAN
patches.
* make io classes inherit from typing IO classes
This makes these classes usable if type annotations are given as "IO"
or "TextIO". In the future, we'll then be able to move open() to
return a concrete class instead (#3951).
* open: introduce concrete return types
Fixes#3951.
We use the values of the "mode" and "buffering" arguments to figure out
the concrete type open() will return at runtime. (Compare the CPython
code in https://github.com/python/cpython/blob/master/Modules/_io/_iomodule.c#L231.)
* Allow unicode objects throughout urlparse.py
Functions such as `urlparse()`, if given a unicode object,
will happily return a ParseResult of unicode components.
Relatedly, functions like `unquote()` will accept any of
bytes/str/unicode and return an object of the same type
or a composite containing that type.
* Allow unicode in several places in Thread
`name` and `kwargs` to Thread.__init__ function perfectly
well with unicode, not just str.
Note: the .name attribute will always be str even
if the constructor is passed something else, since
__init__ calls:
self.__name = str(name or _newname())
* Use typing.AnyStr properly
...rather than defining a new TypeVar unncessarily.
* Use typing.Text properly
Text is behaviorally equivalent to Union[str, unicode]
for Python 2 argument types.
* Remove outdated import & definition
* [check file consistent] copy changes to _dummy_threading.pyi
- While this appears to be private, it's also documented as available
to set here: https://docs.python.org/3/howto/logging.html#optimization
- Did *not* update `logging.logThreads` et al to match the
documentation as it may be more appropriate to update the
documentation to set to `False` rather than to `0` based on how these
are used
Type further narrowed based on known type of a parameter to
`os.normcase`
