Command Line Usage

The simplest way to run prospector is from the project root with no arguments. It will try to figure everything else out itself and provide sensible defaults:

prospector

You can specify a path to check:

prospector path/to/my/package

And you can specify a list of python modules:

prospector module/to/check.py
prospector module/to/check.py other/module/to/check.py something/else.py

See below for a complete list of options and flags. You can also run prospector --help for a full list of options and their effects.

Output Format

The default output format of prospector is designed to be human readable. You can change the output format using the --output-format or -o flags - for example, to get the output in JSON form you can use the --output-format json.

Format Name Notes
emacs
Support for emacs compilation output mode, see issue_16.
vscode
Support for vscode python plugin
grouped
Similar to text, but groups all message on the same line together
rather than having a separate entry per message.
pylint
Produces output in the same style as pylint --parseable. This should
allow prospector to be used as a drop-in replacement for any tools
which parse pylint output. The one minor difference is that the
output includes the name of the tool which generated the error as well
as the error code.
json
Produces a structured, parseable output of the messages and summary. See
below for more information about the structure.
yaml
Same as JSON except produces YAML output.
xunit
Same as JSON except produces xunit compatile XML output.
text
The default output format, a simple human readable format.

If your code uses frameworks and libraries

Often tools such as pylint find errors in code which is not an error, due to attributes of classes being created at run time by a library or framework used by your project. For example, by default, pylint will generate an error for Django models when accessing objects, as the objects attribute is not part of the Model class definition.

Prospector mitigates this by providing an understanding of these frameworks to the underlying tools.

Prospector will try to intuit which libraries your project uses by detecting dependencies <https://github.com/landscapeio/requirements-detector> and automatically turning on support for the requisite libraries. You can see which adaptors were run in the metadata section of the report.

If Prospector does not correctly detect your project’s dependencies, you can specify them manually from the commandline:

prospector --uses django celery flask

Additionally, if Prospector is automatically detecting a library that you do not in fact use, you can turn off autodetection completely:

prospector --no-autodetect

Note that as far as possible, these adaptors have been written as plugins or augmentations for the underlying tools so that they can be used without requiring Prospector. For example, the Django support is available as a pylint plugin. See the “Supported frameworks and libraries” section for more information.

Strictness

Prospector has a configurable ‘strictness’ level which will determine how harshly it searches for errors:

prospector --strictness high

Possible values are verylow, low, medium, high, veryhigh.

Prospector does not include documentation warnings by default, but you can turn this on using the --doc-warnings flag.

All Options

usage: prospector [-h] [-0] [-A] [-u USES] [-B] [--no-common-plugin] [-D] [-T]
                  [-8] [-m] [-F] [--max-line-length MAX_LINE_LENGTH] [-M] [-S]
                  [-o {emacs,grouped,json,pylint,text,vscode,xunit,yaml}]
                  [--absolute-paths] [-t TOOLS] [-w WITH_TOOLS]
                  [-W WITHOUT_TOOLS] [-P PROFILES]
                  [--profile-path PROFILE_PATH]
                  [-s {veryhigh,high,medium,low,verylow}] [--show-profile]
                  [-E] [--pylint-config-file PYLINT_CONFIG_FILE] [-p PATH]
                  [-I IGNORE_PATTERNS] [-i IGNORE_PATHS] [-X]
                  [--include-tool-stdout] [--direct-tool-stdout]
                  [--loquacious-pylint] [--version]
                  [PATH [PATH ...]]
Required Arguments
PATH The path to a Python project to inspect. Defaults to PWD if not specified. If multiple paths are specified, they must all be files (no directories).
Optional Arguments
-0="==SUPPRESS==", --zero-exit="==SUPPRESS=="
 Prospector will exit with a code of 1 (one) if any messages are found. This makes automation easier; if there are any problems at all, the exit code is non-zero. However this behaviour is not always desirable, so if this flag is set, prospector will exit with a code of 0 if it ran successfully, and non-zero if it failed to run.
-A="==SUPPRESS==", --no-autodetect="==SUPPRESS=="
 Turn off auto-detection of frameworks and libraries used. By default, autodetection will be used. To specify manually, see the –uses option.
-u="==SUPPRESS==", --uses="==SUPPRESS=="
 A list of one or more libraries or frameworks that the project uses. Possible values are: django, celery, flask. This will be autodetected by default, but if autodetection doesn’t work, manually specify them using this flag.
-B="==SUPPRESS==", --no-blending="==SUPPRESS=="
 Turn off blending of messages. Prospector will merge together messages from different tools if they represent the same error. Use this option to see all unmerged messages.
--no-common-plugin="==SUPPRESS=="
 Undocumented
-D="==SUPPRESS==", --doc-warnings="==SUPPRESS=="
 Include warnings about documentation.
-T="==SUPPRESS==", --test-warnings="==SUPPRESS=="
 Also check test modules and packages.
