# Prospector > Documentation for Prospector --- # Source: https://github.com/prospector-dev/prospector/blob/master/docs/changelog.rst .. _`changelog`: .. include:: ../CHANGELOG.rst --- # Source: https://github.com/prospector-dev/prospector/blob/master/docs/contents.rst Contents --------- .. toctree:: :caption: Table of Contents :maxdepth: 2 :numbered: 1 index usage profiles suppression supported_tools pre-commit contrib .. only:: html .. toctree:: :maxdepth: 1 changelog --- # Source: https://github.com/prospector-dev/prospector/blob/master/docs/contrib.rst Contributing ============ All contributions are very welcome! You can contribute in many ways: * Join the `python code quality`_ mailing list and answer questions. * Report bugs on the GitHub `issue tracker`_. * Submit pull requests on the GitHub `repository`_. Ideally make a pull request to the *develop* branch, as I prefer to keep the master branch the same as the most recent release on PyPI. If you do this, be sure to add yourself to the CONTRIBUTORS.md file too! .. _python code quality: https://mail.python.org/mailman/listinfo/code-quality .. _issue tracker: https://github.com/PyCQA/prospector/issues .. _repository: https://github.com/PyCQA/prospector Code Quality ------------ As a code quality testing tool, it makes sense to strive to be a good example of good code! To that end, prospector is checked by `Landscape `_ and ideally when making a pull request, please take note of any decreases in quality. Additionally, there is a `pre-commit `_ configuration to prevent various small problems before they are committed. Check the site for more information but the short version is to install it first before committing:: pre-commit install Tests ----- There are not a huge number of tests right now, as most of the code in Prospector is handling the output of other tools. However, please do run them before submitting a pull request:: pytest Prospector targets Python 3.6, 3.7, 3.8, 3.9 and 3.10. You can use `tox`_ to test this locally, and all tests are run on github Actions. .. _tox: https://tox.readthedocs.io/en/latest/ .. include:: ../CONTRIBUTORS.rst Developer Reference -------------------- .. toctree:: :maxdepth: 2 reference --- # Source: https://github.com/prospector-dev/prospector/blob/master/docs/index.rst .. Prospector documentation master file, created by sphinx-quickstart on Sun Sep 28 11:26:59 2014. Prospector - Python Static Analysis =================================== About ----- .. image:: https://img.shields.io/pypi/v/prospector.svg :target: https://pypi.python.org/pypi/prospector :alt: Latest Version of Prospector .. image:: https://github.com/PyCQA/prospector/actions/workflows/tests.yml/badge.svg :target: https://github.com/PyCQA/prospector/actions/workflows/tests.yml :alt: Build Status .. image:: https://img.shields.io/coveralls/PyCQA/prospector.svg?style=flat :target: https://coveralls.io/r/PyCQA/prospector :alt: Test Coverage Prospector is a tool to analyse Python code and output information about errors, potential problems, convention violations and complexity. It brings together the functionality of other Python analysis tools such as `Pylint`_, `pycodestyle`_, and `McCabe complexity`_. See the :doc:`Supported Tools` section for a complete list of default and optional extra tools. The primary aim of Prospector is to be useful 'out of the box'. A common complaint of other Python analysis tools is that it takes a long time to filter through which errors are relevant or interesting to your own coding style. Prospector provides some default profiles, which hopefully will provide a good starting point and will be useful straight away, and adapts the output depending on the libraries your project uses. .. _pylint: https://pylint.readthedocs.io/ .. _pycodestyle: https://pycodestyle.pycqa.org/ .. _McCabe complexity: https://pypi.python.org/pypi/mccabe Installation ------------ You can install default tools using ``pip`` command:: pip install prospector For a full list of optional extra tools, and specific examples to install each of them, see the :doc:`page on supported tools `. For example to install an optional tool such as ``pyroma``:: pip install prospector[with_pyroma] .. Note:: Some shells (such as ``Zsh``, the default shell of macOS Catalina) require brackets to be escaped:: pip install prospector\[with_pyroma\] To install two or more optional extra tools at the same time, they must be comma separated (and without spaces). For example to install mypy and bandit:: pip install prospector[with_mypy,with_bandit] And to install all optional extra tools at the same time, install prospector using the ``with_everything`` option:: pip install prospector[with_everything] For best results, you should install prospector to the same place as your project and its dependencies. That is, if you are using virtual environments, install prospector into that virtual environment alongside your code. This allows the underlying tools to give better results, as they can infer and use knowledge of libraries that you use. If you install prospector system-wide and use it on a project in a virtual environment, you will see several incorrect errors because prospector cannot access the libraries your project uses. Usage ----- Simply run prospector from the root of your project:: prospector This will output a list of messages pointing out potential problems or errors, for example:: prospector.tools.base (prospector/tools/base.py): L5:0 ToolBase: pylint - R0922 Abstract class is only referenced 1 times Read about the full list of options in the :doc:`usage ` page. It is also possible to use prospector as a :doc:`pre-commit hook `. Behaviour --------- Adapting to Dependencies ```````````````````````` Prospector will `try to detect `_ the libraries that your project uses, and adapt the output and filtering to those libraries. For example, if you use Django, the `pylint-django `_ plugin will be loaded to help Pylint inspect Django-specific code. There is currently support for the following frameworks: - `Celery `_ - `Django `_ - `Flask `_ If you have a suggestion for another framework or library which should be supported, please `add an issue `_ or :doc:`consider creating a pull request `. Strictness `````````` Prospector can be configured to be more or less strict. The more strict, the more errors and warnings it will find. At higher strictness levels, you may find that the output is a bit too picky. The default level is designed to give useful output and warnings but also to suppress messages which are not necessarily useful. To change the strictness level:: prospector --strictness high Valid levels are ``verylow``, ``low``, ``medium``, ``high`` and ``veryhigh``. Profiles ```````` A profile is a YAML file containing various directives about which messages and which tools to allow or disable. Profiles can inherit from each other, allowing you to adapt the behaviour of existing profiles or compose several smaller specialised profiles into one to suit your project. Note that the 'strictness' is implemented as a profile. There is more detail about profiles and how to use them on :doc:`the profiles documentation ` page. Pre-commit Hook ``````````````` Prospector can be configured as a `pre-commit `_ hook. For more information see :doc:`the pre-commit documentation `. License ------- Prospector is available under the GPLv2 License. --- # Source: https://github.com/prospector-dev/prospector/blob/master/docs/pre-commit.rst Pre-commit Hook =============== If you'd like Prospector to be run automatically when making changes to files in your Git repository, you can install `pre-commit`_ and add the following text to your repositories' ``.pre-commit-config.yaml``:: repos: - repo: https://github.com/PyCQA/prospector rev: 1.10.0 # The version of Prospector to use, if not 'master' for latest hooks: - id: prospector .. _pre-commit: https://pre-commit.com/ Commandline Arguments --------------------- Some controls for prospector, especially surrounding how the output is displayed, are not :doc:`configurable from a profile `, only from the commandline. To add command-line arguments to the pre-commit hook config file:: repos: - repo: https://github.com/PyCQA/prospector rev: 1.10.0 hooks: - id: prospector args: - --summary-only Optional Tools -------------- By default the configuration will only install :doc:`the base supported tools ` and not optional tools. If you also use optional tools, for example bandit or mypy, then you can add them to the hook configuration like so:: repos: - repo: https://github.com/PyCQA/prospector rev: 1.10.0 hooks: - id: prospector additional_dependencies: - ".[with-mypy,with-bandit]" - args: [ '--with-tool=mypy', '--with-tool=bandit', ] This is equivalent to running:: pip install prospector[with-bandit,with-mypy] --- # Source: https://github.com/prospector-dev/prospector/blob/master/docs/profiles.rst Profiles / Configuration ======================== The behavior of prospector can be configured by creating a profile. A profile is a YAML file containing several sections as described below. Prospector will search for a ``.prospector.yaml`` file (and `several others`_) in the path that it is checking. If found, it will automatically be loaded. Otherwise, you can pass in the profile as an argument:: prospector --profile /path/to/your/profile.yaml You can also use a name instead of the path, if it is on the ``profile-path``:: prospector --profile my_profile In general, command-line arguments override and take precedence over values found in profiles. .. _several others: https://github.com/PyCQA/prospector/blob/master/prospector/profiles/__init__.py .. _profile_path: Profile Path ------------ The name of a profile is the filename without the ``.yaml`` extension. So if you create a profile called 'my_project.yaml', the name will be 'my_project'. Inheritance works by searching the ``profile-path`` for files matching the name in the inheritance list. The ``profile-path`` is where Prospector should search when looking for profiles. By default, it will look in the directory containing the `built-in profiles`_, as well as the directory where prospector is running, and a ``.prospector`` directory relative to that. To add additional places to search:: prospector --profile-path path/to/your/profiles .. _built-in profiles: https://github.com/PyCQA/prospector/tree/master/prospector/profiles/profiles Example ------- Here is an example profile:: output-format: json strictness: medium test-warnings: true doc-warnings: false inherits: - my/other/profile.yml ignore-paths: - docs ignore-patterns: - (^|/)skip(this)?(/|$) pycodestyle: disable: - W602 - W603 enable: - W601 options: max-line-length: 79 mccabe: run: false Builtin Profiles ---------------- Prospector comes with several built-in profiles, which power some of strictness and style options. You can see the `full list on GitHub `_. Global Configuration options ---------------------------- Global configuration options for tools are the following: * output-format_ * strictness_ * test-warnings_ * doc-warnings_ * member-warnings_ * inherits_ * ignore-paths_ * ignore-patterns_ * autodetect_ * uses_ * max-line-length_ .. _output-format: Output-format ............. Same command line options are available. See :doc:`Output format ` .. _strictness: Strictness .......... There is a command line argument to tweak how picky Prospector will be:: prospector --strictness This is implemented using profiles, and is simply a list of messages to disable at each level of strictness. If creating your own profile, you can use the ``strictness`` like so:: strictness: medium Valid values are ``verylow``, ``low``, ``medium`` (the default), ``high`` and ``veryhigh``. If you don't specify a strictness value, then the default of ``medium`` will be used. To avoid using any of Prospector's default strictness profiles, set ``strictness: none``. There are some aspects of analysis which can be turned on or off separately from the strictness or individual tuning of the tools. Example: .. _doc-warnings: Documentation Warnings ...................... By default prospector will not produce warnings about missing documentation or `docstring styleguide violations `_. If you want to see these, use the ``--doc-warnings`` flag at runtime or include it in your profile:: doc-warnings: true This will turn on the otherwise disabled ``pycodestyle`` tool. .. _test-warnings: Test Warnings ............. Prospector will not inspect unit tests and test files by default. You can turn this on using the ``--test-warnings`` flag or in your profile:: test-warnings: true .. _member-warnings: Member Warnings ............... Pylint generates warnings when you try to access an attribute of a class that does not exist, or import a module that does not exist. Unfortunately it is not always accurate and in some projects, this message is a large amount of noise. Prospector therefore turns these messages off by default, but you can turn it on using the ``--member-warnings`` flag or in a profile:: member-warnings: true .. _uses: .. _autodetect: Libraries Used and Autodetect ............................. Prospector will adjust the behavior of the underlying tools based on the libraries that your project uses. If you use Django, for example, the `pylint-django `_ plugin will be loaded. This will happen automatically. If prospector is not correctly determining which of its supported libraries you use, you can specify it manually in the profile:: uses: - django - celery - flask Currently, Django, Flask and Celery have plugins. If prospector is incorrectly deciding that you use one of these, you can turn off autodetection:: autodetect: false .. _inherits: Inheritance ........... Profiles can inherit from other profiles, and can inherit from more than one profile. Prospector merges together all of the options in each profile, starting at the top of the inheritance tree and overwriting values with those found lower. The example profile above inherits from another profile provided by the user, ``my/other/profile.yml``. This allows you to have, for example, a project wide default profile with specific overrides for each individual repository or library. It is possible to inherit from the built-in prospector profiles as well, although there are shortcuts for most of the built-ins, see below.:: inherits: - strictness_medium - full_pep8 For lists, such as the ``ignore`` section, they will be merged together rather than overwritten - so essentially, the ``ignore`` section will accumulate. The profile named in the ``inherits`` section must be on the :ref:`profile path `. Inheritance can also be optional - for example, if each developer might have a local prospector configuration but that's not guaranteed, then you can inherit from a profile with the ``?`` suffix and if it is not present, prospector will simply carry on. For example:: inherits: - project_config - local_config? In this case, if a developer has a local profile called 'local_config' it would append to the project-wide configuration, but if they don't, prospector won't error with a ``ProfileNotFound`` exception. Note that when using profiles, prospector does not automatically configure ``strictness``. The assumption is that if you provide a profile, you provide all the information about which messages to turn on or off. To keep the strictness functionality, simply inherit from the built-in prospector profiles:: inherits: - strictness_medium The ``inherits`` file can also be in an external package, if you specify a name Prospector will search for a tile named ``prospector.yaml`` or ``prospector.yml`` in the module ``prospector-profile-``. And if the name contains a ``:`` this mean that we use the syntax ``:`` to search the file named ``.yaml`` or ``.yml`` in the module name ``prospector-profile-``. For example:: inherits: - my_module - my_module:my_file .. _ignore-paths: .. _ignore-patterns: Ignoring Paths and patterns ........................... There are two ways to ignore paths or files. Firstly, with the ``ignore-paths`` section. This is a list of paths to ignore relative to the repository root. It can be a directory, in which case the directory contents and all subdirectories are ignored, or it can be a specific file. For example, ``docs`` would ignore a directory in the repository root called "docs", while ``mypackage/vendor`` would ignore anything in the directory at "mypackage/vendor". Secondly, ``ignore-patterns`` is a list of regular expressions. The relative path of files and directories is *searched* for each regular expression, and ignored if any matches are found. If the expression matches a directory, the directory contents and all subdirectories are ignored. For example, ``^example/doc_.*\.py$`` would ignore any files in the "example" directory beginning with "doc\_". Another example: ``(^|/)docs(/|$)`` would ignore all directories called "docs" in the entire repository. Note that a further option called ``ignore`` is available. This is equivalent to ``ignore-patterns``, and is from an older version of the configuration. It will continue working, but it is deprecated, and you should update your profile if you are using it. .. _max-line-length: Max Line Length ............... This general option, provides a way to select maximum line length allowed. .. Note:: This general option overrides and takes precedence over same option in a particular tool (pycodestyle or pylint) Individual Configuration Options -------------------------------- Each tool can be individually configured with a section beginning with the tool name (in lowercase). Valid values are ``bandit``, ``dodgy``, ``frosted``, ``mccabe``, ``mypy``, ``pydocstyle``, ``pycodestyle``, ``pyflakes``, ``pylint``, ``pyright``, ``pyroma``, ``vulture`` and ``ruff``. Enabling and Disabling Tools ............................ There are :doc:`7 default and 5 optional `. Unless otherwise configured, the defaults are enabled and the optional tools are disabled. In a profile, you can enable or disable a tool using the boolean ``run``:: pyroma: run: true Note that the ``--tools`` :doc:`command line argument ` overrides profiles if used. Enabling and Disabling Messages ............................... Messages can be enabled or disabled using the tool's code for the output. These codes are either from the tool itself, or provided by prospector for those tools which do not have message codes. The list of tools and message codes can be found `in the tools package `_. The typical desired action is to disable messages:: pylint: disable: - method-hidden - access-member-before-definition However, you can also enable messages which were disabled by parent profiles:: pylint: enable: - method-hidden - access-member-before-definition Pylint Plugins .............. It is possible to specify list of plugins for Pylint. You can do this by using ``load-plugins`` option in ``pylint`` section:: pylint: load-plugins: - plugin - plugin Note that this option doesn't affect loading of :ref:`autodetected plugins `. PEP8 Control ............ The strictness will turn on or off different messages generated by the `pycodestyle `_ tool depending on how picky they are. However, if you want to have the standard 'medium' strictness but get either complete or zero pep8 style warnings, you can use a shorthand like below:: pep8: full: true Or:: pep8: none: true Note that this section is also the section for configuring the pycodestyle tool, see below. Therefore you can turn on all warnings from pep8 but turn off just one or two individually or otherwise tweak the tool like so:: pycodestyle: full: true disable: - E126 options: max-line-length: 120 Tool Options ............ Some tools can be further configured or tweaked using an options hash:: pycodestyle: options: max-line-length: 120 The available options are: +----------------+------------------------+----------------------------------------------+ | Tool + Option Name + Possible Values | +================+========================+==============================================+ | mccabe | max-complexity | Maximum number of paths allowed in a method | +----------------+------------------------+----------------------------------------------+ | pycodestyle | max-line-length | Maximum line length allowed (This option is | | | | overridden by global option max-line-length_)| +----------------+------------------------+----------------------------------------------+ | pylint | -anything- | Any of the `pylint options`_ | +----------------+------------------------+----------------------------------------------+ | mypy | use-dmypy | Use mypy daemon (mypy server) for faster | | | | checks | +----------------+------------------------+----------------------------------------------+ | mypy | -anything-other- | Any of the `mypy options`_, | | | | if the value is a list of string we it | | | | corresponds to the argument like | | | | `---` | | | | e.g. `disallow: [any-expr, any-explicit]` => | | | | `--disallow-any-expr --disallow-any-explicit`| +----------------+------------------------+----------------------------------------------+ | bandit | config | configuration filename | +----------------+------------------------+----------------------------------------------+ | bandit | profile | profile to use | +----------------+------------------------+----------------------------------------------+ | bandit | severity | report only issues of a given severity | +----------------+------------------------+----------------------------------------------+ | bandit | confidence | report only issues of a given confidence | +----------------+------------------------+----------------------------------------------+ | bandit | -anything-other- | Options pass to Bandit directly | +----------------+------------------------+----------------------------------------------+ | pyright | level | Minimum diagnostic level (error or warning) | +----------------+------------------------+----------------------------------------------+ | pyright | project | Path to location of configuration file | +----------------+------------------------+----------------------------------------------+ | pyright | pythonplatform | Analyze for a specific platform (Darwin, | | | | Linux, Windows) | +----------------+------------------------+----------------------------------------------+ | pyright | pythonversion | Analyze for a specific version | +----------------+------------------------+----------------------------------------------+ | pyright | skipunannotated | Skip analysis of functions with no type | | | | annotations | +----------------+------------------------+----------------------------------------------+ | pyright | typeshed-path | Path to location of typeshed type stubs | +----------------+------------------------+----------------------------------------------+ | pyright | venv-path | Directory that contains virtual environments | +----------------+------------------------+----------------------------------------------+ | ruff | -anything- | Options pass to ruff as argument | | | | `True` => --