From e080f3d21511187c482a440dc0aa87fcbf4eab4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oleg=20H=C3=B6fling?= Date: Mon, 7 Oct 2019 22:37:58 +0200 Subject: [PATCH 1/3] fixed markdown backticks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Oleg Höfling --- docs/source/command_line.rst | 2 +- docs/source/running_mypy.rst | 28 ++++++++++++++-------------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index a757c911b847..673c6f144bd3 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -285,7 +285,7 @@ definitions or calls. None and Optional handling ************************** -The following flags adjust how mypy handles values of type `None`. +The following flags adjust how mypy handles values of type ``None``. For more details, see :ref:`no_strict_optional`. .. _no-implicit-optional: diff --git a/docs/source/running_mypy.rst b/docs/source/running_mypy.rst index 7fff6b410f6c..b05a2b766284 100644 --- a/docs/source/running_mypy.rst +++ b/docs/source/running_mypy.rst @@ -15,7 +15,7 @@ and recommendations on how to handle any issues you may encounter along the way. If you are interested in learning about how to configure the -actual way mypy type checks your code, see our +actual way mypy type checks your code, see our :ref:`command-line` guide. @@ -51,7 +51,7 @@ different ways. Mypy will use an algorithm very similar to the one Python uses to find where modules and imports are located on the file system. - For more details, see :ref:`finding-imports`. + For more details, see :ref:`finding-imports`. 3. Third, you can use the ``-p`` (long form: ``--package``) flag to specify a package to be (recursively) type checked. This flag @@ -97,7 +97,7 @@ you can use this instead:: This file can technically also contain any command line flag, not just file paths. However, if you want to configure many different -flags, the recommended approach is to use a +flags, the recommended approach is to use a :ref:`configuration file ` instead. @@ -105,8 +105,8 @@ flags, the recommended approach is to use a How mypy handles imports ************************ -When mypy encounters an ``import`` statement, it will first -:ref:`attempt to locate ` that module +When mypy encounters an ``import`` statement, it will first +:ref:`attempt to locate ` that module or type stubs for that module in the file system. Mypy will then type check the imported module. There are three different outcomes of this process: @@ -173,9 +173,9 @@ are trying to use has done neither of these things. In that case, you can try: 2. :ref:`Writing your own stub files ` containing type hints for the library. You can point mypy at your type hints either by passing - them in via the command line, by adding the location to the - `MYPYPATH` environment variable, or by using the ``mypy_path`` - :ref:`config file option `. + them in via the command line, by adding the location to the + ``MYPYPATH`` environment variable, or by using the ``mypy_path`` + :ref:`config file option `. Note that if you decide to write your own stub files, they don't need to be complete! A good strategy is to add stubs for just the parts @@ -188,7 +188,7 @@ are trying to use has done neither of these things. In that case, you can try: If the module is a third party library, but you cannot find any existing type hints nor have time to write your own, you can *silence* the errors: -1. To silence a *single* missing import error, add a `# type: ignore` at the end of the +1. To silence a *single* missing import error, add a ``# type: ignore`` at the end of the line containing the import. 2. To silence *all* missing import imports errors from a single library, add @@ -233,7 +233,7 @@ If the module is a part of the standard library, try: errors. After upgrading, we recommend running mypy using the ``--warn-unused-ignores`` flag to help you find any ``# type: ignore`` annotations you no longer need. - + .. _follow-imports: Following imports @@ -243,7 +243,7 @@ Mypy is designed to :ref:`doggedly follow all imports `, even if the imported module is not a file you explicitly wanted mypy to check. For example, suppose we have two modules ``mycode.foo`` and ``mycode.bar``: -the former has type hints and the latter does not. We run +the former has type hints and the latter does not. We run ``mypy -m mycode.foo`` and mypy discovers that ``mycode.foo`` imports ``mycode.bar``. @@ -251,7 +251,7 @@ How do we want mypy to type check ``mycode.bar``? We can configure the desired behavior by using the ``--follow-imports`` flag. This flag accepts one of four string values: -- ``normal`` (the default) follows all imports normally and +- ``normal`` (the default) follows all imports normally and type checks all top level code (as well as the bodies of all functions and methods with at least one type annotation in the signature). @@ -330,12 +330,12 @@ to modules to type check. One more thing about checking modules and packages: if the directory *containing* a module or package specified on the command line has an ``__init__.py[i]`` file, mypy assigns these an absolute module name by -crawling up the path until no ``__init__.py[i]`` file is found. +crawling up the path until no ``__init__.py[i]`` file is found. For example, suppose we run the command ``mypy foo/bar/baz.py`` where ``foo/bar/__init__.py`` exists but ``foo/__init__.py`` does not. Then the module name assumed is ``bar.baz`` and the directory ``foo`` is -added to mypy's module search path. +added to mypy's module search path. On the other hand, if ``foo/bar/__init__.py`` did not exist, ``foo/bar`` would be added to the module search path instead, and the module name From 8605ad3f649fc6931c768609630b4521ceced439 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oleg=20H=C3=B6fling?= Date: Mon, 7 Oct 2019 22:45:32 +0200 Subject: [PATCH 2/3] cleaned up trailing whitespaces reported by doc8 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Oleg Höfling --- docs/source/getting_started.rst | 10 +++++----- docs/source/literal_types.rst | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 57cfcf9887cb..db7ad828e83a 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -165,7 +165,7 @@ The typing module So far, we've added type hints that use only basic concrete types like ``str`` and ``float``. What if we want to express more complex types, -such as "a list of strings" or "an iterable of ints"? +such as "a list of strings" or "an iterable of ints"? You can find many of these more complex static types inside of the ``typing`` module. For example, to indicate that some function can accept a list of @@ -181,7 +181,7 @@ strings, use the ``List`` type from the ``typing`` module: names = ["Alice", "Bob", "Charlie"] ages = [10, 20, 30] - + greet_all(names) # Ok! greet_all(ages) # Error due to incompatible types @@ -234,12 +234,12 @@ to help function signatures look a little cleaner: return 'Hello, ' + name The ``typing`` module contains many other useful types. You can find a -quick overview by looking through the :ref:`mypy cheatsheets ` +quick overview by looking through the :ref:`mypy cheatsheets ` and a more detailed overview (including information on how to make your own generic types or your own type aliases) by looking through the :ref:`type system reference `. -One final note: when adding types, the convention is to import types +One final note: when adding types, the convention is to import types using the form ``from typing import Iterable`` (as opposed to doing just ``import typing`` or ``import typing as t`` or ``from typing import *``). @@ -252,7 +252,7 @@ Local type inference Once you have added type hints to a function (i.e. made it statically typed), mypy will automatically type check that function's body. While doing so, -mypy will try and *infer* as many details as possible. +mypy will try and *infer* as many details as possible. We saw an example of this in the ``normalize_id`` function above -- mypy understands basic ``isinstance`` checks and so can infer that the ``user_id`` variable was of diff --git a/docs/source/literal_types.rst b/docs/source/literal_types.rst index da851fc8f03c..71e95532c2ea 100644 --- a/docs/source/literal_types.rst +++ b/docs/source/literal_types.rst @@ -67,7 +67,7 @@ So, ``Literal[-3, b"foo", True]`` is equivalent to more complex types involving literals a little more convenient. Literal types may also contain ``None``. Mypy will treat ``Literal[None]`` as being -equivalent to just ``None``. This means that ``Literal[4, None]``, +equivalent to just ``None``. This means that ``Literal[4, None]``, ``Union[Literal[4], None]``, and ``Optional[Literal[4]]`` are all equivalent. Literals may also contain aliases to other literal types. For example, the @@ -85,7 +85,7 @@ following program is legal: paint("turquoise") # Does not type check Literals may not contain any other kind of type or expression. This means doing -``Literal[my_instance]``, ``Literal[Any]``, ``Literal[3.14]``, or +``Literal[my_instance]``, ``Literal[Any]``, ``Literal[3.14]``, or ``Literal[{"foo": 2, "bar": 5}]`` are all illegal. Future versions of mypy may relax some of these restrictions. For example, we From dc7704c2005fb4a70d21a665977ba7a06575a4f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oleg=20H=C3=B6fling?= Date: Tue, 8 Oct 2019 00:26:39 +0200 Subject: [PATCH 3/3] more markdown backticks not caught by rst-backticks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Oleg Höfling --- docs/source/class_basics.rst | 4 ++-- docs/source/config_file.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/class_basics.rst b/docs/source/class_basics.rst index a89a7e2637e7..ea16264dcace 100644 --- a/docs/source/class_basics.rst +++ b/docs/source/class_basics.rst @@ -78,8 +78,8 @@ to it explicitly using ``self``: a = self a.x = 1 # Error: 'x' not defined -Annotating `__init__` methods -***************************** +Annotating ``__init__`` methods +******************************* The ``__init__`` method is somewhat special -- it doesn't return a value. This is best expressed as ``-> None``. However, since many feel diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index cd8412408b4b..521a9caffdd2 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -189,7 +189,7 @@ See below for a list of import discovery options that may be used Used in conjunction with ``follow_imports=skip``, this can be used to suppress the import of a module from ``typeshed``, replacing it - with `Any`. + with ``Any``. Used in conjunction with ``follow_imports=error``, this can be used to make any use of a particular ``typeshed`` module an error.