-8="==SUPPRESS==", --no-style-warnings="==SUPPRESS=="
 Don’t create any warnings about style. This disables the PEP8 tool and similar checks for formatting.
-m="==SUPPRESS==", --member-warnings="==SUPPRESS=="
 Attempt to warn when code tries to access an attribute of a class or member of a module which does not exist. This is disabled by default as it tends to be quite inaccurate.
-F="==SUPPRESS==", --full-pep8="==SUPPRESS=="
 Enables every PEP8 warning, so that all PEP8 style violations will be reported.
--max-line-length
 The maximum line length allowed. This will be set by the strictness if no value is explicitly specified
-M="==SUPPRESS==", --messages-only="==SUPPRESS=="
 Only output message information (don’t output summary information about the checks)
-S="==SUPPRESS==", --summary-only="==SUPPRESS=="
 Only output summary information about the checks (don’toutput message information)
-o, --output-format
 

The output format. Valid values are: emacs, grouped, json, pylint, text, vscode, xunit, yaml

Possible choices: emacs, grouped, json, pylint, text, vscode, xunit, yaml

--absolute-paths="==SUPPRESS=="
 Whether to output absolute paths when referencing files in messages. By default, paths will be relative to the project path
-t="==SUPPRESS==", --tool="==SUPPRESS=="
 A list of tools to run. This lets you set exactly which tools to run. To add extra tools to the defaults, see –with-tool. Possible values are: dodgy, frosted, mccabe, pep257, pep8, profile-validator, pyflakes, pylint, pyroma, vulture. By default, the following tools will be run: dodgy, mccabe, pep257, pep8, profile-validator, pyflakes, pylint
-w="==SUPPRESS==", --with-tool="==SUPPRESS=="
 A list of tools to run in addition to the default tools. To specify all tools explicitly, use the –tool argument. Possible values are dodgy, frosted, mccabe, pep257, pep8, profile-validator, pyflakes, pylint, pyroma, vulture.
-W="==SUPPRESS==", --without-tool="==SUPPRESS=="
 A list of tools that should not be run. Useful to turn off only a single tool from the defaults. To specify all tools explicitly, use the –tool argument. Possible values are dodgy, frosted, mccabe, pep257, pep8, profile-validator, pyflakes, pylint, pyroma, vulture.
-P="==SUPPRESS==", --profile="==SUPPRESS=="
 The list of profiles to load. A profile is a certain ‘type’ of behaviour for prospector, and is represented by a YAML configuration file. Either a full path to the YAML file describing the profile must be provided, or it must be on the profile path (see –profile-path)
--profile-path="==SUPPRESS=="
 Additional paths to search for profile files. By default this is the path that prospector will check, and a directory called ”.prospector” in the path that prospector will check.
-s, --strictness
 

How strict the checker should be. This affects how harshly the checker will enforce coding guidelines. The default value is “medium”, possible values are “veryhigh”, “high”, “medium”, “low” and “verylow”.

Possible choices: veryhigh, high, medium, low, verylow

--show-profile="==SUPPRESS=="
 Include the computed profile in the summary. This will show what prospector has decided the overall profile is once all profiles have been combined and inherited from. This will produce a large output in most cases so is only useful when trying to debug why prospector is not behaving like you expect.
-E="==SUPPRESS==", --no-external-config="==SUPPRESS=="
 Determines how prospector should behave when configuration already exists for a tool. By default, prospector will use existing configuration. This flag will cause prospector to ignore existing configuration and use its own settings for every tool. Note that prospector will always use its own config for tools which do not have custom configuration.
--pylint-config-file
 The path to a pylintrc file to use to configure pylint. Prospector will find .pylintrc files in the root of the project, but you can use this option to specify manually where it is.
-p, --path The path to a Python project to inspect. Defaults to PWD if not specified. Note: This command line argument is deprecated and will be removed in a future update. Please use the positional PATH argument instead.
-I="==SUPPRESS==", --ignore-patterns="==SUPPRESS=="
 A list of paths to ignore, as a list of regular expressions. Files and folders will be ignored if their full path contains any of these patterns.
-i="==SUPPRESS==", --ignore-paths="==SUPPRESS=="
 A list of file or directory names to ignore. If the complete name matches any of the items in this list, the file or directory (and all subdirectories) will be ignored.
-X="==SUPPRESS==", --die-on-tool-error="==SUPPRESS=="
 If a tool fails to run, prospector will try to carry on. Use this flag to cause prospector to die and raise the exception the tool generated. Mostly useful for development on prospector.
--include-tool-stdout="==SUPPRESS=="
 Undocumented
--direct-tool-stdout="==SUPPRESS=="
 Undocumented
--loquacious-pylint="==SUPPRESS=="
 Deprecated - replaced by –include-tool-stdout
--version="==SUPPRESS=="
 show program’s version number and exit