Package: tidypy
ContentsOverviewFeaturesUsageDockerConfigurationIgnoring IssuesIncluded ToolsIncluded ReportersIncluded IntegrationsExtending TidyPyFAQsContributingLicenseOverviewTidyPy is a tool that encapsulates a number of other static analysis tools and
makes it easy to configure, execute, and review their results.FeaturesIt’s a consolidated tool for performing static analysis on an entire Python
project – not just your*.pysource files. In addition to executing a
number of differenttoolson your code, it can also check your YAML, JSON,
PO, POT, and RST files.Rather than putting yet another specialized configuration file in your
project, TidyPy uses thepyproject.tomlfile defined byPEP 518. All
options for all the tools TidyPy uses are declared in one place, rather than
requiring that you configure each tool in a different way.Honors the pseudo-standard# noqacomment in your Python source to easily
ignore issues reported by any tool.Includes a number ofintegrationsso you can use it with your favorite
toolchain.Includes a variety ofreportersthat allow you to view or use the results
of TidyPy’s analysis in whatever way works best for you.Provides a simple API for you to implement your own tool or reporter and
include it in the analysis of your project.Supports both Python 2 and 3, as well as PyPy. Even runs on Windows.UsageWhen TidyPy is installed (pip install tidypy), thetidypycommand
should become available in your environment:$ tidypy --help
Usage: tidypy [OPTIONS] COMMAND [ARGS]...

  A tool that executes several static analysis tools upon a Python project
  and aggregates the results.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  check               Executes the tools upon the project files.
  default-config      Outputs a default configuration that can be used to
                      bootstrap your own configuration file.
  extensions          Outputs a listing of all available TidyPy extensions.
  install-vcs         Installs TidyPy as a pre-commit hook into the specified
                      VCS.
  list-codes          Outputs a listing of all known issue codes that tools
                      may report.
  purge-config-cache  Deletes the cache of configurations retrieved from
                      outside the primary configuration.
  remove-vcs          Removes the TidyPy pre-commit hook from the specified
                      VCS.To have TidyPy analyze your project, use thechecksubcommand:$ tidypy check --help
Usage: tidypy check [OPTIONS] [PATH]

  Executes the tools upon the project files.

  Accepts one argument, which is the path to the base of the Python project.
  If not specified, defaults to the current working directory.

Options:
  -x, --exclude REGEX             Specifies a regular expression matched
                                  against paths that you want to exclude from
                                  the examination. Can be specified multiple
                                  times. Overrides the expressions specified
                                  in the configuration file.
  -t, --tool [bandit|dlint|eradicate|jsonlint|manifest|mccabe|polint|pycodestyle|pydiatra|pydocstyle|pyflakes|pylint|pyroma|rstlint|secrets|vulture|yamllint]
                                  Specifies the name of a tool to use during
                                  the examination. Can be specified multiple
                                  times. Overrides the configuration file.
  -r, --report [console,csv,custom,json,null,pycodestyle,pylint,pylint-parseable,toml,yaml][:filename]
                                  Specifies the name of a report to execute
                                  after the examination. Can specify an
                                  optional output file name using the form -r
                                  report:filename. If filename is unset, the
                                  report will be written on stdout. Can be
                                  specified multiple times. Overrides the
                                  configuration file.
  -c, --config FILENAME           Specifies the path to the TidyPy
                                  configuration file to use instead of the
                                  configuration found in the project's
                                  pyproject.toml.
  --workers NUM_WORKERS           The number of workers to use to concurrently
                                  execute the tools. Overrides the
                                  configuration file.
  --disable-merge                 Disable the merging of issues from various
                                  tools when TidyPy considers them equivalent.
                                  Overrides the configuration file.
  --disable-progress              Disable the display of the progress bar.
  --disable-noqa                  Disable the ability to ignore issues using
                                  the "# noqa" comment in Python files.
  --disable-config-cache          Disable the use of the cache when retrieving
                                  configurations referenced by the "extends"
                                  option.
  --help                          Show this message and exit.If you need to generate a skeleton configuration file with the default options,
use thedefault-configsubcommand:$ tidypy default-config --help
Usage: tidypy default-config [OPTIONS]

  Outputs a default configuration that can be used to bootstrap your own
  configuration file.

Options:
  --pyproject  Output the config so that it can be used in a pyproject.toml
               file.
  --help       Show this message and exit.If you’d like to see a list of the possible issue codes that could be returned,
use thelist-codessubcommand:$ tidypy list-codes --help
Usage: tidypy list-codes [OPTIONS]

  Outputs a listing of all known issue codes that tools may report.

