deadcode: A Python repository from albertas

Find and Fix Unused Python Code

Installation

pip install deadcode

Usage

To see unused code findings:

deadcode .

To see suggested fixes for all files:

deadcode . --fix --dry

To see suggested fixes only for foo.py file:

deadcode . --fix --dry --only foo.py

To fix:

deadcode . --fix

Tune out some of the false positives, e.g.:

deadcode . --exclude=venv,tests --ignore-names=BaseTestCase,*Mixin --ignore-names-in-files=migrations

The same options can be provided in pyproject.toml settings file:

[tool.deadcode]
exclude = ["venv", "tests"]
ignore-names = ["BaseTestCase", "*Mixin"]
ignore-names-in-files = ["migrations"]

Pre-commit hook

Create a .pre-commit-config.yaml file in the root of your project directory, if it doesn't exist, and add the following to the file:

# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
repos:
  - repo: https://github.com/albertas/deadcode
    rev: 2.4.1
    hooks:
      - id: deadcode

Command line options

Option	Type	Meaning
`--fix`	-	Automatically remove detected unused code expressions from the code base.
`--dry`	-	Show changes which would be made in files.
`--only`	list	Filenames (or path expressions), that will be reflected in the output (and modified if needed).
`--exclude`	list	Filenames (or path expressions), which will be completely skipped without being analysed.
`--ignore-names`	list	Removes provided list of names from the output. Regexp expressions to match multiple names can also be provided, e.g. `*Mixin` will match all classes ending with `Mixin`.
`--ignore-names-in-files`	list	Ignores unused names in files, which filenames match provided path expressions.
`--ignore-names-if-inherits-from`	list	Ignores names of classes, which inherit from provided class names.
`--ignore-names-if-decorated-with`	list	Ignores names of an expression, which is decorated with one of the provided decorator names.
`--ignore-bodies-of`	list	Ignores body of an expression if its name matches any of the provided names.
`--ignore-bodies-if-decorated-with`	list	Ignores body of an expression if its decorated with one of the provided decorator names.
`--ignore-bodies-if-inherits-from`	list	Ignores body of a class if it inherits from any of the provided class names.
`--ignore-definitions`	list	Ignores definition (including name and body) if a name of an expression matches any of the provided ones.
`--ignore-definitions-if-inherits-from`	list	Ignores definition (including name and body) of a class if it inherits from any of the provided class names.
`--ignore-definitions-if-decorated-with`	list	Ignores definition (including name and body) of an expression, which is decorated with any of the provided decorator names.
`--no-color`	-	Removes colors from the output.
`--count`	-	Provides the count of the detected unused names instead of printing them all out.
`--quiet`	-	Does not output anything. Makefile still fails with exit code 1 if unused names are found.

Glossory

name - variable, function or class name.
body - code block which follows after : in function or class definition.
definition - whole class or function definition expression including its name and body.

Rules

Code	Name	Message
DC01	unused-variable	Variable `{name}` is never used
DC02	unused-function	Function `{name}` is never used
DC03	unused-class	Class `{name}` is never used
DC04	unused-method	Method `{name}` is never used
DC05	unused-attribute	Attribute `{name}` is never used
DC06	unused-name	Name `{name}` is never used
DC07	unused-import	Import `{name}` is never used
DC08	unused-property	Property `{name}` is never used
DC09	unreachable-if-block	Unreachable conditional statement block
DC11	empty-file	Empty Python file
DC12	commented-out-code	Commented out code
DC13	unreachable-code	Code after terminal statement, e.g. `return`, `raise`, `continue`, `break`
DC	ignore-expression	Do not show any findings for an expression, which starts on current line (this code can only be used in `# noqa: DC` comments)

Ignoring checks with noqa comments

Inline # noqa comments can be used to ignore deadcode checks. E.g. unused Foo class wont be detected/fixed because # noqa: DC03 comment is used:

class Foo:  # noqa: DC03
    pass

Contributing

make check - runs unit tests and other checks using virtual environment.

Rationale

ruff and flake8 - don't have rules for unused global code detection, only for local ones F823, F841, F842. deadcode package tries to add new DCXXX checks for detecting variables/functions/classes/files which are not used in a whole code base.

deadcode - is supposed to be used inline with other static code checkers like ruff.

There is an alternative vulture package.

Known limitations

In case there are several definitions using the same name - they all wont be reported if at least one usage of that name is being detected.

Files with syntax errors will be ignored, because deadcode uses ast to build abstract syntax tree for name usage detection.

It is assumed that deadcode will be run using the same or higher Python version as the code base is implemented in.

Feature requests

Release notes

v2.4.1:
- Add --version option to show deadcode version.
- Use stdout for deadcode output.
v2.4.0:
- Add --only option that accepts filenames only which will be reflected in the output and modified. This option can be used with --fix and --fix --dry options as well as for simple unused code detection without fixing.
v2.3.2:
- Add pre-commit hook support.
- Drop support for Python 3.8 and 3.9 versions, since their ast implementation is lacking features.
v2.3.1:
- Started analysing files in bytes instead of trying to convert them into UTF-8 encoded strings.
- Improved automatic removal of unused imports.
v2.3.0:
- Add --dry option.
- Update error codes to use DCXX format instead of DCXXX.