lapsed 2.7.0

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"]

If your project uses Tach to declare module boundaries, deadcode can read one or more tach.toml files and treat names exposed through [[interfaces]] as intentional public API (never reported as unused, the same way __all__ is treated), and skip files that belong to a module marked unchecked = true:

deadcode . --tach-config tach.toml

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.7.0
    hooks:
      - id: deadcode

Command line options

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

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

• Replace .* with only * in regexp matching.
• Add unused class method detection DC04 check.
• Add --fix option to automatically remove detected dead code occourencies
• Add a check for empty python files.
• Split error codes into DC01, DC02, DC03 for variables, functions, class.
  • Should have different codes for ignoring name and ignoring whole definition (reserved DCxx0 - ignore name, DCxx1 - ignore definition).
  • Allow to disable each check separately using:
    • inline comment.
    • pyproject.toml file
• Add a check for code in comments.
• Add target python version option, if specified it will be used for code base check.
• Add a --depth parameter to ignore nested code.. (To only check global scope use 0).
• Add options:
  • --ignore-definitions
  • --ignore-definitions-if-inherits-from
  • --ignore-definitions-if-decorated-with
  • --ignore-names-if-inherits-from
  • --ignore-names-if-decorated-with
  • --ignore-bodies-of
  • --ignore-bodies-if-decorated-with
  • --ignore-bodies-if-inherits-from
  • --ignore-definitions
  • --ignore-definitions-if-inherits-from
  • --ignore-definitions-if-decorated-with
    • Question: would it be possible to ignore only certain types of checks for a body, e.g. only variable attributes of TypedDict and still check usage of methods and properties?
    • What expression would allow this type of precission?
• Distinguish between definitions with same name, but different files.
• Repeated application of deadcode till the output stops changing.
• Unreachable code detection and fixing: this should only be scoped for if statements and only limited to primitive variables.
• Benchmarking performance with larger projects (time, CPU and memory consumption) in order to optimize.
• --fix could accept a list of filenames as well (only those files would be changed, but the summary could would be full). (This might be confusing, because filenames, which have to be considered are provided without any flag, --fix is expected to not accept arguments)
• pre-commit-hook.
• language server.
• DC10: remove code after terminal statements like raise, return, break, continue and comes in the same scope.
• Add ignore and per-file-ignores command line and pyproject.toml options, which allows to skip some rules.
• Make sure that all rules are being skipped by noqa comment and all rules react to noqa: rule_id comments.
• Include package names into code item scope (dot-separated path), e.g. "package1.package2.module.class.method.variable".
• All options should be able to accept dot-separated path or a generic name, e.g. "marshmallow.Schema" vs "Schema", documentation should cleary demonstrate the behaviour/example that "Schema" means "*.Schema".
• Redefinition of an existing name makes previous name unreachable, unless it is assigned somehow.
• Check if file is still valid/parsable after automatic fixing, if not: halt the change and report error.
• Investigate ways of extracting and backporting Python3.10+ ast implementation to lower Python versions.

Release notes

• v2.7.0:
  • Treat pytest_* functions defined in conftest.py (e.g. pytest_configure, pytest_collection_modifyitems, pytest_addoption) as pytest hooks, which pytest calls automatically by name, and never report them as unused.
  • Treat methods decorated with @typing.override (or @typing_extensions.override) as used, since they are called via the base class they override, not by their own name.
• v2.6.0:
  • Add --ignore-class-attributes option to not report unused attributes assigned directly in a class body (e.g. THING = "blah" inside class Foo:), since such attributes may control behaviour of inherited/overridden methods, external frameworks, or metaclasses.
• v2.5.0:
  • Add --ignore-non-self-attributes option to not report unused attributes assigned on objects other than self (e.g. foo.bar = 1), since such assignments may have side effects or be consumed by code outside of the analysed files.
• v2.4.2:
  • Add --tach-config option to read tach.toml file(s) and treat names exposed via [[interfaces]] as public API, and skip unchecked = true modules entirely.
• 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.