Metadata-Version: 2.1
Name: deadcode
Version: 2.0.5
Summary: Find and remove dead code.
Project-URL: Homepage, https://github.com/albertas/deadcode
Project-URL: Documentation, https://deadcode.readthedocs.io/
Author-email: Albertas Gimbutas <albertasgim@gmail.com>
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Requires-Dist: tomli==2.0.1
Description-Content-Type: text/markdown

# deadcode
`deadcode` allows to detect and fix unused Python code. It implements `DCXXX`
static code linting rules for detecting unused code such as
variables, functions and classes.

## Installation
```shell
pip install deadcode
```

## Usage
```shell
deadcode .
```

Or with command line options:
```
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"]
```

### Command line options

| Option&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Type | Meaning  |
|--------------------------|------|----------|
|`--fix`                   | -    | Automatically remove detected unused code parts from the code base. |
|`--exclude`               | list | Path expressions to completely skip files from being analysed. |
|`--ignore-names`          | list | Removes provided list of names from the error 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 | Unused names from files matching provided path expressions. |
|`--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. |


## Rules
| Code   | Name               | Message        |
|--------|--------------------|----------------|
| DC001  | unused-variable    | Variable `{name}` is never used
| DC002  | unused-function    | Function `{name}` is never used
| DC003  | unused-class       | Class `{name}` is never used
| DC004  | unused-method      | Method `{name}` is never used
| DC005  | unused-attribute   | Attribute `{name}` is never used
| DC006  | unused-name        | Name `{name}` is never used
| DC007  | unused-import      | Import `{name}` is never used
| DC008  | unused-property    | Property `{name}` is never used
| DC009  | unreachable-code   | Unreachable `else` block
| DC011  | empty-file         | Empty file
| DC012* | commented-out-code | Commented out code
| DC013* | ignore-expression  | *This error code can ony be used in `# noqa: DC013` comments (no errors will be reported for expression which begins in current line)*

`*` - are not yet implemented rules.

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

## Rationale
[ruff](https://pypi.org/project/ruff/) and
[flake8](https://pypi.org/project/flake8/) - don't have rules for unused global
code detection, only for local ones `F823`, `F841`, `F842`. `deadcode` package
tries to add a new `DCXXX` checks for detecting variables/functions/classes
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](https://pypi.org/project/vulture/) package.

## Known limitations
If the same unused name is repeated in several files - it wont be 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
- [x] Replace `.*` with only `*` in regexp matching.
- [x] Add unused class method detection DC310 check.
- [x] Add `--fix` option to automatically remove detected dead code occourencies
- [x] Add a check for empty python files.
- [x] Split error codes into DC010, DC020, DC030 for variables, functions, class.
    - [x] 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
- [ ] Distinguish between definitions with same name, but different files.
