diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 07ea54ae2b0a5..f8b31e28b0b14 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 @@ -87,7 +99,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 @@ -192,6 +204,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 +260,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 +294,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 @@ -317,11 +332,11 @@ 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). + .. _configuring-warnings: Configuring warnings @@ -469,6 +484,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 @@ -511,6 +527,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 show error location markers. + ``--no-color-output`` This flag will disable color output in error messages, enabled by default. @@ -519,6 +539,10 @@ 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: Incremental mode @@ -556,14 +580,22 @@ 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. -.. _advanced-flags: +``--skip-cache-mtime-checks`` + Skip cache internal consistency checks based on mtime. + -Advanced flags -************** +Advanced options +**************** The following flags are useful mostly for people who are interested in developing or debugging mypy internals. @@ -576,7 +608,10 @@ in developing or debugging mypy internals. If set, this flag will display a full traceback when mypy encounters a fatal error. -``--custom-typing MODULE`` +``--raise-exceptions`` + Raise exception on fatal error. + +``--custom-typing-module MODULE`` This flag lets you use a custom module as a substitute for the :py:mod:`typing` module. @@ -622,6 +657,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 ***************** @@ -632,6 +668,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`` / ``--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. @@ -641,30 +687,29 @@ format into the specified directory. absolute filename to a list of line numbers that belong to typed functions in that file. -``--cobertura-xml-report DIR`` - Causes mypy to generate a Cobertura XML type checking coverage report. +``--lineprecision-report DIR`` + 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. 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. +``--xml-report DIR`` + Causes mypy to generate an XML type checking coverage report. You must install the `lxml`_ library to generate this 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. +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. @@ -681,3 +726,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 2307220a642dd..e0aa200cead34 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 ****************** @@ -80,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 ******** @@ -134,34 +158,36 @@ 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 -***************************** +.. _config-file-import-discovery: -The following config options may be set either globally (in the ``[mypy]`` section) -or on a per-module basis (in sections like ``[mypy-foo.bar]``). +Import discovery +**************** -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 `. +For more information, see the :ref:`Import discovery ` +section of the command line docs. -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). +``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. -.. _config-file-import-discovery-per-module: + This option may only be set in the global section (``[mypy]``). -Import discovery ----------------- +``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. -For more information, see the :ref:`import discovery ` -section of the command line docs. + 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. -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 `. + 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. @@ -194,10 +220,54 @@ 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. +``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]``). + + +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 ------------------------ +*********************** -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) @@ -222,9 +292,9 @@ 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) @@ -245,12 +315,13 @@ 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 --------------------------- +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) @@ -265,11 +336,16 @@ 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) + 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. @@ -284,10 +360,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 +374,13 @@ no analog available via the command line options. ``ignore_errors`` (bool, default False) Ignores all non-fatal errors. + 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 @@ -326,88 +406,42 @@ 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 - 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. - - -Global-only options -******************* - -The following options may only be set in the global section (``[mypy]``). -.. _config-file-import-discovery-global: - -Import discovery ----------------- +Configuring error messages +************************** -For more information, see the :ref:`import discovery ` +For more information, see the :ref:`Configuring error messages ` 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. - -``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. - -``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. - -``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. +These options may only be set in the global section (``[mypy]``). -``files`` (string) +``show_error_context`` (bool, default False) + Prefixes each error with the relevant context. - 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. +``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. -Platform configuration ----------------------- +``pretty`` (bool, default False) + Use visually nicer output in error messages: use soft word wrap, + show source code snippets, and show error location markers. -For more information, see the :ref:`platform configuration ` -section of the command line docs. +``color_output`` (bool, default True) + Shows error messages with color enabled. -``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. +``error_summary`` (bool, default True) + Shows a short summary line after error messages. -``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. +``show_absolute_path`` (bool, default False) + Show absolute paths to files. 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 `. @@ -422,39 +456,25 @@ section of the command line docs. 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.) - -Configuring error messages --------------------------- - -For more information, see the :ref:`configuring error messages ` -section of the command line docs. - -``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. +``skip_cache_mtime_checks`` (bool, default False) + Skip cache internal consistency checks based on mtime. 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. @@ -462,6 +482,9 @@ section of the command line docs. ``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. @@ -475,11 +498,59 @@ section of the command line docs. 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. + +``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. + +``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. + +``lineprecision_report`` (string) + 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. + + You must install the `lxml`_ library to generate this report. + +``xml_report`` (string) + Causes mypy to generate an XML type checking coverage report. + + You must install the `lxml`_ library to generate this report. + + Miscellaneous -------------- +************* -``warn_redundant_casts`` (bool, default False) - Warns about casting an expression to its inferred type. +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 @@ -493,6 +564,5 @@ Miscellaneous ``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.) +.. _lxml: https://pypi.org/project/lxml/ +.. _SQLite: https://www.sqlite.org/ 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 diff --git a/mypy/main.py b/mypy/main.py index 92ac0de385431..25a0bd329d1c3 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', @@ -397,14 +397,11 @@ 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', 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', @@ -459,12 +459,10 @@ 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='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 +490,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", @@ -502,15 +500,49 @@ def add_invertible_flag(flag: str, help="Allow unconditional variable redefinition with a new type", 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) - add_invertible_flag('--no-implicit-reexport', default=True, strict_flag=True, - dest='implicit_reexport', - help="Treat imports as private unless aliased", - group=strictness_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) + + 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 show 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) + add_invertible_flag('--show-absolute-path', default=False, + help="Show absolute paths to files", + group=error_group) incremental_group = parser.add_argument_group( title='Incremental mode', @@ -543,7 +575,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") @@ -554,7 +586,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', @@ -571,47 +603,14 @@ 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='Error reporting', - 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) - add_invertible_flag('--show-absolute-path', default=False, - help="Show absolute paths to files", - 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.') 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') @@ -619,13 +618,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)