Profiles

The behaviour 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 <https://github.com/landscapeio/prospector/blob/master/prospector/profiles/__init__.py>_) 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.

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

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)?(/|$)

pep8:
  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.

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.

Tweaking Certain Aspects

There are some aspects of analysis which can be turned on or off separately from the strictness or individual tuning of the tools.

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 pep257 tool.

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

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

PEP8 Control

The strictness will turn on or off different messages generated by the pep8.py 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 pep8 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:

pep8:
    full: true
    disable:
        - E126
    options:
        max-line-length: 120

Libraries Used and Autodetect

Prospector will adjust the behaviour 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

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 profile path.

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

Ignoring Paths

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.

Tool Configuration

Each tool can be individually configured with a section beginning with the tool name (in lowercase). Valid values are pylint, pep8, mccabe, dodgy, pyflakes, frosted, vulture and pyroma.

Enabling and Disabling Tools

There are 6 default and 2 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 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

Tool Options

Some tools can be further configured or tweaked using an options hash:

pep8:
  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
pep8 max-line-length Maximum line length allowed
pylint -anything- Any of the pylint options