diff --git a/docs/source/additional_features.rst b/docs/source/additional_features.rst index c4922d330ae4..fc151598cff0 100644 --- a/docs/source/additional_features.rst +++ b/docs/source/additional_features.rst @@ -286,7 +286,7 @@ run after starting or restarting the daemon. The mypy daemon requires extra fine-grained dependency data in the cache files which aren't included by default. To use caching with -the mypy daemon, use the ``--cache-fine-grained`` option in your CI +the mypy daemon, use the :option:`--cache-fine-grained ` option in your CI build:: $ mypy --cache-fine-grained @@ -326,7 +326,7 @@ at least if your codebase is hundreds of thousands of lines or more: network), the script can still fall back to a normal incremental build. * You can have multiple local cache directories for different local branches - using the ``--cache-dir`` option. If the user switches to an existing + using the :option:`--cache-dir ` option. If the user switches to an existing branch where downloaded cache data is already available, you can continue to use the existing cache data instead of redownloading the data. diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 099cbf1ec680..0cfcbe98cb86 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -6,7 +6,7 @@ The mypy command line ===================== This section documents mypy's command line interface. You can view -a quick summary of the available flags by running ``mypy --help``. +a quick summary of the available flags by running :option:`mypy --help`. .. note:: @@ -44,7 +44,7 @@ for full details, see :ref:`running-mypy`. package. This flag is identical to :option:`--module` apart from this behavior. -.. option -c PROGRAM_TEXT, --command PROGRAM_TEXT +.. option:: -c PROGRAM_TEXT, --command PROGRAM_TEXT Asks mypy to type check the provided string as a program. @@ -523,7 +523,7 @@ of the above sections. .. option:: --strict This flag mode enables all optional error checking flags. You can see the - list of flags enabled by strict mode in the full ``mypy --help`` output. + list of flags enabled by strict mode in the full :option:`mypy --help` output. Note: the exact list of flags enabled by running :option:`--strict` may change over time. diff --git a/docs/source/common_issues.rst b/docs/source/common_issues.rst index ee4a83a63f6a..14369e44cc56 100644 --- a/docs/source/common_issues.rst +++ b/docs/source/common_issues.rst @@ -31,7 +31,7 @@ flagged as an error. return type) are not type-checked, and even the most blatant type errors (e.g. ``2 + 'a'``) pass silently. The solution is to add annotations. Where that isn't possible, functions without annotations - can be checked using ``--check-untyped-defs``. + can be checked using :option:`--check-untyped-defs `. Example: @@ -73,17 +73,17 @@ flagged as an error. `_ for the reason). - **Some imports may be silently ignored**. Another source of - unexpected ``Any`` values are the :ref:`"--ignore-missing-imports" - ` and :ref:`"--follow-imports=skip" - ` flags. When you use ``--ignore-missing-imports``, + unexpected ``Any`` values are the :option:`--ignore-missing-imports + ` and :option:`--follow-imports=skip + ` flags. When you use :option:`--ignore-missing-imports `, any imported module that cannot be found is silently replaced with - ``Any``. When using ``--follow-imports=skip`` the same is true for + ``Any``. When using :option:`--follow-imports=skip ` the same is true for modules for which a ``.py`` file is found but that are not specified on the command line. (If a ``.pyi`` stub is found it is always processed normally, regardless of the value of - ``--follow-imports``.) To help debug the former situation (no - module found at all) leave out ``--ignore-missing-imports``; to get - clarity about the latter use ``--follow-imports=error``. You can + :option:`--follow-imports `.) To help debug the former situation (no + module found at all) leave out :option:`--ignore-missing-imports `; to get + clarity about the latter use :option:`--follow-imports=error `. You can read up about these and other useful flags in :ref:`command-line`. - **A function annotated as returning a non-optional type returns 'None' @@ -418,7 +418,7 @@ Example: Some other expressions exhibit similar behavior; in particular, :py:data:`~typing.TYPE_CHECKING`, variables named ``MYPY``, and any variable -whose name is passed to ``--always-true`` or ``--always-false``. +whose name is passed to :option:`--always-true ` or :option:`--always-false `. (However, ``True`` and ``False`` are not treated specially!) .. note:: @@ -431,14 +431,14 @@ By default, mypy will use your current version of Python and your current operating system as default values for ``sys.version_info`` and ``sys.platform``. -To target a different Python version, use the ``--python-version X.Y`` flag. +To target a different Python version, use the :option:`--python-version X.Y ` flag. For example, to verify your code typechecks if were run using Python 2, pass -in ``--python-version 2.7`` from the command line. Note that you do not need +in :option:`--python-version 2.7 ` from the command line. Note that you do not need to have Python 2.7 installed to perform this check. -To target a different operating system, use the ``--platform PLATFORM`` flag. +To target a different operating system, use the :option:`--platform PLATFORM ` flag. For example, to verify your code typechecks if it were run in Windows, pass -in ``--platform win32``. See the documentation for :py:data:`sys.platform` +in :option:`--platform win32 `. See the documentation for :py:data:`sys.platform` for examples of valid platform parameters. .. _reveal-type: diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index e0aa200cead3..e17a3effd3dc 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -7,11 +7,11 @@ Mypy supports reading configuration settings from a file. By default it uses the file ``mypy.ini`` with fallback to ``setup.cfg`` in the current directory, then ``$XDG_CONFIG_HOME/mypy/config``, then ``~/.config/mypy/config``, and finally ``.mypy.ini`` in the user home directory -if none of them are found; the ``--config-file`` command-line flag can be used -to read a different file instead (see :ref:`--config-file `). +if none of them are found; the :option:`--config-file ` command-line flag can be used +to read a different file instead (see :ref:`config-file-flag`). It is important to understand that there is no merging of configuration -files, as it would lead to ambiguity. The ``--config-file`` flag +files, as it would lead to ambiguity. The :option:`--config-file ` flag has the highest precedence and must be correct; otherwise mypy will report an error and exit. Without command line option, mypy will look for defaults, but will use only one of them. The first one to read is ``mypy.ini``, @@ -134,7 +134,7 @@ This config file specifies three global options in the ``[mypy]`` section. These options will: 1. Type-check your entire project assuming it will be run using Python 2.7. - (This is equivalent to using the ``--python-version 2.7`` or ``--2`` flag). + (This is equivalent to using the :option:`--python-version 2.7 ` or :option:`-2 ` flag). 2. Report an error whenever a function returns a value that is inferred to have type ``Any``. diff --git a/docs/source/error_code_list2.rst b/docs/source/error_code_list2.rst index 4cfd2f2613ab..c84294f95ecf 100644 --- a/docs/source/error_code_list2.rst +++ b/docs/source/error_code_list2.rst @@ -18,7 +18,7 @@ error codes that are enabled by default. Check that type arguments exist [type-arg] ------------------------------------------ -If you use ``--disallow-any-generics``, mypy requires that each generic +If you use :option:`--disallow-any-generics `, mypy requires that each generic type has values for each type argument. For example, the types ``List`` or ``dict`` would be rejected. You should instead use types like ``List[int]`` or ``Dict[str, int]``. Any omitted generic type arguments get implicit ``Any`` @@ -39,7 +39,7 @@ Example: Check that every function has an annotation [no-untyped-def] ------------------------------------------------------------ -If you use ``--disallow-untyped-defs``, mypy requires that all functions +If you use :option:`--disallow-untyped-defs `, mypy requires that all functions have annotations (either a Python 3 annotation or a type comment). Example: @@ -67,7 +67,7 @@ Example: Check that cast is not redundant [redundant-cast] ------------------------------------------------- -If you use ``--warn-redundant-casts``, mypy will generate an error if the source +If you use :option:`--warn-redundant-casts `, mypy will generate an error if the source type of a cast is the same as the target type. Example: @@ -87,7 +87,7 @@ Example: Check that comparisons are overlapping [comparison-overlap] ----------------------------------------------------------- -If you use ``--strict-equality``, mypy will generate an error if it +If you use :option:`--strict-equality `, mypy will generate an error if it thinks that a comparison operation is always true or false. These are often bugs. Sometimes mypy is too picky and the comparison can actually be useful. Instead of disabling strict equality checking @@ -118,7 +118,7 @@ literal: Check that no untyped functions are called [no-untyped-call] ------------------------------------------------------------ -If you use ``--disallow-untyped-calls``, mypy generates an error when you +If you use :option:`--disallow-untyped-calls `, mypy generates an error when you call an unannotated function in an annotated function. Example: @@ -138,7 +138,7 @@ Example: Check that function does not return Any value [no-any-return] ------------------------------------------------------------- -If you use ``--warn-return-any``, mypy generates an error if you return a +If you use :option:`--warn-return-any `, mypy generates an error if you return a value with an ``Any`` type in a function that is annotated to return a non-``Any`` value. @@ -158,7 +158,7 @@ Example: Check that types have no Any components due to missing imports [no-any-unimported] ---------------------------------------------------------------------------------- -If you use ``--disallow-any-unimported``, mypy generates an error if a component of +If you use :option:`--disallow-any-unimported `, mypy generates an error if a component of a type becomes ``Any`` because mypy couldn't resolve an import. These "stealth" ``Any`` types can be surprising and accidentally cause imprecise type checking. diff --git a/docs/source/error_codes.rst b/docs/source/error_codes.rst index aafe95d0f289..869d17842b7a 100644 --- a/docs/source/error_codes.rst +++ b/docs/source/error_codes.rst @@ -23,7 +23,7 @@ Error codes may change in future mypy releases. Displaying error codes ---------------------- -Error codes are not displayed by default. Use ``--show-error-codes`` +Error codes are not displayed by default. Use :option:`--show-error-codes ` to display error codes. Error codes are shown inside square brackets: .. code-block:: text @@ -43,7 +43,7 @@ codes on individual lines using this comment. .. note:: There are command-line flags and config file settings for enabling - certain optional error codes, such as ``--disallow-untype-defs``, + certain optional error codes, such as :option:`--disallow-untyped-defs `, which enables the ``no-untyped-def`` error code. This example shows how to ignore an error about an imported name mypy diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 70a4b31a5d9f..73adceaa3733 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -90,7 +90,7 @@ How do I type check my Python 2 code? You can use a :pep:`comment-based function annotation syntax <484#suggested-syntax-for-python-2-7-and-straddling-code>` -and use the ``--py2`` command-line option to type check your Python 2 code. +and use the :option:`--py2 ` command-line option to type check your Python 2 code. You'll also need to install ``typing`` for Python 2 via ``pip install typing``. Is mypy free? diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index bfba10d38ea9..08e614c73984 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -42,7 +42,7 @@ to your code to take full advantage of mypy. See the section below for details. .. note:: Although you must install Python 3 to run mypy, mypy is fully capable of - type checking Python 2 code as well: just pass in the ``--py2`` flag. See + type checking Python 2 code as well: just pass in the :option:`--py2 ` flag. See :ref:`python2` for more details. .. code-block:: shell @@ -102,7 +102,7 @@ when you are prototyping a new feature, it may be convenient to initially implem the code using dynamic typing and only add type hints later once the code is more stable. Once you are finished migrating or prototyping your code, you can make mypy warn you -if you add a dynamic function by mistake by using the ``--disallow-untyped-defs`` +if you add a dynamic function by mistake by using the :option:`--disallow-untyped-defs ` flag. See :ref:`command-line` for more information on configuring mypy. .. note:: @@ -333,11 +333,11 @@ mypy behaves: see :ref:`command-line` for more details. For example, suppose you want to make sure *all* functions within your codebase are using static typing and make mypy report an error if you add a dynamically-typed function by mistake. You can make mypy do this -by running mypy with the ``--disallow-untyped-defs`` flag. +by running mypy with the :option:`--disallow-untyped-defs ` flag. -Another potentially useful flag is ``--strict``, which enables many +Another potentially useful flag is :option:`--strict `, which enables many (though not all) of the available strictness options -- including -``--disallow-untyped-defs``. +:option:`--disallow-untyped-defs `. This flag is mostly useful if you're starting a new project from scratch and want to maintain a high degree of type safety from day one. However, diff --git a/docs/source/installed_packages.rst b/docs/source/installed_packages.rst index 0014ac53b275..0a509c51fa0d 100644 --- a/docs/source/installed_packages.rst +++ b/docs/source/installed_packages.rst @@ -19,15 +19,15 @@ By default, mypy searches for packages installed for the Python executable running mypy. It is highly unlikely you want this situation if you have installed typed packages in another Python's package directory. -Generally, you can use the ``--python-version`` flag and mypy will try to find +Generally, you can use the :option:`--python-version ` flag and mypy will try to find the correct package directory. If that fails, you can use the -``--python-executable`` flag to point to the exact executable, and mypy will +:option:`--python-executable ` flag to point to the exact executable, and mypy will find packages installed for that Python executable. Note that mypy does not support some more advanced import features, such as zip imports and custom import hooks. -If you do not want to use typed packages, use the ``--no-site-packages`` flag +If you do not want to use typed packages, use the :option:`--no-site-packages ` flag to disable searching. Note that stub-only packages (defined in :pep:`PEP 561: Stub-only Packages diff --git a/docs/source/kinds_of_types.rst b/docs/source/kinds_of_types.rst index 935dd7afe653..acb8a3edff72 100644 --- a/docs/source/kinds_of_types.rst +++ b/docs/source/kinds_of_types.rst @@ -402,7 +402,7 @@ case you should add an explicit ``Optional[...]`` annotation (or type comment). ``Optional[...]`` *does not* mean a function argument with a default value. However, if the default value of an argument is ``None``, you can use an optional type for the argument, but it's not enforced by default. - You can use the ``--no-implicit-optional`` command-line option to stop + You can use the :option:`--no-implicit-optional ` command-line option to stop treating arguments with a ``None`` default value as having an implicit ``Optional[...]`` type. It's possible that this will become the default behavior in the future. @@ -418,7 +418,7 @@ the Java ``null``). In this mode ``None`` is also valid for primitive types such as ``int`` and ``float``, and :py:data:`~typing.Optional` types are not required. -The mode is enabled through the ``--no-strict-optional`` command-line +The mode is enabled through the :option:`--no-strict-optional ` command-line option. In mypy versions before 0.600 this was the default mode. You can enable this option explicitly for backward compatibility with earlier mypy versions, in case you don't want to introduce optional diff --git a/docs/source/more_types.rst b/docs/source/more_types.rst index 833bc84fd09f..8494de1aefee 100644 --- a/docs/source/more_types.rst +++ b/docs/source/more_types.rst @@ -535,7 +535,7 @@ type hints provided on the implementation. For example, in the argument list ``index: Union[int, slice]`` and a return type of ``Union[T, Sequence[T]]``. If there are no annotations on the implementation, then the body is not type checked. If you want to -force mypy to check the body anyways, use the ``--check-untyped-defs`` +force mypy to check the body anyways, use the :option:`--check-untyped-defs ` flag (:ref:`more details here `). The variants must also also be compatible with the implementation diff --git a/docs/source/mypy_daemon.rst b/docs/source/mypy_daemon.rst index 5f75208dd223..c553fb65562f 100644 --- a/docs/source/mypy_daemon.rst +++ b/docs/source/mypy_daemon.rst @@ -1,5 +1,7 @@ .. _mypy_daemon: +.. program:: dmypy + Mypy daemon (mypy server) ========================= @@ -41,8 +43,8 @@ will always run on the current host. Example:: dmypy run -- --follow-imports=error prog.py pkg1/ pkg2/ .. note:: - You'll need to use either the ``--follow-imports=error`` or the - ``--follow-imports=skip`` option with dmypy because the current + You'll need to use either the :option:`--follow-imports=error ` or the + :option:`--follow-imports=skip ` option with dmypy because the current implementation can't follow imports. See :ref:`follow-imports` for details on how these work. You can also define these using a @@ -53,7 +55,7 @@ configuration or mypy version changes. You need to provide all files or directories you want to type check (other than stubs) as arguments. This is a result of the -``--follow-imports`` restriction mentioned above. +:option:`--follow-imports ` restriction mentioned above. The initial run will process all the code and may take a while to finish, but subsequent runs will be quick, especially if you've only @@ -95,8 +97,8 @@ command-specific options. Limitations *********** -* You have to use either the ``--follow-imports=error`` or - the ``--follow-imports=skip`` option because of an implementation +* You have to use either the :option:`--follow-imports=error ` or + the :option:`--follow-imports=skip ` option because of an implementation limitation. This can be defined through the command line or through a :ref:`configuration file `. diff --git a/docs/source/python2.rst b/docs/source/python2.rst index 68be2fa655a7..3e484fb3619f 100644 --- a/docs/source/python2.rst +++ b/docs/source/python2.rst @@ -8,7 +8,7 @@ annotations are given in comments, since the function annotation syntax was introduced in Python 3. The comment-based syntax is specified in :pep:`484`. -Run mypy in Python 2 mode by using the ``--py2`` option:: +Run mypy in Python 2 mode by using the :option:`--py2 ` option:: $ mypy --py2 program.py diff --git a/docs/source/running_mypy.rst b/docs/source/running_mypy.rst index 9f9509b21c3a..40aeb6d383a4 100644 --- a/docs/source/running_mypy.rst +++ b/docs/source/running_mypy.rst @@ -39,7 +39,7 @@ different ways. For more details about how exactly this is done, see :ref:`Mapping file paths to modules `. -2. Second, you can use the ``-m`` flag (long form: ``--module``) to +2. Second, you can use the :option:`-m ` flag (long form: :option:`--module `) to specify a module name to be type checked. The name of a module is identical to the name you would use to import that module within a Python program. For example, running:: @@ -53,16 +53,16 @@ different ways. find where modules and imports are located on the file system. For more details, see :ref:`finding-imports`. -3. Third, you can use the ``-p`` (long form: ``--package``) flag to +3. Third, you can use the :option:`-p ` (long form: :option:`--package `) flag to specify a package to be (recursively) type checked. This flag - is almost identical to the ``-m`` flag except that if you give it + is almost identical to the :option:`-m ` flag except that if you give it a package name, mypy will recursively type check all submodules and subpackages of that package. For example, running:: $ mypy -p html ...will type check the entire ``html`` package (of library stubs). - In contrast, if we had used the ``-m`` flag, mypy would have type + In contrast, if we had used the :option:`-m ` flag, mypy would have type checked just ``html``'s ``__init__.py`` file and anything imported from there. @@ -72,7 +72,7 @@ different ways. $ mypy --package p.a --package p.b --module c 4. Fourth, you can also instruct mypy to directly type check small - strings as programs by using the ``-c`` (long form: ``--command``) + strings as programs by using the :option:`-c ` (long form: :option:`--command `) flag. For example:: $ mypy -c 'x = [1, 2]; print(x())' @@ -207,7 +207,7 @@ type hints nor have time to write your own, you can *silence* the errors: :ref:`import discovery ` in config files. 3. To silence *all* missing import errors for *all* libraries in your codebase, - invoke mypy with the ``--ignore-missing-imports`` command line flag or set + invoke mypy with the :option:`--ignore-missing-imports ` command line flag or set the ``ignore_missing_imports`` :ref:`config file option ` to True in the *global* section of your mypy config file:: @@ -231,7 +231,7 @@ If the module is a part of the standard library, try: Changes to typeshed will come bundled with mypy the next time it's released. In the meantime, you can add a ``# type: ignore`` to silence any relevant errors. After upgrading, we recommend running mypy using the - ``--warn-unused-ignores`` flag to help you find any ``# type: ignore`` + :option:`--warn-unused-ignores ` flag to help you find any ``# type: ignore`` annotations you no longer need. .. _follow-imports: @@ -248,7 +248,7 @@ the former has type hints and the latter does not. We run ``mycode.bar``. How do we want mypy to type check ``mycode.bar``? We can configure the -desired behavior by using the ``--follow-imports`` flag. This flag +desired behavior by using the :option:`--follow-imports ` flag. This flag accepts one of four string values: - ``normal`` (the default) follows all imports normally and @@ -270,19 +270,19 @@ accepts one of four string values: main.py:1: note: (Using --follow-imports=error, module not passed on command line) If you are starting a new codebase and plan on using type hints from -the start, we recommend you use either ``--follow-imports=normal`` -(the default) or ``--follow-imports=error``. Either option will help +the start, we recommend you use either :option:`--follow-imports=normal ` +(the default) or :option:`--follow-imports=error `. Either option will help make sure you are not skipping checking any part of your codebase by accident. If you are planning on adding type hints to a large, existing code base, we recommend you start by trying to make your entire codebase (including -files that do not use type hints) pass under ``--follow-imports=normal``. +files that do not use type hints) pass under :option:`--follow-imports=normal `. This is usually not too difficult to do: mypy is designed to report as few error messages as possible when it is looking at unannotated code. If doing this is intractable, we recommend passing mypy just the files -you want to type check and use ``--follow-imports=silent``. Even if +you want to type check and use :option:`--follow-imports=silent `. Even if mypy is unable to perfectly type check a file, it can still glean some useful information by parsing it (for example, understanding what methods a given object has). See :ref:`existing-code` for more recommendations. @@ -343,7 +343,7 @@ assumed is just ``baz``. If a script (a file not ending in ``.py[i]``) is processed, the module name assumed is ``__main__`` (matching the behavior of the -Python interpreter), unless ``--scripts-are-modules`` is passed. +Python interpreter), unless :option:`--scripts-are-modules ` is passed. .. _finding-imports: @@ -352,7 +352,7 @@ How imports are found ********************* When mypy encounters an ``import`` statement or receives module -names from the command line via the ``--module`` or ``--package`` +names from the command line via the :option:`--module ` or :option:`--package ` flags, mypy tries to find the module on the file system similar to the way Python finds it. However, there are some differences. diff --git a/docs/source/stubs.rst b/docs/source/stubs.rst index 767a5082cd69..7b8eb22dce80 100644 --- a/docs/source/stubs.rst +++ b/docs/source/stubs.rst @@ -18,14 +18,14 @@ Here is an overview of how to create a stub file: * Write a stub file for the library (or an arbitrary module) and store it as a ``.pyi`` file in the same directory as the library module. * Alternatively, put your stubs (``.pyi`` files) in a directory - reserved for stubs (e.g., ``myproject/stubs``). In this case you + reserved for stubs (e.g., :file:`myproject/stubs`). In this case you have to set the environment variable ``MYPYPATH`` to refer to the directory. For example:: $ export MYPYPATH=~/work/myproject/stubs -Use the normal Python file name conventions for modules, e.g. ``csv.pyi`` -for module ``csv``. Use a subdirectory with ``__init__.pyi`` for packages. Note +Use the normal Python file name conventions for modules, e.g. :file:`csv.pyi` +for module ``csv``. Use a subdirectory with :file:`__init__.pyi` for packages. Note that :pep:`561` stub-only packages must be installed, and may not be pointed at through the ``MYPYPATH`` (see :ref:`PEP 561 support `). @@ -49,7 +49,7 @@ in your programs and stub files. .. note:: You may be tempted to point ``MYPYPATH`` to the standard library or - to the ``site-packages`` directory where your 3rd party packages + to the :file:`site-packages` directory where your 3rd party packages are installed. This is almost always a bad idea -- you will likely get tons of error messages about code you didn't write and that mypy can't analyze all that well yet, and in the worst case