3. Profiles / Configuration¶
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) 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
prospector --profile my_profile
In general, command-line arguments override and take precedence over values found in profiles.
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.
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
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
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:
Same command line options are available. See Output format
There is a command line argument to tweak how picky Prospector will be:
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:
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
There are some aspects of analysis which can be turned on or off separately from the strictness or individual tuning of the tools. Example:
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
This will turn on the otherwise disabled
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:
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:
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:
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
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 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”.
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¶
This general option, provides a way to select maximum line length allowed.
This general option overrides and takes precedence over same option in a particular tool (pep8 or pylint)
Individual Configuration Options¶
Each tool can be individually configured with a section beginning with the tool name
(in lowercase). Valid values are
Enabling and Disabling Tools¶
There are 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
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
It is possible to specify list of plugins for Pylint. You can do this by using
pylint: load-plugins: - plugin - plugin
Note that this option doesn’t affect loading of autodetected plugins.
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
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
Some tools can be further configured or tweaked using an options hash:
pep8: options: max-line-length: 120
The available options are:
Next is another example using most options:
output-format: json strictness: medium test-warnings: true doc-warnings: false member-warnings: false inherits: - default ignore-paths: - docs ignore-patterns: - (^|/)skip(this)?(/|$) autodetect: true max-line-length: 88 bandit: run: true options: config: .bandit.yml dodgy: run: true frosted: disable: - E103 - E306 mccabe: run: false options: max-complexity: 10 pep8: disable: - W602 - W603 enable: - W601 options: max-line-length: 79 pep257: disable: - D100 - D101 pyflakes: disable: - F403 - F810 pylint: disable: - bad-builtin - too-few-public-methods options: max-locals: 15 max-returns: 6 max-branches: 15 max-statements: 60 max-parents: 7 max-attributes: 7 min-public-methods: 1 max-public-methods: 20 max-module-lines: 1000 max-line-length: 99 pyroma: disable: - PYR15 - PYR18 mypy: run: true options: ignore-missing-imports: true follow-imports: skip vulture: run: true