Skip to content

Commit c408b14

Browse files
authored
Merge branch 'master' into refactor-test-discovery
2 parents 813138b + 47e53f8 commit c408b14

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

87 files changed

+4739
-1261
lines changed

.travis.yml

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,6 @@ python:
99
- "3.5.1"
1010
- "3.6"
1111
- "3.7-dev"
12-
# Pypy build is disabled because it doubles the travis build time, and it rarely fails
13-
# unless one one of the other builds fails.
14-
# - "pypy3"
1512

1613
install:
1714
- pip install -U pip setuptools wheel
@@ -20,5 +17,6 @@ install:
2017
- pip install .
2118

2219
script:
23-
- python runtests.py -j12 -x lint
20+
- python runtests.py -j12 -x lint -x package
2421
- if [[ $TRAVIS_PYTHON_VERSION == '3.6' ]]; then flake8; fi
22+
- if [[ $TRAVIS_PYTHON_VERSION == '3.5.1' ]]; then python runtests.py package; fi

README.md

Lines changed: 15 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -25,23 +25,15 @@ What is mypy?
2525
-------------
2626

2727
Mypy is an optional static type checker for Python. You can add type
28-
hints to your Python programs using the standard for type
29-
annotations introduced in Python 3.5 ([PEP 484](https://www.python.org/dev/peps/pep-0484/)), and use mypy to
30-
type check them statically. Find bugs in your programs without even
31-
running them!
32-
33-
The type annotation standard has also been backported to earlier
34-
Python 3.x versions. Mypy supports Python 3.3 and later.
35-
XML based reports do not work on Python 3.3 and 3.4 on Windows.
36-
37-
For Python 2.7, you can add annotations as comments (this is also
38-
specified in [PEP 484](https://www.python.org/dev/peps/pep-0484/)).
28+
hints ([PEP 484](https://www.python.org/dev/peps/pep-0484/)) to your
29+
Python programs, and use mypy to type check them statically.
30+
Find bugs in your programs without even running them!
3931

4032
You can mix dynamic and static typing in your programs. You can always
4133
fall back to dynamic typing when static typing is not convenient, such
4234
as for legacy code.
4335

44-
Here is a small example to whet your appetite:
36+
Here is a small example to whet your appetite (Python 3):
4537

4638
```python
4739
from typing import Iterator
@@ -52,11 +44,20 @@ def fib(n: int) -> Iterator[int]:
5244
yield a
5345
a, b = b, a + b
5446
```
47+
See [the documentation](http://mypy.readthedocs.io/en/stable/introduction.html) for more examples.
48+
49+
For Python 2.7, the standard annotations are written as comments:
50+
```python
51+
def is_palindrome(s):
52+
# type: (str) -> bool
53+
return s == s[::-1]
54+
```
55+
56+
See [the documentation for Python 2 support](http://mypy.readthedocs.io/en/latest/python2.html).
5557

5658
Mypy is in development; some features are missing and there are bugs.
5759
See 'Development status' below.
5860

59-
6061
Requirements
6162
------------
6263

@@ -105,7 +106,7 @@ Mypy can be integrated into popular IDEs:
105106

106107
* Vim: [vim-mypy](https://github.com/Integralist/vim-mypy)
107108
* Emacs: using [Flycheck](https://github.com/flycheck/) and [Flycheck-mypy](https://github.com/lbolla/emacs-flycheck-mypy/issues)
108-
* Sublime Text: [SublimeLinter-contrib-mypy]
109+
* Sublime Text: [SublimeLinter-contrib-mypy](https://github.com/fredcallaway/SublimeLinter-contrib-mypy)
109110
* Atom: [linter-mypy](https://atom.io/packages/linter-mypy)
110111
* PyCharm: PyCharm integrates [its own implementation of PEP 484](https://www.jetbrains.com/help/pycharm/2017.1/type-hinting-in-pycharm.html).
111112

@@ -157,9 +158,6 @@ In Windows, the script is generally installed in
157158

158159
C:\>\Python34\python \Python34\Scripts\mypy PROGRAM
159160

160-
If you are on Windows using Python 3.3 or 3.4, and would like to use XML reports
161-
download LXML from [PyPi](https://pypi.python.org/pypi/lxml).
162-
163161
### Working with `virtualenv`
164162

165163
If you are using [`virtualenv`](https://virtualenv.pypa.io/en/stable/),

appveyor.yml

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,17 @@ install:
1212
- "git config core.symlinks true"
1313
- "git reset --hard"
1414
- "%PYTHON%\\python.exe -m pip install -r test-requirements.txt"
15+
- "C:\\Python27\\python.exe -m pip install typing"
1516
- "git submodule update --init typeshed"
1617
- "cd typeshed && git config core.symlinks true && git reset --hard && cd .."
1718
- "%PYTHON%\\python.exe -m pip install ."
1819

1920
build: off
2021

2122
test_script:
22-
# Ignore lint (it's run in Travis)
23-
- "%PYTHON%\\python.exe runtests.py -x lint"
23+
# Ignore lint and mypy self check (both run in Travis)
24+
- "%PYTHON%\\python.exe runtests.py -x lint -x package -x pytest"
25+
- "%PYTHON%\\python.exe runtests.py pytest -p -k -p \"not (PythonEvaluationSuite and python2)\""
2426

2527
skip_commits:
2628
files:

docs/source/cheat_sheet_py3.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -239,7 +239,7 @@ Other stuff
239239
else:
240240
return sys.stdout
241241
242-
# forward references are useful if you want to referemce a class before it is designed
242+
# forward references are useful if you want to reference a class before it is designed
243243
244244
def f(foo: A) -> int: # this will fail
245245
...
@@ -304,4 +304,4 @@ Mypy brings limited support for PEP 526 annotations.
304304
def __init__(self) -> None:
305305
self.items: List[str] = []
306306
307-
Please see :ref:`python-36` for more on mypy's compatability with Python 3.6's new features.
307+
Please see :ref:`python-36` for more on mypy's compatibility with Python 3.6's new features.

docs/source/class_basics.rst

Lines changed: 74 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -158,30 +158,32 @@ Protocols and structural subtyping
158158

159159
.. note::
160160

161-
The support for structural subtyping is still experimental. Some features
162-
might be not yet implemented, mypy could pass unsafe code or reject
163-
working code.
164-
165-
There are two main type systems with respect to subtyping: nominal subtyping
166-
and structural subtyping. The *nominal* subtyping is based on class hierarchy,
167-
so that if class ``D`` inherits from class ``C``, then it is a subtype
168-
of ``C``. This type system is primarily used in mypy since it allows
169-
to produce clear and concise error messages, and since Python provides native
170-
``isinstance()`` checks based on class hierarchy. The *structural* subtyping
171-
however has its own advantages. In this system class ``D`` is a subtype
172-
of class ``C`` if the former has all attributes of the latter with
173-
compatible types.
174-
175-
This type system is a static equivalent of duck typing, well known by Python
176-
programmers. Mypy provides an opt-in support for structural subtyping via
177-
protocol classes described in this section.
178-
See `PEP 544 <https://www.python.org/dev/peps/pep-0544/>`_ for
179-
specification of protocols and structural subtyping in Python.
180-
181-
User defined protocols
182-
**********************
183-
184-
To define a protocol class, one must inherit the special
161+
Structural subtyping is experimental. Some things may not
162+
work as expected. Mypy may pass unsafe code or it can reject
163+
valid code.
164+
165+
Mypy supports two ways of deciding whether two classes are compatible
166+
as types: nominal subtyping and structural subtyping. *Nominal*
167+
subtyping is strictly based on the class hierarchy. If class ``D``
168+
inherits class ``C``, it's also a subtype of ``C``. This form of
169+
subtyping is used by default in mypy, since it's easy to understand
170+
and produces clear and concise error messages, and since it matches
171+
how the native ``isinstance()`` check works -- based on class
172+
hierarchy. *Structural* subtyping can also be useful. Class ``D`` is
173+
a structural subtype of class ``C`` if the former has all attributes
174+
and methods of the latter, and with compatible types.
175+
176+
Structural subtyping can be seen as a static equivalent of duck
177+
typing, which is well known to Python programmers. Mypy provides an
178+
opt-in support for structural subtyping via protocol classes described
179+
below. See `PEP 544 <https://www.python.org/dev/peps/pep-0544/>`_ for
180+
the detailed specification of protocols and structural subtyping in
181+
Python.
182+
183+
Simple user-defined protocols
184+
*****************************
185+
186+
You can define a protocol class by inheriting the special
185187
``typing_extensions.Protocol`` class:
186188

187189
.. code-block:: python
@@ -191,37 +193,42 @@ To define a protocol class, one must inherit the special
191193
192194
class SupportsClose(Protocol):
193195
def close(self) -> None:
194-
...
196+
... # Explicit '...'
197+
198+
class Resource: # No SupportsClose base class!
199+
# ... some methods ...
195200
196-
class Resource: # Note, this class does not have 'SupportsClose' base.
197-
# some methods
198201
def close(self) -> None:
199202
self.resource.release()
200203
201-
def close_all(things: Iterable[SupportsClose]) -> None:
202-
for thing in things:
203-
thing.close()
204+
def close_all(items: Iterable[SupportsClose]) -> None:
205+
for item in items:
206+
item.close()
204207
205-
close_all([Resource(), open('some/file')]) # This passes type check
208+
close_all([Resource(), open('some/file')]) # Okay!
209+
210+
``Resource`` is a subtype of the ``SupportClose`` protocol since it defines
211+
a compatible ``close`` method. Regular file objects returned by ``open()`` are
212+
similarly compatible with the protocol, as they support ``close()``.
206213

207214
.. note::
208215

209-
The ``Protocol`` base class is currently provided in ``typing_extensions``
210-
package. When structural subtyping is mature and
211-
`PEP 544 <https://www.python.org/dev/peps/pep-0544/>`_ is accepted,
212-
``Protocol`` will be included in the ``typing`` module. As well, several
213-
types such as ``typing.Sized``, ``typing.Iterable`` etc. will be made
214-
protocols.
216+
The ``Protocol`` base class is currently provided in the ``typing_extensions``
217+
package. Once structural subtyping is mature and
218+
`PEP 544 <https://www.python.org/dev/peps/pep-0544/>`_ has been accepted,
219+
``Protocol`` will be included in the ``typing`` module. Several library
220+
types such as ``typing.Sized`` and ``typing.Iterable`` will also be changed
221+
into protocols. They are currently treated as regular ABCs by mypy.
215222

216223
Defining subprotocols
217224
*********************
218225

219-
Subprotocols are also supported. Existing protocols can be extended
220-
and merged using multiple inheritance. For example:
226+
You can also define subprotocols. Existing protocols can be extended
227+
and merged using multiple inheritance. Example:
221228

222229
.. code-block:: python
223230
224-
# continuing from previous example
231+
# ... continuing from the previous example
225232
226233
class SupportsRead(Protocol):
227234
def read(self, amount: int) -> bytes: ...
@@ -232,46 +239,47 @@ and merged using multiple inheritance. For example:
232239
class AdvancedResource(Resource):
233240
def __init__(self, label: str) -> None:
234241
self.label = label
242+
235243
def read(self, amount: int) -> bytes:
236244
# some implementation
237245
...
238246
239-
resource = None # type: TaggedReadableResource
240-
241-
# some code
242-
247+
resource: TaggedReadableResource
243248
resource = AdvancedResource('handle with care') # OK
244249
245-
Note that inheriting from existing protocols does not automatically turn
246-
a subclass into a protocol, it just creates a usual (non-protocol) ABC that
247-
implements given protocols. The ``typing_extensions.Protocol`` base must always
248-
be explicitly present:
250+
Note that inheriting from an existing protocol does not automatically
251+
turn the subclass into a protocol -- it just creates a regular
252+
(non-protocol) ABC that implements the given protocol (or
253+
protocols). The ``typing_extensions.Protocol`` base class must always
254+
be explicitly present if you are defining a protocol:
249255

250256
.. code-block:: python
251257
252258
class NewProtocol(SupportsClose): # This is NOT a protocol
253259
new_attr: int
254260
255261
class Concrete:
256-
new_attr = None # type: int
262+
new_attr: int = 0
263+
257264
def close(self) -> None:
258265
...
259-
# Below is an error, since nominal subtyping is used by default
260-
x = Concrete() # type: NewProtocol # Error!
266+
267+
# Error: nominal subtyping used by default
268+
x: NewProtocol = Concrete() # Error!
261269
262270
.. note::
263271

264-
The `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_ variable
265-
annotations can be used to declare protocol attributes. However, protocols
266-
are also supported on Python 2.7 and Python 3.3+ with the help of type
267-
comments and properties, see
268-
`backwards compatibility in PEP 544 <https://www.python.org/dev/peps/pep-0544/#backwards-compatibility>`_.
272+
You can use Python 3.6 variable annotations (`PEP 526
273+
<https://www.python.org/dev/peps/pep-0526/>`_)
274+
to declare protocol attributes. On Python 2.7 and earlier Python 3
275+
versions you can use type comments and properties.
269276

270277
Recursive protocols
271278
*******************
272279

273-
Protocols can be recursive and mutually recursive. This could be useful for
274-
declaring abstract recursive collections such as trees and linked lists:
280+
Protocols can be recursive (self-referential) and mutually
281+
recursive. This is useful for declaring abstract recursive collections
282+
such as trees and linked lists:
275283

276284
.. code-block:: python
277285
@@ -280,8 +288,10 @@ declaring abstract recursive collections such as trees and linked lists:
280288
281289
class TreeLike(Protocol):
282290
value: int
291+
283292
@property
284293
def left(self) -> Optional['TreeLike']: ...
294+
285295
@property
286296
def right(self) -> Optional['TreeLike']: ...
287297
@@ -296,9 +306,9 @@ declaring abstract recursive collections such as trees and linked lists:
296306
Using ``isinstance()`` with protocols
297307
*************************************
298308

299-
To use a protocol class with ``isinstance()``, one needs to decorate it with
300-
a special ``typing_extensions.runtime`` decorator. It will add support for
301-
basic runtime structural checks:
309+
You can use a protocol class with ``isinstance()`` if you decorate it
310+
with the ``typing_extensions.runtime`` class decorator. The decorator
311+
adds support for basic runtime structural checks:
302312

303313
.. code-block:: python
304314
@@ -314,11 +324,9 @@ basic runtime structural checks:
314324
315325
mug = Mug()
316326
if isinstance(mug, Portable):
317-
use(mug.handles) # Works statically and at runtime.
327+
use(mug.handles) # Works statically and at runtime
318328
319329
.. note::
320-
``isinstance()`` is with protocols not completely safe at runtime.
330+
``isinstance()`` with protocols is not completely safe at runtime.
321331
For example, signatures of methods are not checked. The runtime
322-
implementation only checks the presence of all protocol members
323-
in object's MRO.
324-
332+
implementation only checks that all protocol members are defined.

0 commit comments

Comments
 (0)