From 394b71c33bebdb908f8ee70df0dfc96d9c799230 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Mon, 21 Oct 2019 05:02:56 +0300 Subject: [PATCH 01/33] Preparing to restructure the document to removing the separation of options to "Per-module and global" and "Global only" options in the config file doc. --- docs/source/command_line.rst | 2 +- docs/source/config_file.rst | 87 +++++++++++++++++------------------- 2 files changed, 43 insertions(+), 46 deletions(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 07ea54ae2b0a5..8b9c354cb1dcc 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -87,7 +87,7 @@ imports. module search path -- this is primarily set from the source files passed on the command line, the ``MYPYPATH`` environment variable, and the :ref:`mypy_path config option - `. + `. Note that this only affects import discovery -- for modules and packages explicitly passed on the command line, mypy still diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index 2307220a642dd..718f00088862a 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -25,6 +25,7 @@ Some flags support user home directory and environment variable expansion. To refer to the user home directory, use ``~`` at the beginning of the path. To expand environment variables use ``$VARNAME`` or ``${VARNAME}``. + Config file format ****************** @@ -134,12 +135,11 @@ assume here is some 3rd party library you've installed and are importing. These module ``somelibrary``. This is useful if ``somelibrary`` is some 3rd party library missing type hints. -.. _per-module-flags: Per-module and global options ***************************** -The following config options may be set either globally (in the ``[mypy]`` section) +Some of the config options may be set either globally (in the ``[mypy]`` section) or on a per-module basis (in sections like ``[mypy-foo.bar]``). If you set an option both globally and for a specific module, the module configuration @@ -147,22 +147,24 @@ options take precedence. This lets you set global defaults and override them on module-by-module basis. If multiple pattern sections match a module, :ref:`the options from the most specific section are used where they disagree `. +Some other options, as specified in their description, +may only be set in the global section (``[mypy]``). + + +Inverting option values +*********************** + Options that take a boolean value may be inverted by adding ``no_`` to their name or by (when applicable) swapping their prefix from ``disallow`` to ``allow`` (and vice versa). -.. _config-file-import-discovery-per-module: Import discovery ----------------- +**************** For more information, see the :ref:`import discovery ` section of the command line docs. -Note: this section describes options that can be used both globally and per-module. -See below for a list of import discovery options that may be used -:ref:`only globally `. - ``ignore_missing_imports`` (bool, default False) Suppresses error messages about imports that cannot be resolved. @@ -194,8 +196,9 @@ See below for a list of import discovery options that may be used Used in conjunction with ``follow_imports=error``, this can be used to make any use of a particular ``typeshed`` module an error. + Disallow dynamic typing ------------------------ +*********************** For more information, see the :ref:`disallowing dynamic typing ` section of the command line docs. @@ -222,7 +225,7 @@ section of the command line docs. Untyped definitions and calls ------------------------------ +***************************** For more information, see the :ref:`untyped definitions and calls ` section of the command line docs. @@ -245,10 +248,9 @@ section of the command line docs. Reports an error whenever a function with type annotations is decorated with a decorator without annotations. -.. _config-file-none-and-optional-handling: None and optional handling --------------------------- +************************** For more information, see the :ref:`None and optional handling ` section of the command line docs. @@ -265,7 +267,7 @@ section of the command line docs. Configuring warnings --------------------- +******************** For more information, see the :ref:`configuring warnings ` section of the command line docs. @@ -284,10 +286,9 @@ section of the command line docs. Shows a warning when encountering any code inferred to be unreachable or redundant after performing type analysis. -.. _config-file-suppressing-errors: Suppressing errors ------------------- +****************** Note: these configuration options are available in the config file only. There is no analog available via the command line options. @@ -299,8 +300,9 @@ no analog available via the command line options. ``ignore_errors`` (bool, default False) Ignores all non-fatal errors. + Miscellaneous strictness flags ------------------------------- +****************************** ``allow_redefinition`` (bool, default False) Allows variables to be redefined with an arbitrary type, as long as the redefinition @@ -326,8 +328,9 @@ Miscellaneous strictness flags Prohibit equality checks, identity checks, and container checks between non-overlapping types. + Platform configuration ----------------------- +********************** ``always_true`` (comma-separated list of strings) Specifies a list of variables that mypy will treat as @@ -338,44 +341,38 @@ Platform configuration compile-time constants that are always false. -Global-only options -******************* - -The following options may only be set in the global section (``[mypy]``). - -.. _config-file-import-discovery-global: - Import discovery ----------------- - -For more information, see the :ref:`import discovery ` -section of the command line docs. - -Note: this section describes only global-only import discovery options. See above for -a list of import discovery options that may be used -:ref:`both per-module and globally `. +***************** ``namespace_packages`` (bool, default False) Enables :pep:`420` style namespace packages. See :ref:`the corresponding flag ` for more information. + This option may only be set in the global section (``[mypy]``). + ``python_executable`` (string) Specifies the path to the Python executable to inspect to collect a list of available :ref:`PEP 561 packages `. User home directory and environment variables will be expanded. Defaults to the executable used to run mypy. + This option may only be set in the global section (``[mypy]``). + ``no_silence_site_packages`` (bool, default False) Enables reporting error messages generated within :pep:`561` compliant packages. Those error messages are suppressed by default, since you are usually not able to control errors in 3rd party code. + This option may only be set in the global section (``[mypy]``). + ``mypy_path`` (string) Specifies the paths to use, after trying the paths from ``MYPYPATH`` environment variable. Useful if you'd like to keep stubs in your repo, along with the config file. Multiple paths are always separated with a ``:`` or ``,`` regardless of the platform. User home directory and environment variables will be expanded. + This option may only be set in the global section (``[mypy]``). + ``files`` (string) A comma-separated list of paths which should be checked by mypy if none are given on the command @@ -383,12 +380,13 @@ a list of import discovery options that may be used files in the current directory and ``**/`` (e.g. ``**/*.py``) matches files in any directories below the current one. User home directory and environment variables will be expanded. + This option may only be set in the global section (``[mypy]``). + Platform configuration ----------------------- +********************** -For more information, see the :ref:`platform configuration ` -section of the command line docs. +These options may only be set in the global section (``[mypy]``). ``python_version`` (string) Specifies the Python version used to parse and check the target @@ -404,10 +402,9 @@ section of the command line docs. Incremental mode ----------------- +**************** -For more information, see the :ref:`incremental mode ` -section of the command line docs. +These options may only be set in the global section (``[mypy]``). ``incremental`` (bool, default True) Enables :ref:`incremental mode `. @@ -429,10 +426,9 @@ section of the command line docs. Configuring error messages --------------------------- +************************** -For more information, see the :ref:`configuring error messages ` -section of the command line docs. +These options may only be set in the global section (``[mypy]``). ``show_error_context`` (bool, default False) Prefixes each error with the relevant context. @@ -451,10 +447,9 @@ section of the command line docs. Advanced options ----------------- +**************** -For more information, see the :ref:`advanced flags ` -section of the command line docs. +These options may only be set in the global section (``[mypy]``). ``pdb`` (bool, default False) Invokes pdb on fatal error. @@ -476,7 +471,9 @@ section of the command line docs. Miscellaneous -------------- +************* + +These options may only be set in the global section (``[mypy]``). ``warn_redundant_casts`` (bool, default False) Warns about casting an expression to its inferred type. From 6dfb4c265c0aa4c4b942903f2e19767a8cc03c13 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Mon, 21 Oct 2019 05:06:04 +0300 Subject: [PATCH 02/33] Merging "Import discovery" sections --- docs/source/config_file.rst | 80 ++++++++++++++++++------------------- 1 file changed, 38 insertions(+), 42 deletions(-) diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index 718f00088862a..abbedca25aed9 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -196,6 +196,44 @@ section of the command line docs. Used in conjunction with ``follow_imports=error``, this can be used to make any use of a particular ``typeshed`` module an error. +``namespace_packages`` (bool, default False) + Enables :pep:`420` style namespace packages. See :ref:`the + corresponding flag ` for more information. + + This option may only be set in the global section (``[mypy]``). + +``python_executable`` (string) + Specifies the path to the Python executable to inspect to collect + a list of available :ref:`PEP 561 packages `. User + home directory and environment variables will be expanded. Defaults to + the executable used to run mypy. + + This option may only be set in the global section (``[mypy]``). + +``no_silence_site_packages`` (bool, default False) + Enables reporting error messages generated within :pep:`561` compliant packages. + Those error messages are suppressed by default, since you are usually + not able to control errors in 3rd party code. + + This option may only be set in the global section (``[mypy]``). + +``mypy_path`` (string) + Specifies the paths to use, after trying the paths from ``MYPYPATH`` environment + variable. Useful if you'd like to keep stubs in your repo, along with the config file. + Multiple paths are always separated with a ``:`` or ``,`` regardless of the platform. + User home directory and environment variables will be expanded. + + This option may only be set in the global section (``[mypy]``). + +``files`` (string) + + A comma-separated list of paths which should be checked by mypy if none are given on the command + line. Supports recursive file globbing using :py:mod:`glob`, where ``*`` (e.g. ``*.py``) matches + files in the current directory and ``**/`` (e.g. ``**/*.py``) matches files in any directories below + the current one. User home directory and environment variables will be expanded. + + This option may only be set in the global section (``[mypy]``). + Disallow dynamic typing *********************** @@ -341,48 +379,6 @@ Platform configuration compile-time constants that are always false. -Import discovery -***************** - -``namespace_packages`` (bool, default False) - Enables :pep:`420` style namespace packages. See :ref:`the - corresponding flag ` for more information. - - This option may only be set in the global section (``[mypy]``). - -``python_executable`` (string) - Specifies the path to the Python executable to inspect to collect - a list of available :ref:`PEP 561 packages `. User - home directory and environment variables will be expanded. Defaults to - the executable used to run mypy. - - This option may only be set in the global section (``[mypy]``). - -``no_silence_site_packages`` (bool, default False) - Enables reporting error messages generated within :pep:`561` compliant packages. - Those error messages are suppressed by default, since you are usually - not able to control errors in 3rd party code. - - This option may only be set in the global section (``[mypy]``). - -``mypy_path`` (string) - Specifies the paths to use, after trying the paths from ``MYPYPATH`` environment - variable. Useful if you'd like to keep stubs in your repo, along with the config file. - Multiple paths are always separated with a ``:`` or ``,`` regardless of the platform. - User home directory and environment variables will be expanded. - - This option may only be set in the global section (``[mypy]``). - -``files`` (string) - - A comma-separated list of paths which should be checked by mypy if none are given on the command - line. Supports recursive file globbing using :py:mod:`glob`, where ``*`` (e.g. ``*.py``) matches - files in the current directory and ``**/`` (e.g. ``**/*.py``) matches files in any directories below - the current one. User home directory and environment variables will be expanded. - - This option may only be set in the global section (``[mypy]``). - - Platform configuration ********************** From e25668be9405bf9ba818abad00305e69b65b8ff0 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Mon, 21 Oct 2019 05:09:05 +0300 Subject: [PATCH 03/33] Reordering sections: moving Examples to the end of the preface part. --- docs/source/config_file.rst | 46 ++++++++++++++++++------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index abbedca25aed9..70d13fa95e441 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -81,6 +81,29 @@ unfortunate, and is subject to change in future versions. Configuration flags are liable to change between releases. +Per-module and global options +***************************** + +Some of the config options may be set either globally (in the ``[mypy]`` section) +or on a per-module basis (in sections like ``[mypy-foo.bar]``). + +If you set an option both globally and for a specific module, the module configuration +options take precedence. This lets you set global defaults and override them on a +module-by-module basis. If multiple pattern sections match a module, :ref:`the options from the +most specific section are used where they disagree `. + +Some other options, as specified in their description, +may only be set in the global section (``[mypy]``). + + +Inverting option values +*********************** + +Options that take a boolean value may be inverted by adding ``no_`` to +their name or by (when applicable) swapping their prefix from +``disallow`` to ``allow`` (and vice versa). + + Examples ******** @@ -136,29 +159,6 @@ assume here is some 3rd party library you've installed and are importing. These missing type hints. -Per-module and global options -***************************** - -Some of the config options may be set either globally (in the ``[mypy]`` section) -or on a per-module basis (in sections like ``[mypy-foo.bar]``). - -If you set an option both globally and for a specific module, the module configuration -options take precedence. This lets you set global defaults and override them on a -module-by-module basis. If multiple pattern sections match a module, :ref:`the options from the -most specific section are used where they disagree `. - -Some other options, as specified in their description, -may only be set in the global section (``[mypy]``). - - -Inverting option values -*********************** - -Options that take a boolean value may be inverted by adding ``no_`` to -their name or by (when applicable) swapping their prefix from -``disallow`` to ``allow`` (and vice versa). - - Import discovery **************** From 4937647982af1028afe99d996a99eba0813de7c1 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Mon, 21 Oct 2019 05:12:08 +0300 Subject: [PATCH 04/33] Fixing broken links. --- docs/source/config_file.rst | 2 ++ docs/source/running_mypy.rst | 10 +++++----- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index 70d13fa95e441..932ff7c27e9d0 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -158,6 +158,7 @@ assume here is some 3rd party library you've installed and are importing. These module ``somelibrary``. This is useful if ``somelibrary`` is some 3rd party library missing type hints. +.. _config-file-import-discovery: Import discovery **************** @@ -286,6 +287,7 @@ section of the command line docs. Reports an error whenever a function with type annotations is decorated with a decorator without annotations. +.. _config-file-none-and-optional-handling: None and optional handling ************************** diff --git a/docs/source/running_mypy.rst b/docs/source/running_mypy.rst index 7c0bc328f91f7..9f9509b21c3af 100644 --- a/docs/source/running_mypy.rst +++ b/docs/source/running_mypy.rst @@ -148,7 +148,7 @@ If the module is a part of your own codebase, try: how you're invoking mypy accordingly. 3. Adding the directory containing that module to either the ``MYPYPATH`` environment variable or the ``mypy_path`` - :ref:`config file option `. + :ref:`config file option `. Note: if the module you are trying to import is actually a *submodule* of some package, you should add the directory containing the *entire* package @@ -175,7 +175,7 @@ are trying to use has done neither of these things. In that case, you can try: 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 `. + :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 @@ -204,12 +204,12 @@ type hints nor have time to write your own, you can *silence* the errors: Note: this option is equivalent to adding a ``# type: ignore`` to every import of ``foobar`` in your codebase. For more information, see the documentation about configuring - :ref:`import discovery ` in config files. + :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 the ``ignore_missing_imports`` - :ref:`config file option ` to True + :ref:`config file option ` to True in the *global* section of your mypy config file:: [mypy] @@ -361,7 +361,7 @@ This is computed from the following items: - The ``MYPYPATH`` environment variable (a colon-separated list of directories). -- The ``mypy_path`` :ref:`config file option `. +- The ``mypy_path`` :ref:`config file option `. - The directories containing the sources given on the command line (see below). - The installed packages marked as safe for type checking (see From 9e9ab74bb0c891f4e8bdd02dfaa9b2723f1117f9 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Mon, 21 Oct 2019 05:54:35 +0300 Subject: [PATCH 05/33] Reordering options and sections to match the command line doc --- docs/source/config_file.rst | 104 ++++++++++++++++++------------------ 1 file changed, 52 insertions(+), 52 deletions(-) diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index 932ff7c27e9d0..6463923a7fe2e 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -166,6 +166,12 @@ Import discovery For more information, see the :ref:`import discovery ` section of the command line docs. +``namespace_packages`` (bool, default False) + Enables :pep:`420` style namespace packages. See :ref:`the + corresponding flag ` for more information. + + This option may only be set in the global section (``[mypy]``). + ``ignore_missing_imports`` (bool, default False) Suppresses error messages about imports that cannot be resolved. @@ -197,12 +203,6 @@ section of the command line docs. Used in conjunction with ``follow_imports=error``, this can be used to make any use of a particular ``typeshed`` module an error. -``namespace_packages`` (bool, default False) - Enables :pep:`420` style namespace packages. See :ref:`the - corresponding flag ` for more information. - - This option may only be set in the global section (``[mypy]``). - ``python_executable`` (string) Specifies the path to the Python executable to inspect to collect a list of available :ref:`PEP 561 packages `. User @@ -236,6 +236,34 @@ section of the command line docs. This option may only be set in the global section (``[mypy]``). +Platform configuration +********************** + +``python_version`` (string) + Specifies the Python version used to parse and check the target + program. The string should be in the format ``DIGIT.DIGIT`` -- + for example ``2.7``. The default is the version of the Python + interpreter used to run mypy. + + This option may only be set in the global section (``[mypy]``). + +``platform`` (string) + Specifies the OS platform for the target program, for example + ``darwin`` or ``win32`` (meaning OS X or Windows, respectively). + The default is the current platform as revealed by Python's + :py:data:`sys.platform` variable. + + This option may only be set in the global section (``[mypy]``). + +``always_true`` (comma-separated list of strings) + Specifies a list of variables that mypy will treat as + compile-time constants that are always true. + +``always_false`` (comma-separated list of strings) + Specifies a list of variables that mypy will treat as + compile-time constants that are always false. + + Disallow dynamic typing *********************** @@ -312,6 +340,11 @@ Configuring warnings For more information, see the :ref:`configuring warnings ` section of the command line docs. +``warn_redundant_casts`` (bool, default False) + Warns about casting an expression to its inferred type. + + This option may only be set in the global section (``[mypy]``). + ``warn_unused_ignores`` (bool, default False) Warns about unneeded ``# type: ignore`` comments. @@ -369,34 +402,25 @@ Miscellaneous strictness flags non-overlapping types. -Platform configuration -********************** - -``always_true`` (comma-separated list of strings) - Specifies a list of variables that mypy will treat as - compile-time constants that are always true. +Configuring error messages +************************** -``always_false`` (comma-separated list of strings) - Specifies a list of variables that mypy will treat as - compile-time constants that are always false. +These options may only be set in the global section (``[mypy]``). +``show_error_context`` (bool, default False) + Prefixes each error with the relevant context. -Platform configuration -********************** +``show_column_numbers`` (bool, default False) + Shows column numbers in error messages. -These options may only be set in the global section (``[mypy]``). +``show_error_codes`` (bool, default False) + Shows error codes in error messages. See :ref:`error-codes` for more information. -``python_version`` (string) - Specifies the Python version used to parse and check the target - program. The string should be in the format ``DIGIT.DIGIT`` -- - for example ``2.7``. The default is the version of the Python - interpreter used to run mypy. +``color_output`` (bool, default True) + Shows error messages with color enabled. -``platform`` (string) - Specifies the OS platform for the target program, for example - ``darwin`` or ``win32`` (meaning OS X or Windows, respectively). - The default is the current platform as revealed by Python's - :py:data:`sys.platform` variable. +``error_summary`` (bool, default True) + Shows a short summary line after error messages. Incremental mode @@ -423,27 +447,6 @@ These options may only be set in the global section (``[mypy]``). check and regenerate the cache if it was written by older versions of mypy.) -Configuring error messages -************************** - -These options may only be set in the global section (``[mypy]``). - -``show_error_context`` (bool, default False) - Prefixes each error with the relevant context. - -``show_column_numbers`` (bool, default False) - Shows column numbers in error messages. - -``show_error_codes`` (bool, default False) - Shows error codes in error messages. See :ref:`error-codes` for more information. - -``color_output`` (bool, default True) - Shows error messages with color enabled. - -``error_summary`` (bool, default True) - Shows a short summary line after error messages. - - Advanced options **************** @@ -473,9 +476,6 @@ Miscellaneous These options may only be set in the global section (``[mypy]``). -``warn_redundant_casts`` (bool, default False) - Warns about casting an expression to its inferred type. - ``scripts_are_modules`` (bool, default False) Makes script ``x`` become module ``x`` instead of ``__main__``. This is useful when checking multiple scripts in a single run. From 2b0c50569f50bc0e1ac2c196f0ac556f68b65bce Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Mon, 21 Oct 2019 05:55:10 +0300 Subject: [PATCH 06/33] Old typo fixed (Optional should be written with capital O) --- docs/source/config_file.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index 6463923a7fe2e..236a7ff3ea908 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -317,10 +317,10 @@ section of the command line docs. .. _config-file-none-and-optional-handling: -None and optional handling +None and Optional handling ************************** -For more information, see the :ref:`None and optional handling ` +For more information, see the :ref:`None and Optional handling ` section of the command line docs. ``no_implicit_optional`` (bool, default False) From 8b5cff1b22a6da03133285e53a888f94f2f25e59 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Mon, 21 Oct 2019 05:55:57 +0300 Subject: [PATCH 07/33] Removed new_semantic_analyzer option that is now obsolete as the old semantic analyzer support is removed --- docs/source/config_file.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index 236a7ff3ea908..f2454cb679206 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -487,7 +487,3 @@ These options may only be set in the global section (``[mypy]``). ``verbosity`` (integer, default 0) Controls how much debug output will be generated. Higher numbers are more verbose. - -``new_semantic_analyzer`` (bool, default True) - Enables the new, improved, semantic analyzer. - (See :ref:`The mypy command line ` for more information.) From 7480ff437fb52825ade2537c7c62fa914d6adede Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Tue, 22 Oct 2019 04:48:11 +0300 Subject: [PATCH 08/33] Unifying section separators --- docs/source/command_line.rst | 8 ++++++++ docs/source/config_file.rst | 2 ++ 2 files changed, 10 insertions(+) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 8b9c354cb1dcc..114f262ff5688 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -192,6 +192,7 @@ For more information on how to use these flags, see :ref:`version_and_platform_c compile-time constants that are always false. This flag may be repeated. + .. _disallow-dynamic-typing: Disallow dynamic typing @@ -247,6 +248,7 @@ The following options are available: the base class even though that may not actually be the case. This flag makes mypy raise an error instead. + .. _untyped-definitions-and-calls: Untyped definitions and calls @@ -280,6 +282,7 @@ definitions or calls. This flag reports an error whenever a function with type annotations is decorated with a decorator without annotations. + .. _none-and-optional-handling: None and Optional handling @@ -322,6 +325,7 @@ For more details, see :ref:`no_strict_optional`. mypy 0.600, and in previous versions it had to be explicitly enabled using ``--strict-optional`` (which is still accepted). + .. _configuring-warnings: Configuring warnings @@ -469,6 +473,7 @@ of the above sections. Note: the exact list of flags enabled by running ``--strict`` may change over time. + .. _configuring-error-messages: Configuring error messages @@ -519,6 +524,7 @@ in error messages. including total number of errors, number of files with errors, and number of files checked. + .. _incremental: Incremental mode @@ -560,6 +566,7 @@ beyond what incremental mode can offer, try running mypy in By default, mypy will ignore cache data generated by a different version of mypy. This flag disables that behavior. + .. _advanced-flags: Advanced flags @@ -622,6 +629,7 @@ in developing or debugging mypy internals. cause mypy to type check the contents of ``temp.py`` instead of ``original.py``, but error messages will still reference ``original.py``. + Report generation ***************** diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index f2454cb679206..d95e6808b206c 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -158,6 +158,7 @@ assume here is some 3rd party library you've installed and are importing. These module ``somelibrary``. This is useful if ``somelibrary`` is some 3rd party library missing type hints. + .. _config-file-import-discovery: Import discovery @@ -315,6 +316,7 @@ section of the command line docs. Reports an error whenever a function with type annotations is decorated with a decorator without annotations. + .. _config-file-none-and-optional-handling: None and Optional handling From 8f3a33c56cae5d289c17d683f0a832af152e90af Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Tue, 22 Oct 2019 04:48:19 +0300 Subject: [PATCH 09/33] Note formatting fixed --- docs/source/config_file.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index d95e6808b206c..eeb9372dd4952 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -333,7 +333,8 @@ section of the command line docs. Enables or disables strict Optional checks. If False, mypy treats ``None`` as compatible with every type. - **Note:** This was False by default in mypy versions earlier than 0.600. +.. note:: + This was False by default in mypy versions earlier than 0.600. Configuring warnings From 525a25af48f201467527456096456cc253a5a880 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Tue, 22 Oct 2019 04:48:55 +0300 Subject: [PATCH 10/33] Added allow_untyped_globals description from command line doc --- docs/source/config_file.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index eeb9372dd4952..d922980fe2b82 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -380,6 +380,10 @@ no analog available via the command line options. Miscellaneous strictness flags ****************************** +``allow_untyped_globals`` (bool, default False) + Causes mypy to suppress errors caused by not being able to fully + infer the types of global and class variables. + ``allow_redefinition`` (bool, default False) Allows variables to be redefined with an arbitrary type, as long as the redefinition is in the same block and nesting level as the original definition. From 1e55ebc63183cda40c51baced3dbafea0a52c971 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Tue, 22 Oct 2019 04:52:26 +0300 Subject: [PATCH 11/33] "Advanced flags" section renamed to "Advanced options" to match the config file documentation --- docs/source/command_line.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 114f262ff5688..a65e71da2f706 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -567,10 +567,8 @@ beyond what incremental mode can offer, try running mypy in version of mypy. This flag disables that behavior. -.. _advanced-flags: - -Advanced flags -************** +Advanced options +**************** The following flags are useful mostly for people who are interested in developing or debugging mypy internals. From 7132a2d3c166e4458f562a72f402d5150184c1c0 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Tue, 22 Oct 2019 05:04:01 +0300 Subject: [PATCH 12/33] Copied "Report generation" section from command line documentation --- docs/source/config_file.rst | 42 +++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index d922980fe2b82..2300a5976a3e3 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -478,6 +478,46 @@ These options may only be set in the global section (``[mypy]``). in combination with ``disallow_untyped_defs`` or ``disallow_incomplete_defs``. +Report generation +***************** + +If these options are set, mypy will generate a report in the specified +format into the specified directory. + +``any_exprs_report`` (string) + Causes mypy to generate a text file report documenting how many + expressions of type ``Any`` are present within your codebase. + +``linecount_report`` (string) + Causes mypy to generate a text file report documenting the functions + and lines that are typed and untyped within your codebase. + +``linecoverage_report`` (string) + Causes mypy to generate a JSON file that maps each source file's + absolute filename to a list of line numbers that belong to typed + functions in that file. + +``cobertura_xml_report`` (string) + Causes mypy to generate a Cobertura XML type checking coverage report. + + You must install the `lxml`_ library to generate this report. + +``html_report`` / ``xslt_html_report`` (string) + Causes mypy to generate an HTML type checking coverage report. + + You must install the `lxml`_ library to generate this report. + +``txt_report`` / ``xslt_txt_report`` (string) + Causes mypy to generate a text file type checking coverage report. + + You must install the `lxml`_ library to generate this report. + +``junit_xml`` (string) + Causes mypy to generate a JUnit XML test result document with + type checking results. This can make it easier to integrate mypy + with continuous integration (CI) tools. + + Miscellaneous ************* @@ -494,3 +534,5 @@ These options may only be set in the global section (``[mypy]``). ``verbosity`` (integer, default 0) Controls how much debug output will be generated. Higher numbers are more verbose. + +.. _lxml: https://pypi.org/project/lxml/ From f9b2dbbe440c7abfbe1f02aecc4f034db0f0b5ab Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Tue, 22 Oct 2019 05:21:52 +0300 Subject: [PATCH 13/33] Added options mentioned in `--help` but lacking documentation --- docs/source/command_line.rst | 9 +++++++++ docs/source/config_file.rst | 9 +++++++++ 2 files changed, 18 insertions(+) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index a65e71da2f706..c32eacb91aba1 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -647,6 +647,15 @@ format into the specified directory. absolute filename to a list of line numbers that belong to typed functions in that file. +``--lineprecision-report DIR`` + TBD + +``--memory-xml-report DIR`` + TBD + +``--xml-report DIR`` + TBD + ``--cobertura-xml-report DIR`` Causes mypy to generate a Cobertura XML type checking coverage report. diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index 2300a5976a3e3..b455f8c38686a 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -497,6 +497,15 @@ format into the specified directory. absolute filename to a list of line numbers that belong to typed functions in that file. +``lineprecision_report`` (string) + TBD + +``memory_xml_report`` (string) + TBD + +``xml_report`` (string) + TBD + ``cobertura_xml_report`` (string) Causes mypy to generate a Cobertura XML type checking coverage report. From 0fb3f9812fcbe671ffc8ee1ba91c2ad7c4187a8c Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Tue, 22 Oct 2019 05:34:31 +0300 Subject: [PATCH 14/33] Minor description correction --- docs/source/config_file.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index b455f8c38686a..b98bbd5b7c016 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -227,7 +227,7 @@ section of the command line docs. This option may only be set in the global section (``[mypy]``). -``files`` (string) +``files`` (comma-separated list of strings) A comma-separated list of paths which should be checked by mypy if none are given on the command line. Supports recursive file globbing using :py:mod:`glob`, where ``*`` (e.g. ``*.py``) matches From d2e738f0bb9e3f3ea3cd82cb16591054b4565ae4 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Tue, 22 Oct 2019 05:39:28 +0300 Subject: [PATCH 15/33] Added options that are mentioned in `--help` but were otherwise undocumented --- docs/source/command_line.rst | 22 ++++++++++++++++++++++ docs/source/config_file.rst | 22 ++++++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index c32eacb91aba1..b6e7b843007eb 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -325,6 +325,11 @@ For more details, see :ref:`no_strict_optional`. mypy 0.600, and in previous versions it had to be explicitly enabled using ``--strict-optional`` (which is still accepted). +``--strict-optional-whitelist [GLOB [GLOB ...]]`` + Suppress strict ``Optional`` errors in all but the provided files; + implies ``--strict-optional`` (may suppress certain other errors + in non-whitelisted files). + .. _configuring-warnings: @@ -516,6 +521,10 @@ in error messages. See :ref:`error-codes` for more information. +``--pretty`` + Use visually nicer output in error messages: use soft word wrap, + show source code snippets and error location markers. + ``--no-color-output`` This flag will disable color output in error messages, enabled by default. @@ -562,10 +571,19 @@ beyond what incremental mode can offer, try running mypy in writing to the cache, use ``--cache-dir=/dev/null`` (UNIX) or ``--cache-dir=nul`` (Windows). +``--sqlite-cache`` + Use an `SQLite`_ database to store the cache. + +``--cache-fine-grained`` + Include fine-grained dependency information in the cache for the mypy daemon. + ``--skip-version-check`` By default, mypy will ignore cache data generated by a different version of mypy. This flag disables that behavior. +``--skip-cache-mtime-checks`` + Skip cache internal consistency checks based on mtime. + Advanced options **************** @@ -581,6 +599,9 @@ in developing or debugging mypy internals. If set, this flag will display a full traceback when mypy encounters a fatal error. +``--raise-exceptions`` + Raise exception on fatal error. + ``--custom-typing MODULE`` This flag lets you use a custom module as a substitute for the :py:mod:`typing` module. @@ -696,3 +717,4 @@ Miscellaneous by this flag is often more convenient.) .. _lxml: https://pypi.org/project/lxml/ +.. _SQLite: https://www.sqlite.org/ diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index b98bbd5b7c016..ede16c5180cc1 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -336,6 +336,11 @@ section of the command line docs. .. note:: This was False by default in mypy versions earlier than 0.600. +``strict_optional_whitelist`` (comma-separated list of strings) + Suppress strict ``Optional`` errors in all but the provided files; + implies ``strict_optional`` (may suppress certain other errors + in non-whitelisted files). + Configuring warnings ******************** @@ -423,6 +428,10 @@ These options may only be set in the global section (``[mypy]``). ``show_error_codes`` (bool, default False) Shows error codes in error messages. See :ref:`error-codes` for more information. +``pretty`` (bool, default False) + Use visually nicer output in error messages: use soft word wrap, + show source code snippets and error location markers. + ``color_output`` (bool, default True) Shows error messages with color enabled. @@ -448,11 +457,20 @@ These options may only be set in the global section (``[mypy]``). but is always written to, unless the value is set to ``/dev/null`` (UNIX) or ``nul`` (Windows). +``sqlite_cache`` (bool, default False) + Use an `SQLite`_ database to store the cache. + +``cache_fine_grained`` (bool, default False) + Include fine-grained dependency information in the cache for the mypy daemon. + ``skip_version_check`` (bool, default False) Makes mypy use incremental cache data even if it was generated by a different version of mypy. (By default, mypy will perform a version check and regenerate the cache if it was written by older versions of mypy.) +``skip_cache_mtime_checks`` (bool, default False) + Skip cache internal consistency checks based on mtime. + Advanced options **************** @@ -465,6 +483,9 @@ These options may only be set in the global section (``[mypy]``). ``show_traceback`` (bool, default False) Shows traceback on fatal error. +``raise_exceptions`` (bool, default False) + Raise exception on fatal error. + ``custom_typing_module`` (string) Specifies a custom module to use as a substitute for the :py:mod:`typing` module. @@ -545,3 +566,4 @@ These options may only be set in the global section (``[mypy]``). Controls how much debug output will be generated. Higher numbers are more verbose. .. _lxml: https://pypi.org/project/lxml/ +.. _SQLite: https://www.sqlite.org/ From 72f156400fca5939a6bddb91344031ef4919282b Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Tue, 22 Oct 2019 05:48:19 +0300 Subject: [PATCH 16/33] Minor formatting fix --- docs/source/config_file.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index ede16c5180cc1..c78d22a025935 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -228,7 +228,6 @@ section of the command line docs. This option may only be set in the global section (``[mypy]``). ``files`` (comma-separated list of strings) - A comma-separated list of paths which should be checked by mypy if none are given on the command line. Supports recursive file globbing using :py:mod:`glob`, where ``*`` (e.g. ``*.py``) matches files in the current directory and ``**/`` (e.g. ``**/*.py``) matches files in any directories below From 1b5f20d522047b83d354b5e699813af5c6bec236 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Tue, 22 Oct 2019 15:04:28 +0300 Subject: [PATCH 17/33] Fixed #7772. --- mypy/main.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mypy/main.py b/mypy/main.py index c8029c67a7ab6..87943e761d09e 100644 --- a/mypy/main.py +++ b/mypy/main.py @@ -554,7 +554,7 @@ def add_invertible_flag(flag: str, '--raise-exceptions', action='store_true', help="Raise exception on fatal error" ) internals_group.add_argument( - '--custom-typing', metavar='MODULE', dest='custom_typing_module', + '--custom-typing-module', metavar='MODULE', dest='custom_typing_module', help="Use a custom typing module") internals_group.add_argument( '--custom-typeshed-dir', metavar='DIR', From 6617210556ae8f922da6f980a289a57150926b98 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Tue, 22 Oct 2019 15:15:48 +0300 Subject: [PATCH 18/33] Sections in --help are renamed to match the command line documentation --- mypy/main.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/mypy/main.py b/mypy/main.py index 87943e761d09e..0097629baa15e 100644 --- a/mypy/main.py +++ b/mypy/main.py @@ -397,7 +397,7 @@ def add_invertible_flag(flag: str, help="Additional variable to be considered False (may be repeated)") disallow_any_group = parser.add_argument_group( - title='Dynamic typing', + title='Disallow dynamic typing', description="Disallow the use of the dynamic 'Any' type under certain conditions.") disallow_any_group.add_argument( '--disallow-any-unimported', default=False, action='store_true', @@ -464,7 +464,7 @@ def add_invertible_flag(flag: str, "in non-whitelisted files)") lint_group = parser.add_argument_group( - title='Warnings', + title='Configuring warnings', description="Detect code that is sound but redundant or problematic.") add_invertible_flag('--warn-redundant-casts', default=False, strict_flag=True, help="Warn about casting an expression to its inferred type", @@ -492,7 +492,7 @@ def add_invertible_flag(flag: str, # We add `--strict` near the end so we don't accidentally miss any strictness # flags that are added after this group. strictness_group = parser.add_argument_group( - title='Other strictness checks') + title='Miscellaneous strictness flags') add_invertible_flag('--allow-untyped-globals', default=False, strict_flag=False, help="Suppress toplevel errors caused by missing annotations", @@ -543,7 +543,7 @@ def add_invertible_flag(flag: str, help="Skip cache internal consistency checks based on mtime") internals_group = parser.add_argument_group( - title='Mypy internals', + title='Advanced options', description="Debug and customize mypy internals.") internals_group.add_argument( '--pdb', action='store_true', help="Invoke pdb on fatal error") @@ -572,7 +572,7 @@ def add_invertible_flag(flag: str, group=internals_group) error_group = parser.add_argument_group( - title='Error reporting', + title='Configuring error messages', description="Adjust the amount of detail shown in error messages.") add_invertible_flag('--show-error-context', default=False, dest='show_error_context', From 9873348f6a370e4aecfd2708f303a2f0d8cf02cf Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Tue, 22 Oct 2019 15:17:26 +0300 Subject: [PATCH 19/33] Sections in --help reordered match the command line documentation --- mypy/main.py | 62 ++++++++++++++++++++++++++-------------------------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/mypy/main.py b/mypy/main.py index 0097629baa15e..6be20874848fb 100644 --- a/mypy/main.py +++ b/mypy/main.py @@ -512,6 +512,37 @@ def add_invertible_flag(flag: str, help="Treat imports as private unless aliased", group=strictness_group) + error_group = parser.add_argument_group( + title='Configuring error messages', + description="Adjust the amount of detail shown in error messages.") + add_invertible_flag('--show-error-context', default=False, + dest='show_error_context', + help='Precede errors with "note:" messages explaining context', + group=error_group) + add_invertible_flag('--show-column-numbers', default=False, + help="Show column numbers in error messages", + group=error_group) + add_invertible_flag('--show-error-codes', default=False, + help="Show error codes in error messages", + group=error_group) + add_invertible_flag('--pretty', default=False, + help="Use visually nicer output in error messages:" + " Use soft word wrap, show source code snippets," + " and error location markers", + group=error_group) + add_invertible_flag('--no-color-output', dest='color_output', default=True, + help="Do not colorize error messages", + group=error_group) + add_invertible_flag('--no-error-summary', dest='error_summary', default=True, + help="Do not show error stats summary", + group=error_group) + + strict_help = "Strict mode; enables the following flags: {}".format( + ", ".join(strict_flag_names)) + strictness_group.add_argument( + '--strict', action='store_true', dest='special-opts:strict', + help=strict_help) + incremental_group = parser.add_argument_group( title='Incremental mode', description="Adjust how mypy incrementally type checks and caches modules. " @@ -571,37 +602,6 @@ def add_invertible_flag(flag: str, add_invertible_flag('--fast-exit', default=False, help=argparse.SUPPRESS, group=internals_group) - error_group = parser.add_argument_group( - title='Configuring error messages', - description="Adjust the amount of detail shown in error messages.") - add_invertible_flag('--show-error-context', default=False, - dest='show_error_context', - help='Precede errors with "note:" messages explaining context', - group=error_group) - add_invertible_flag('--show-column-numbers', default=False, - help="Show column numbers in error messages", - group=error_group) - add_invertible_flag('--show-error-codes', default=False, - help="Show error codes in error messages", - group=error_group) - add_invertible_flag('--pretty', default=False, - help="Use visually nicer output in error messages:" - " Use soft word wrap, show source code snippets," - " and error location markers", - group=error_group) - add_invertible_flag('--no-color-output', dest='color_output', default=True, - help="Do not colorize error messages", - group=error_group) - add_invertible_flag('--no-error-summary', dest='error_summary', default=True, - help="Do not show error stats summary", - group=error_group) - - strict_help = "Strict mode; enables the following flags: {}".format( - ", ".join(strict_flag_names)) - strictness_group.add_argument( - '--strict', action='store_true', dest='special-opts:strict', - help=strict_help) - report_group = parser.add_argument_group( title='Report generation', description='Generate a report in the specified format.') From 4f399c56619b05a9c0b698bc73b7a04d430504d0 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Tue, 22 Oct 2019 15:44:23 +0300 Subject: [PATCH 20/33] Report generations options reordered to match the order in --help --- docs/source/command_line.rst | 32 ++++++++++++++++---------------- docs/source/config_file.rst | 34 +++++++++++++++++++--------------- 2 files changed, 35 insertions(+), 31 deletions(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index b6e7b843007eb..afe0d49833022 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -659,6 +659,16 @@ format into the specified directory. Causes mypy to generate a text file report documenting how many expressions of type ``Any`` are present within your codebase. +``--cobertura-xml-report DIR`` + Causes mypy to generate a Cobertura XML type checking coverage report. + + You must install the `lxml`_ library to generate this report. + +``--html-report DIR``, ``--xslt-html-report DIR`` + Causes mypy to generate an HTML type checking coverage report. + + You must install the `lxml`_ library to generate this report. + ``--linecount-report DIR`` Causes mypy to generate a text file report documenting the functions and lines that are typed and untyped within your codebase. @@ -674,33 +684,23 @@ format into the specified directory. ``--memory-xml-report DIR`` TBD -``--xml-report DIR`` - TBD - -``--cobertura-xml-report DIR`` - Causes mypy to generate a Cobertura XML type checking coverage report. +``--txt-report DIR``, ``--xslt-txt-report DIR`` + Causes mypy to generate a text file type checking coverage report. You must install the `lxml`_ library to generate this report. -``--html-report DIR``, ``--xslt-html-report DIR`` - Causes mypy to generate an HTML type checking coverage report. - - You must install the `lxml`_ library to generate this report. +``--xml-report DIR`` + TBD -``--txt-report DIR``, ``--xslt-txt-report DIR`` - Causes mypy to generate a text file type checking coverage report. - You must install the `lxml`_ library to generate this report. +Miscellaneous +************* ``--junit-xml JUNIT_XML`` Causes mypy to generate a JUnit XML test result document with type checking results. This can make it easier to integrate mypy with continuous integration (CI) tools. - -Miscellaneous -************* - ``--find-occurrences CLASS.MEMBER`` This flag will make mypy print out all usages of a class member based on static type information. This feature is experimental. diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index c78d22a025935..79042f45372f4 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -508,6 +508,16 @@ format into the specified directory. Causes mypy to generate a text file report documenting how many expressions of type ``Any`` are present within your codebase. +``cobertura_xml_report`` (string) + Causes mypy to generate a Cobertura XML type checking coverage report. + + You must install the `lxml`_ library to generate this report. + +``html_report`` / ``xslt_html_report`` (string) + Causes mypy to generate an HTML type checking coverage report. + + You must install the `lxml`_ library to generate this report. + ``linecount_report`` (string) Causes mypy to generate a text file report documenting the functions and lines that are typed and untyped within your codebase. @@ -523,17 +533,6 @@ format into the specified directory. ``memory_xml_report`` (string) TBD -``xml_report`` (string) - TBD - -``cobertura_xml_report`` (string) - Causes mypy to generate a Cobertura XML type checking coverage report. - - You must install the `lxml`_ library to generate this report. - -``html_report`` / ``xslt_html_report`` (string) - Causes mypy to generate an HTML type checking coverage report. - You must install the `lxml`_ library to generate this report. ``txt_report`` / ``xslt_txt_report`` (string) @@ -541,10 +540,10 @@ format into the specified directory. You must install the `lxml`_ library to generate this report. -``junit_xml`` (string) - Causes mypy to generate a JUnit XML test result document with - type checking results. This can make it easier to integrate mypy - with continuous integration (CI) tools. +``xml_report`` (string) + TBD + + You must install the `lxml`_ library to generate this report. Miscellaneous @@ -552,6 +551,11 @@ Miscellaneous These options may only be set in the global section (``[mypy]``). +``junit_xml`` (string) + Causes mypy to generate a JUnit XML test result document with + type checking results. This can make it easier to integrate mypy + with continuous integration (CI) tools. + ``scripts_are_modules`` (bool, default False) Makes script ``x`` become module ``x`` instead of ``__main__``. This is useful when checking multiple scripts in a single run. From b786b3b4cb6782393632afade273376e294b8989 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Tue, 22 Oct 2019 15:45:11 +0300 Subject: [PATCH 21/33] Options in --help reordered to match the command line documentation --- mypy/main.py | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/mypy/main.py b/mypy/main.py index 6be20874848fb..0b3f86f4d1170 100644 --- a/mypy/main.py +++ b/mypy/main.py @@ -348,6 +348,10 @@ def add_invertible_flag(flag: str, imports_group = parser.add_argument_group( title='Import discovery', description="Configure how imports are discovered and followed.") + add_invertible_flag( + '--namespace-packages', default=False, + help="Support namespace packages (PEP 420, __init__.py-less)", + group=imports_group) imports_group.add_argument( '--ignore-missing-imports', action='store_true', help="Silently ignore imports of missing modules") @@ -366,10 +370,6 @@ def add_invertible_flag(flag: str, imports_group.add_argument( '--no-silence-site-packages', action='store_true', help="Do not silence errors in PEP 561 compliant installed packages") - add_invertible_flag( - '--namespace-packages', default=False, - help="Support namespace packages (PEP 420, __init__.py-less)", - group=imports_group) platform_group = parser.add_argument_group( title='Platform configuration', @@ -402,9 +402,6 @@ def add_invertible_flag(flag: str, disallow_any_group.add_argument( '--disallow-any-unimported', default=False, action='store_true', help="Disallow Any types resulting from unfollowed imports") - add_invertible_flag('--disallow-subclassing-any', default=False, strict_flag=True, - help="Disallow subclassing values of type 'Any' when defining classes", - group=disallow_any_group) disallow_any_group.add_argument( '--disallow-any-expr', default=False, action='store_true', help='Disallow all expressions that have type Any') @@ -418,6 +415,9 @@ def add_invertible_flag(flag: str, add_invertible_flag('--disallow-any-generics', default=False, strict_flag=True, help='Disallow usage of generic types that do not specify explicit type ' 'parameters', group=disallow_any_group) + add_invertible_flag('--disallow-subclassing-any', default=False, strict_flag=True, + help="Disallow subclassing values of type 'Any' when defining classes", + group=disallow_any_group) untyped_group = parser.add_argument_group( title='Untyped definitions and calls', @@ -502,16 +502,16 @@ def add_invertible_flag(flag: str, help="Allow unconditional variable redefinition with a new type", group=strictness_group) - add_invertible_flag('--strict-equality', default=False, strict_flag=False, - help="Prohibit equality, identity, and container checks for" - " non-overlapping types", - group=strictness_group) - add_invertible_flag('--no-implicit-reexport', default=True, strict_flag=True, dest='implicit_reexport', help="Treat imports as private unless aliased", group=strictness_group) + add_invertible_flag('--strict-equality', default=False, strict_flag=False, + help="Prohibit equality, identity, and container checks for" + " non-overlapping types", + group=strictness_group) + error_group = parser.add_argument_group( title='Configuring error messages', description="Adjust the amount of detail shown in error messages.") @@ -616,13 +616,13 @@ def add_invertible_flag(flag: str, '--quickstart-file', help=argparse.SUPPRESS) other_group.add_argument( '--junit-xml', help="Write junit.xml to the given file") - other_group.add_argument( - '--scripts-are-modules', action='store_true', - help="Script x becomes module x instead of __main__") other_group.add_argument( '--find-occurrences', metavar='CLASS.MEMBER', dest='special-opts:find_occurrences', help="Print out all usages of a class member (experimental)") + other_group.add_argument( + '--scripts-are-modules', action='store_true', + help="Script x becomes module x instead of __main__") if server_options: # TODO: This flag is superfluous; remove after a short transition (2018-03-16) From 81d05a0f59af205bc468182659165aa75162df55 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Tue, 22 Oct 2019 15:53:09 +0300 Subject: [PATCH 22/33] Formatting improvement to Report generation options --- docs/source/command_line.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index afe0d49833022..3e5cfce6885c7 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -664,7 +664,7 @@ format into the specified directory. You must install the `lxml`_ library to generate this report. -``--html-report DIR``, ``--xslt-html-report DIR`` +``--html-report`` / ``--xslt-html-report DIR`` Causes mypy to generate an HTML type checking coverage report. You must install the `lxml`_ library to generate this report. @@ -684,7 +684,9 @@ format into the specified directory. ``--memory-xml-report DIR`` TBD -``--txt-report DIR``, ``--xslt-txt-report DIR`` + You must install the `lxml`_ library to generate this report. + +``--txt-report`` / ``--xslt-txt-report DIR`` Causes mypy to generate a text file type checking coverage report. You must install the `lxml`_ library to generate this report. @@ -692,6 +694,8 @@ format into the specified directory. ``--xml-report DIR`` TBD + You must install the `lxml`_ library to generate this report. + Miscellaneous ************* From bb1a2c7b6de8cd88dc911c2d443193094c51012b Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Tue, 22 Oct 2019 16:01:29 +0300 Subject: [PATCH 23/33] Documentation for -h, -v, -V command line options added --- docs/source/command_line.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 3e5cfce6885c7..e848e6ea9e6f6 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -44,6 +44,18 @@ for full details, see :ref:`running-mypy`. Asks mypy to type check the provided string as a program. +Optional arguments +****************** + +``-h`` / ``--help`` + Show help message and exit. + +``-v`` / ``--verbose`` + More verbose messages. + +``-V`` / ``--version`` + Show program's version number and exit. + .. _config-file-flag: Config file From 6d734872875313df8ba65435bb1884447ff59dac Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Wed, 23 Oct 2019 02:35:34 +0300 Subject: [PATCH 24/33] Improving Report generation options documentation as discussed --- docs/source/command_line.rst | 10 +++------- docs/source/config_file.rst | 10 +++------- 2 files changed, 6 insertions(+), 14 deletions(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index e848e6ea9e6f6..39a47b61dd611 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -691,12 +691,8 @@ format into the specified directory. functions in that file. ``--lineprecision-report DIR`` - TBD - -``--memory-xml-report DIR`` - TBD - - You must install the `lxml`_ library to generate this report. + Causes mypy to generate a flat text file report with per-module + statistics of how many lines are typechecked etc. ``--txt-report`` / ``--xslt-txt-report DIR`` Causes mypy to generate a text file type checking coverage report. @@ -704,7 +700,7 @@ format into the specified directory. You must install the `lxml`_ library to generate this report. ``--xml-report DIR`` - TBD + Causes mypy to generate an XML type checking coverage report. You must install the `lxml`_ library to generate this report. diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index 79042f45372f4..83523a2dc6a44 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -528,12 +528,8 @@ format into the specified directory. functions in that file. ``lineprecision_report`` (string) - TBD - -``memory_xml_report`` (string) - TBD - - You must install the `lxml`_ library to generate this report. + Causes mypy to generate a flat text file report with per-module + statistics of how many lines are typechecked etc. ``txt_report`` / ``xslt_txt_report`` (string) Causes mypy to generate a text file type checking coverage report. @@ -541,7 +537,7 @@ format into the specified directory. You must install the `lxml`_ library to generate this report. ``xml_report`` (string) - TBD + Causes mypy to generate an XML type checking coverage report. You must install the `lxml`_ library to generate this report. From d70a8640063dabdbbb43e871d77aafece4e9773f Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Wed, 23 Oct 2019 02:44:47 +0300 Subject: [PATCH 25/33] Improving Report generation options documentation as discussed --- mypy/main.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/mypy/main.py b/mypy/main.py index 0b3f86f4d1170..0dbdebd9f5ac0 100644 --- a/mypy/main.py +++ b/mypy/main.py @@ -606,9 +606,10 @@ def add_invertible_flag(flag: str, title='Report generation', description='Generate a report in the specified format.') for report_type in sorted(defaults.REPORTER_NAMES): - report_group.add_argument('--%s-report' % report_type.replace('_', '-'), - metavar='DIR', - dest='special-opts:%s_report' % report_type) + if report_type not in {'memory-xml',}: + report_group.add_argument('--%s-report' % report_type.replace('_', '-'), + metavar='DIR', + dest='special-opts:%s_report' % report_type) other_group = parser.add_argument_group( title='Miscellaneous') From 51228fabfe39678f0ddb13e7895772f73c5155fc Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Wed, 23 Oct 2019 02:45:13 +0300 Subject: [PATCH 26/33] Removed --strict-optional-whitelist option from documentation as discussed --- docs/source/command_line.rst | 5 ----- docs/source/config_file.rst | 5 ----- mypy/main.py | 4 +--- 3 files changed, 1 insertion(+), 13 deletions(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 39a47b61dd611..f462b61a53dfc 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -337,11 +337,6 @@ For more details, see :ref:`no_strict_optional`. mypy 0.600, and in previous versions it had to be explicitly enabled using ``--strict-optional`` (which is still accepted). -``--strict-optional-whitelist [GLOB [GLOB ...]]`` - Suppress strict ``Optional`` errors in all but the provided files; - implies ``--strict-optional`` (may suppress certain other errors - in non-whitelisted files). - .. _configuring-warnings: diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index 83523a2dc6a44..3a7d06d93a939 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -335,11 +335,6 @@ section of the command line docs. .. note:: This was False by default in mypy versions earlier than 0.600. -``strict_optional_whitelist`` (comma-separated list of strings) - Suppress strict ``Optional`` errors in all but the provided files; - implies ``strict_optional`` (may suppress certain other errors - in non-whitelisted files). - Configuring warnings ******************** diff --git a/mypy/main.py b/mypy/main.py index 0dbdebd9f5ac0..6b747b4d73184 100644 --- a/mypy/main.py +++ b/mypy/main.py @@ -459,9 +459,7 @@ def add_invertible_flag(flag: str, help="Disable strict Optional checks (inverse: --strict-optional)") none_group.add_argument( '--strict-optional-whitelist', metavar='GLOB', nargs='*', - help="Suppress strict Optional errors in all but the provided files; " - "implies --strict-optional (may suppress certain other errors " - "in non-whitelisted files)") + help=argparse.SUPPRESS) lint_group = parser.add_argument_group( title='Configuring warnings', From ec2e47b33291b0f0a3204898c9a47249c772af29 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Wed, 23 Oct 2019 02:48:19 +0300 Subject: [PATCH 27/33] Fixed --pretty documentation as discussed. --- docs/source/command_line.rst | 2 +- docs/source/config_file.rst | 2 +- mypy/main.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index f462b61a53dfc..e8acb3e81d1c8 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -530,7 +530,7 @@ in error messages. ``--pretty`` Use visually nicer output in error messages: use soft word wrap, - show source code snippets and error location markers. + show source code snippets, and show error location markers. ``--no-color-output`` This flag will disable color output in error messages, enabled by default. diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index 3a7d06d93a939..03d22dac4da9f 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -424,7 +424,7 @@ These options may only be set in the global section (``[mypy]``). ``pretty`` (bool, default False) Use visually nicer output in error messages: use soft word wrap, - show source code snippets and error location markers. + show source code snippets, and show error location markers. ``color_output`` (bool, default True) Shows error messages with color enabled. diff --git a/mypy/main.py b/mypy/main.py index 6b747b4d73184..2e873473d6bd0 100644 --- a/mypy/main.py +++ b/mypy/main.py @@ -526,7 +526,7 @@ def add_invertible_flag(flag: str, add_invertible_flag('--pretty', default=False, help="Use visually nicer output in error messages:" " Use soft word wrap, show source code snippets," - " and error location markers", + " and show error location markers", group=error_group) add_invertible_flag('--no-color-output', dest='color_output', default=True, help="Do not colorize error messages", From 44847248c71c72c65e5c0bee4667c7b60198f1f8 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Wed, 23 Oct 2019 02:49:59 +0300 Subject: [PATCH 28/33] Moving mypy_path and files to the top of the section, as discussed --- docs/source/config_file.rst | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index 03d22dac4da9f..b06c06c11d293 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -167,6 +167,22 @@ Import discovery For more information, see the :ref:`import discovery ` section of the command line docs. +``mypy_path`` (string) + Specifies the paths to use, after trying the paths from ``MYPYPATH`` environment + variable. Useful if you'd like to keep stubs in your repo, along with the config file. + Multiple paths are always separated with a ``:`` or ``,`` regardless of the platform. + User home directory and environment variables will be expanded. + + This option may only be set in the global section (``[mypy]``). + +``files`` (comma-separated list of strings) + A comma-separated list of paths which should be checked by mypy if none are given on the command + line. Supports recursive file globbing using :py:mod:`glob`, where ``*`` (e.g. ``*.py``) matches + files in the current directory and ``**/`` (e.g. ``**/*.py``) matches files in any directories below + the current one. User home directory and environment variables will be expanded. + + This option may only be set in the global section (``[mypy]``). + ``namespace_packages`` (bool, default False) Enables :pep:`420` style namespace packages. See :ref:`the corresponding flag ` for more information. @@ -219,22 +235,6 @@ section of the command line docs. This option may only be set in the global section (``[mypy]``). -``mypy_path`` (string) - Specifies the paths to use, after trying the paths from ``MYPYPATH`` environment - variable. Useful if you'd like to keep stubs in your repo, along with the config file. - Multiple paths are always separated with a ``:`` or ``,`` regardless of the platform. - User home directory and environment variables will be expanded. - - This option may only be set in the global section (``[mypy]``). - -``files`` (comma-separated list of strings) - A comma-separated list of paths which should be checked by mypy if none are given on the command - line. Supports recursive file globbing using :py:mod:`glob`, where ``*`` (e.g. ``*.py``) matches - files in the current directory and ``**/`` (e.g. ``**/*.py``) matches files in any directories below - the current one. User home directory and environment variables will be expanded. - - This option may only be set in the global section (``[mypy]``). - Platform configuration ********************** From 7ae15499b07bcd8045cee34f7e83a2316e0c6f6c Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Wed, 23 Oct 2019 02:58:39 +0300 Subject: [PATCH 29/33] --no-strict-optional notes made less visible --- docs/source/command_line.rst | 3 +-- docs/source/config_file.rst | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index e8acb3e81d1c8..193c22aa70500 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -332,8 +332,7 @@ For more details, see :ref:`no_strict_optional`. generally check the use of ``None`` values -- they are valid everywhere. See :ref:`no_strict_optional` for more about this feature. -.. note:: - Strict optional checking was enabled by default starting in + **Note:** Strict optional checking was enabled by default starting in mypy 0.600, and in previous versions it had to be explicitly enabled using ``--strict-optional`` (which is still accepted). diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index b06c06c11d293..ddfdbdcfc969a 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -332,8 +332,7 @@ section of the command line docs. Enables or disables strict Optional checks. If False, mypy treats ``None`` as compatible with every type. -.. note:: - This was False by default in mypy versions earlier than 0.600. + **Note:** This was False by default in mypy versions earlier than 0.600. Configuring warnings From e18c6706882c52017c86de3e560a0ee2e2ace521 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Wed, 23 Oct 2019 03:02:59 +0300 Subject: [PATCH 30/33] Restored an accidentally lost blurb; also fixing typography for other "For more information" links. --- docs/source/config_file.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index ddfdbdcfc969a..046bfeca9a36a 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -164,7 +164,7 @@ assume here is some 3rd party library you've installed and are importing. These Import discovery **************** -For more information, see the :ref:`import discovery ` +For more information, see the :ref:`Import discovery ` section of the command line docs. ``mypy_path`` (string) @@ -267,7 +267,7 @@ Platform configuration Disallow dynamic typing *********************** -For more information, see the :ref:`disallowing dynamic typing ` +For more information, see the :ref:`Disallow dynamic typing ` section of the command line docs. ``disallow_any_unimported`` (bool, default False) @@ -294,7 +294,7 @@ section of the command line docs. Untyped definitions and calls ***************************** -For more information, see the :ref:`untyped definitions and calls ` +For more information, see the :ref:`Untyped definitions and calls ` section of the command line docs. ``disallow_untyped_calls`` (bool, default False) @@ -338,7 +338,7 @@ section of the command line docs. Configuring warnings ******************** -For more information, see the :ref:`configuring warnings ` +For more information, see the :ref:`Configuring warnings ` section of the command line docs. ``warn_redundant_casts`` (bool, default False) @@ -410,6 +410,9 @@ Miscellaneous strictness flags Configuring error messages ************************** +For more information, see the :ref:`Configuring error messages ` +section of the command line docs. + These options may only be set in the global section (``[mypy]``). ``show_error_context`` (bool, default False) From 109b100a9b876ea498ec6bdbf1c67b06f69d4c15 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Wed, 23 Oct 2019 03:05:52 +0300 Subject: [PATCH 31/33] Fixed custom typing module option name --- docs/source/command_line.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 193c22aa70500..f0780accb1781 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -608,7 +608,7 @@ in developing or debugging mypy internals. ``--raise-exceptions`` Raise exception on fatal error. -``--custom-typing MODULE`` +``--custom-typing-module MODULE`` This flag lets you use a custom module as a substitute for the :py:mod:`typing` module. From 68e5ca4faf557b2679a575d3dea11eb64b43d0fc Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Wed, 23 Oct 2019 03:24:59 +0300 Subject: [PATCH 32/33] Added documentation for --show-absolute-path. --- docs/source/command_line.rst | 3 +++ docs/source/config_file.rst | 3 +++ 2 files changed, 6 insertions(+) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index f0780accb1781..f8b31e28b0b14 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -539,6 +539,9 @@ in error messages. including total number of errors, number of files with errors, and number of files checked. +``--show-absolute-path`` + Show absolute paths to files. + .. _incremental: diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index 046bfeca9a36a..e0aa200cead34 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -434,6 +434,9 @@ These options may only be set in the global section (``[mypy]``). ``error_summary`` (bool, default True) Shows a short summary line after error messages. +``show_absolute_path`` (bool, default False) + Show absolute paths to files. + Incremental mode **************** From 1b0e1831736f32b8ccce6cc9d6e1a9d17b7ce069 Mon Sep 17 00:00:00 2001 From: Vasily Zakharov Date: Wed, 23 Oct 2019 03:29:50 +0300 Subject: [PATCH 33/33] flake8 fix --- mypy/main.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/mypy/main.py b/mypy/main.py index f945f7e229281..25a0bd329d1c3 100644 --- a/mypy/main.py +++ b/mypy/main.py @@ -544,7 +544,6 @@ def add_invertible_flag(flag: str, help="Show absolute paths to files", group=error_group) - incremental_group = parser.add_argument_group( title='Incremental mode', description="Adjust how mypy incrementally type checks and caches modules. " @@ -608,7 +607,7 @@ def add_invertible_flag(flag: str, title='Report generation', description='Generate a report in the specified format.') for report_type in sorted(defaults.REPORTER_NAMES): - if report_type not in {'memory-xml',}: + if report_type not in {'memory-xml'}: report_group.add_argument('--%s-report' % report_type.replace('_', '-'), metavar='DIR', dest='special-opts:%s_report' % report_type)