# Prospector - Python Static Analysis

## About

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, pep8, and McCabe complexity. See the Supported Tools section for a complete list.

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.

## Installation

You can install using `pip`:

    pip install prospector

To install optional dependencies such as `pyroma`:

    pip install prospector[with_pyroma]

For a full list of optional extras, see the page on supported tools.

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 pip 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 usage page.

## 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 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 the profiles documentation page.

## License

Prospector is available under the GPLv2 License.

Contents:

- Command Line Usage
- Profiles
- Error Suppression
- Supported Tools
- Development and Contributing

# Indices and tables

- Index
- Module Index
- Search Page