Options:
  -t, --tool [bandit|dlint|eradicate|jsonlint|manifest|mccabe|polint|pycodestyle|pydiatra|pydocstyle|pyflakes|pylint|pyroma|rstlint|secrets|vulture|yamllint]
                                  Specifies the name of a tool whose codes
                                  should be output. If not specified, defaults
                                  to all tools.
  -f, --format [toml|json|yaml|csv]
                                  Specifies the format in which the tools
                                  should be output. If not specified, defaults
                                  to TOML.
  --help                          Show this message and exit.If you want to install or remove TidyPy as a pre-commit hook in your project’s
VCS, use theinstall-vcs/remove-vcssubcommands:$ tidypy install-vcs --help
Usage: tidypy install-vcs [OPTIONS] VCS [PATH]

  Installs TidyPy as a pre-commit hook into the specified VCS.

  Accepts two arguments:

    VCS: The version control system to install the hook into. Choose from:
    git, hg

    PATH: The path to the base of the repository to install the hook into.
    If not specified, defaults to the current working directory.

Options:
  --strict  Whether or not the hook should prevent the commit if TidyPy finds
            issues.
  --help    Show this message and exit.

$ tidypy remove-vcs --help
Usage: tidypy remove-vcs [OPTIONS] VCS [PATH]

  Removes the TidyPy pre-commit hook from the specified VCS.

  Accepts two arguments:

    VCS: The version control system to remove the hook from. Choose from:
    git, hg

    PATH: The path to the base of the repository to remove the hook from. If
    not specified, defaults to the current working directory.

Options:
  --help  Show this message and exit.If you’d like to enable bash completion for TidyPy, run the following in your
shell (or put it in your bash startup scripts):$ eval "$(_TIDYPY_COMPLETE=source tidypy)"DockerIf you don’t want to install TidyPy locally on your system or in your
virtualenv, you can use thepublished Dockerimage:$ docker run --rm --tty --volume=`pwd`:/project tidypy/tidypyThe command above will runtidypy checkon the contents of the current
directory. If you want to run it on a different directory, then change the`pwd`to whatever path you need (the goal being to mount your project
directory to the container’s/projectvolume).Running TidyPy in this manner has a few limitiations, mostly around the fact
that since TidyPy is running in its own, isolated Python environment, tools
like pylint won’t be able to introspect the packages your project installed
locally, so it may report false positives around “import-error”,
“no-name-in-module”, “no-member”, etc.If you want to run a command other thancheck, just pass that along when
you invoke docker:$ docker run --rm --tty --volume=`pwd`:/project tidypy/tidypy tidypy list-codesConfigurationTODOIgnoring IssuesIn addition to ignoring entire files, tools, or specific issue types from tools
via your configuration file, you can also use comments in your Python source
files to ignore issues on specific lines. Some tools have their own built-in
support and notation for doing this:pylint will respectcomments that look like:# pylintbandit will respectcomments that look like:# nosecpycodestyle will respectcomments that look like:# noqapydocstyle will also respectcomments that look like:# noqadetect-secrets will respectcomments that look like:# pragma: whitelist secretTidyPy goes beyond these tool-specific flags to implement# noqaon a
global scale for Python source files. It will ignore issues for lines that have
the# noqacomment, regardless of what tools raise the issues. If you only
want to ignore a particular type of issue on a line, you can use syntax like
the following:# noqa: CODE1,CODE2Or, if a particular code is used in multiple tools, you can specify the exact
tool in the comment:# noqa: pycodestyle:CODE1,pylint:CODE2Or, if you want to ignore any issue a specific tool raises on a line, you can
specify the tool:# noqa: @pycodestyle,@pylintYou can, of course, mix and match all three notations in a single comment if
you need to:# noqa: CODE1,pylint:CODE2,@pycodestyleYou can disable TidyPy’s NOQA behavior by specifying the--disable-noqaoption on the command line, or by setting thenoqaoption tofalsein
your configuration file. A caveat, though: currently pycodestyle and pydocstyle
do not respect this option and will always honor any# noqacomments they
find.Included ToolsOut of the box, TidyPy includes support for a number of tools:pylintPylintis a Python source code analyzer which looks for programming
errors, helps enforcing a coding standard and sniffs for some code smells.pycodestylepycodestyleis a tool to check your Python code against some of the
style conventions inPEP 8.pydocstylepydocstyleis a static analysis tool for checking compliance with Python
docstring conventions (e.g.,PEP 257).pyromaPyromatests your project’s packaging friendliness.vultureVulturefinds unused code in Python programs.banditBanditis a security linter for Python source code.eradicateEradicatefinds commented-out code in Python files.pyflakesPyflakesis a simple program which checks Python source files for
errors.mccabeNed Batchelder’s script to check theMcCabecyclomatic complexity of
Python code.jsonlintA part of thedemjsonpackage, this tool validates your JSON documents
for strict conformance to the JSON specification, and to detect potential
data portability issues.yamllintTheyamllinttool, as its name implies, is a linter for YAML files.rstlintTherestructuredtext-linttool, as its name implies, is a linter for
reStructuredText files.polintA part of thedennispackage, this tool lints PO and POT files for
problems.manifestUses thecheck-manifestscript to detect discrepancies or problems with
your project’s MANIFEST.in file.pydiatrapydiatrais yet another static checker for Python code.secretsThedetect-secretstool attempts to find secrets (keys, passwords, etc)
within a code base.dlintDlintis a tool for encouraging best coding practices and helping ensure
we’re writing secure Python code.Included ReportersTidyPy includes a number of different methods to present and/or export the
results of the analysis of a project. Out of the box, it provides the
following:consoleThe default reporter. Prints a colored report to the console that groups
issues by the file they were found in.pylintPrints a report to the console that is in the same format asPylint’s
default output.pylint-parseablePrints a report to the console that is in roughly the same format asPylint’s “parseable” output.pycodestylePrints a report to the console that is in the same format aspycodestyle’s default output.jsonGenerates a JSON-serialized object that contains the results of the
analysis.yamlGenerates a YAML-serialized object that contains the results of the
analysis.tomlGenerates a TOML-serialized object that contains the results of the
analysis.csvGenerates a set of CSV records that contains the results of the analysis.customPrints ouput to the console that is in the format defined by a template
string specified in the project configuration. The template string is
expected to be one allowed by thestr.format()Python method. It will
receive the following arguments:filename,line,character,tool,code,message.Included IntegrationsTidyPy includes a handful of plugins/integrations that hook it into other
tools.pytestTidyPy can be run during execution of yourpytesttest suite. To enable
it, you need to specify--tidypyon the command line when you run
pytest, or include it as part of theaddoptsproperty in your pytest
config.noseTidyPy can be run during execution of yournosetest suite. To enable
it, you can either specify--with-tidypyon the command line when you
run nose, or set thewith-tidypyproperty to1in yoursetup.cfg.pbbtTidyPy can be included in yourPBBTscripts using thetidypytest.
To enable it, you can either specify--extend=tidypy.plugin.pbbton the
command line when you run PBBT, or set theextendproperty in yoursetup.cfgorpbbt.yamltotidypy.plugin.pbbt.Extending TidyPyA simple interface exists for extending TidyPy to include more and different
tools and reporters. To add a tool, create a class that extendstidypy.Tool,
and in yoursetup.py, declare anentry_pointfortidypy.toolsthat
points to your class:entry_points={
    'tidypy.tools': [
        'mycooltool = path.to.model:MyCoolToolClassName',
    ],
}To add a reporter, the process is nearly identical, except that you extendtidypy.Reportand declare anentry_pointfortidypy.reports.FAQsAren’t there already tools like this?Yup. There’sprospector,pylama,flake8, andciocheckjust to
name a few. But, as is customary in the world of software development, if
the wheel isn’t as round as you’d like it to be, you must spend countless
hours to reinvent it. I’ve tried a number of these tools (and even
contributed to some), but in the end, I always found something lacking or
annoying. Thus, TidyPy was born.How do I run TidyPy on a single file?The short answer is, you don’t (at the moment, anyway). It wasn’t designed
with that use case in mind. TidyPy was built to analyze a whole project,
and show you everything.I tried TidyPy out on my project and it reported hundreds/thousands of issues. My ego is now bruised.Yea, that happens. The philosophy I chose to follow with this tool is that
I didn’t want it to hide anything from me. I wanted its default behavior to
execute every tool in its suite using their most obnoxious setting. Then,
when I can see the full scope of damage, I can then decide to disable
specific tools or issues via a project-level configuration. I figured if
someone took the time to implement a check for a particular issue, they
must think it has some value. If my tooling hides that from me by default,
then I won’t be able to gain any benefits from it.In general, I don’t recommend starting to use linters or other sorts of
static analyzers when you think you’re “done”. You should incorporate them
into your workflow right at the beginning of a project – just as you would
(or should) your unit tests. That way you find things early and learn from
them (or disable them). It’s much less daunting a task to deal with when
you address them incrementally.ContributingContributions are most welcome. Particularly if they’re bug fixes! To hack on
this code, simply clone it, and then runmake setup. This will create a
virtualenv with all the tools you’ll need. TheMakefilealso has atesttarget for running the pytest suite, and alinttarget for running TidyPy
on itself.LicenseTidyPy is released under the terms of theMIT License.