diff options
| author | CoprDistGit <infra@openeuler.org> | 2023-03-09 18:02:05 +0000 |
|---|---|---|
| committer | CoprDistGit <infra@openeuler.org> | 2023-03-09 18:02:05 +0000 |
| commit | e64b6fe4bb5ed95d364f644c7fe6824310d38036 (patch) | |
| tree | 6acb0379dfb376edfa05eda9649472a4f93ff9a5 | |
| parent | 42a6a22f4bfa4bcfc9acd151c96a40e71a29ac27 (diff) | |
automatic import of python-vulture
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | python-vulture.spec | 2023 | ||||
| -rw-r--r-- | sources | 1 |
3 files changed, 2025 insertions, 0 deletions
@@ -0,0 +1 @@ +/vulture-2.7.tar.gz diff --git a/python-vulture.spec b/python-vulture.spec new file mode 100644 index 0000000..e76a1ec --- /dev/null +++ b/python-vulture.spec @@ -0,0 +1,2023 @@ +%global _empty_manifest_terminate_build 0 +Name: python-vulture +Version: 2.7 +Release: 1 +Summary: Find dead code +License: MIT +URL: https://github.com/jendrikseipp/vulture +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/de/ff/196ca63becc5faf5586202ab6e30102322adeea538bb45549d97ed38225d/vulture-2.7.tar.gz +BuildArch: noarch + +Requires: python3-toml + +%description +# Vulture - Find dead code + + +[](https://codecov.io/gh/jendrikseipp/vulture?branch=main) + +Vulture finds unused code in Python programs. This is useful for +cleaning up and finding errors in large code bases. If you run Vulture +on both your library and test suite you can find untested code. + +Due to Python's dynamic nature, static code analyzers like Vulture are +likely to miss some dead code. Also, code that is only called implicitly +may be reported as unused. Nonetheless, Vulture can be a very helpful +tool for higher code quality. + +## Features + +* fast: uses static code analysis +* tested: tests itself and has complete test coverage +* complements pyflakes and has the same output syntax +* sorts unused classes and functions by size with `--sort-by-size` +* supports Python \>= 3.6 + +## Installation + + $ pip install vulture + +## Usage + + $ vulture myscript.py # or + $ python3 -m vulture myscript.py + $ vulture myscript.py mypackage/ + $ vulture myscript.py --min-confidence 100 # Only report 100% dead code. + +The provided arguments may be Python files or directories. For each +directory Vulture analyzes all contained +<span class="title-ref">\*.py</span> files. + +After you have found and deleted dead code, run Vulture again, because +it may discover more dead code. + +## Types of unused code + +In addition to finding unused functions, classes, etc., Vulture can detect +unreachable code. Each chunk of dead code is assigned a *confidence value* +between 60% and 100%, where a value of 100% signals that it is certain that the +code won't be executed. Values below 100% are *very rough* estimates (based on +the type of code chunk) for how likely it is that the code is unused. + +| Code type | Confidence value | +| ------------------- | -- | +| function/method/class argument, unreachable code | 100% | +| import | 90% | +| attribute, class, function, method, property, variable | 60% | + +You can use the `--min-confidence` flag to set the minimum confidence +for code to be reported as unused. Use `--min-confidence 100` to only +report code that is guaranteed to be unused within the analyzed files. + +## Handling false positives + +When Vulture incorrectly reports chunks of code as unused, you have +several options for suppressing the false positives. If fixing your false +positives could benefit other users as well, please file an issue report. + +#### Whitelists + +The recommended option is to add used code that is reported as unused to a +Python module and add it to the list of scanned paths. To obtain such a +whitelist automatically, pass `--make-whitelist` to Vulture: + + $ vulture mydir --make-whitelist > whitelist.py + $ vulture mydir whitelist.py + +Note that the resulting `whitelist.py` file will contain valid Python +syntax, but for Python to be able to *run* it, you will usually have to +make some modifications. + +We collect whitelists for common Python modules and packages in +`vulture/whitelists/` (pull requests are welcome). + +#### Ignoring files + +If you want to ignore a whole file or directory, use the `--exclude` parameter +(e.g., `--exclude "*settings.py,*/docs/*.py,*/test_*.py,*/.venv/*.py"`). The +exclude patterns are matched against absolute paths. + +#### Flake8 noqa comments + +<!-- Hide noqa docs until we decide whether we want to support it. +Another way of ignoring errors is to annotate the line causing the false +positive with `# noqa: <ERROR_CODE>` in a trailing comment (e.g., `# +noqa: V103`). The `ERROR_CODE` specifies what kind of dead code to +ignore (see the table below for the list of error codes). In case no +error code is specified, Vulture ignores all results for the line. +(Note that the line number for decorated objects is the line number of +the first decorator.) +--> + +For compatibility with [flake8](https://flake8.pycqa.org/), Vulture +supports the [F401 and +F841](https://flake8.pycqa.org/en/latest/user/error-codes.html) error +codes for ignoring unused imports (`# noqa: F401`) and unused local +variables (`# noqa: F841`). However, we recommend using whitelists instead +of `noqa` comments, since `noqa` comments add visual noise to the code and +make it harder to read. + +#### Ignoring names + +You can use `--ignore-names foo*,ba[rz]` to let Vulture ignore all names +starting with `foo` and the names `bar` and `baz`. Additionally, the +`--ignore-decorators` option can be used to ignore functions decorated +with the given decorator. This is helpful for example in Flask projects, +where you can use `--ignore-decorators "@app.route"` to ignore all +functions with the `@app.route` decorator. + +We recommend using whitelists instead of `--ignore-names` or +`--ignore-decorators` whenever possible, since whitelists are +automatically checked for syntactic correctness when passed to Vulture +and often you can even pass them to your Python interpreter and let it +check that all whitelisted code actually still exists in your project. + +#### Marking unused variables + +There are situations where you can't just remove unused variables, e.g., +in function signatures. The recommended solution is to use the `del` +keyword as described in the +[PyLint manual](http://pylint-messages.wikidot.com/messages:w0613) and on +[StackOverflow](https://stackoverflow.com/a/14836005): + +```python +def foo(x, y): + del y + return x + 3 +``` + +Vulture will also ignore all variables that start with an underscore, so +you can use `_x, y = get_pos()` to mark unused tuple assignments or +function arguments, e.g., `def foo(x, _y)`. + +#### Minimum confidence + +Raise the minimum [confidence value](#types-of-unused-code) with the `--min-confidence` flag. + +#### Unreachable code + +If Vulture complains about code like `if False:`, you can use a Boolean +flag `debug = False` and write `if debug:` instead. This makes the code +more readable and silences Vulture. + +#### Forward references for type annotations + +See [#216](https://github.com/jendrikseipp/vulture/issues/216). For +example, instead of `def foo(arg: "Sequence"): ...`, we recommend using + +``` python +from __future__ import annotations + +def foo(arg: Sequence): + ... +``` + +if you're using Python 3.7+. + + +## Configuration + +You can also store command line arguments in `pyproject.toml` under the +`tool.vulture` section. Simply remove leading dashes and replace all +remaining dashes with underscores. + +Options given on the command line have precedence over options in +`pyproject.toml`. + +Example Config: + +``` toml +[tool.vulture] +exclude = ["*file*.py", "dir/"] +ignore_decorators = ["@app.route", "@require_*"] +ignore_names = ["visit_*", "do_*"] +make_whitelist = true +min_confidence = 80 +paths = ["myscript.py", "mydir"] +sort_by_size = true +verbose = true +``` + +## Version control integration + +You can use a [pre-commit](https://pre-commit.com/#install) hook to run +Vulture before each commit. For this, install pre-commit and add the +following to the `.pre-commit-config.yaml` file in your repository: + +```yaml +repos: + - repo: https://github.com/jendrikseipp/vulture + rev: 'v2.3' # or any later Vulture version + hooks: + - id: vulture +``` + +Then run `pre-commit install`. Finally, create a `pyproject.toml` file +in your repository and specify all files that Vulture should check under +`[tool.vulture] --> paths` (see above). + +## How does it work? + +Vulture uses the `ast` module to build abstract syntax trees for all +given files. While traversing all syntax trees it records the names of +defined and used objects. Afterwards, it reports the objects which have +been defined, but not used. This analysis ignores scopes and only takes +object names into account. + +Vulture also detects unreachable code by looking for code after +`return`, `break`, `continue` and `raise` statements, and by searching +for unsatisfiable `if`- and `while`-conditions. + +## Sort by size + +When using the `--sort-by-size` option, Vulture sorts unused code by its +number of lines. This helps developers prioritize where to look for dead +code first. + +## Examples + +Consider the following Python script (`dead_code.py`): + +``` python +import os + +class Greeter: + def greet(self): + print("Hi") + +def hello_world(): + message = "Hello, world!" + greeter = Greeter() + func_name = "greet" + greet_func = getattr(greeter, func_name) + greet_func() + +if __name__ == "__main__": + hello_world() +``` + +Calling : + + $ vulture dead_code.py + +results in the following output: + + dead_code.py:1: unused import 'os' (90% confidence) + dead_code.py:4: unused function 'greet' (60% confidence) + dead_code.py:8: unused variable 'message' (60% confidence) + +Vulture correctly reports `os` and `message` as unused but it fails to +detect that `greet` is actually used. The recommended method to deal +with false positives like this is to create a whitelist Python file. + +**Preparing whitelists** + +In a whitelist we simulate the usage of variables, attributes, etc. For +the program above, a whitelist could look as follows: + +``` python +# whitelist_dead_code.py +from dead_code import Greeter +Greeter.greet +``` + +Alternatively, you can pass `--make-whitelist` to Vulture and obtain an +automatically generated whitelist. + +Passing both the original program and the whitelist to Vulture + + $ vulture dead_code.py whitelist_dead_code.py + +makes Vulture ignore the `greet` method: + + dead_code.py:1: unused import 'os' (90% confidence) + dead_code.py:8: unused variable 'message' (60% confidence) + +<!-- Hide noqa docs until we decide whether we want to support it. +**Using "# noqa"** + +```python +import os # noqa + +class Greeter: # noqa: V102 + def greet(self): # noqa: V103 + print("Hi") +``` + +## Error codes + +For compatibility with [flake8](https://flake8.pycqa.org/), Vulture +supports the [F401 and +F841](https://flake8.pycqa.org/en/latest/user/error-codes.html) error +codes. + +| Error codes | Description | +| ----------- | ----------------- | +| V101 | Unused attribute | +| V102 | Unused class | +| V103 | Unused function | +| V104, F401 | Unused import | +| V105 | Unused property | +| V106 | Unused method | +| V107, F841 | Unused variable | +| V201 | Unreachable code | + +--> + +## Exit codes + +| Exit code | Description | +| --------- | ------------------------------------------------------------- | +| 0 | No dead code found | +| 1 | Dead code found | +| 1 | Invalid input (file missing, syntax error, wrong encoding) | +| 2 | Invalid command line arguments | + +## Similar programs + + - [pyflakes](https://pypi.org/project/pyflakes/) finds unused imports + and unused local variables (in addition to many other programmatic + errors). + - [coverage](https://pypi.org/project/coverage/) finds unused code + more reliably than Vulture, but requires all branches of the code to + actually be run. + - [uncalled](https://pypi.org/project/uncalled/) finds dead code by + using the abstract syntax tree (like Vulture), regular expressions, + or both. + - [dead](https://pypi.org/project/dead/) finds dead code by using the + abstract syntax tree (like Vulture). + +## Participate + +Please visit <https://github.com/jendrikseipp/vulture> to report any +issues or to make pull requests. + + - Contributing guide: + [CONTRIBUTING.md](https://github.com/jendrikseipp/vulture/blob/main/CONTRIBUTING.md) + - Release notes: + [CHANGELOG.md](https://github.com/jendrikseipp/vulture/blob/main/CHANGELOG.md) + - Roadmap: + [TODO.md](https://github.com/jendrikseipp/vulture/blob/main/TODO.md) + + +# 2.7 (2023-01-08) + +* Ignore `setup_module()`, `teardown_module()`, etc. in pytest `test_*.py` files (Jendrik Seipp). +* Add whitelist for `socketserver.TCPServer.allow_reuse_address` (Ben Elliston). +* Clarify that `--exclude` patterns are matched against absolute paths (Jendrik Seipp, #260). +* Fix example in README file (Jendrik Seipp, #272). + +# 2.6 (2022-09-19) + +* Add basic `match` statement support (kreathon, #276, #291). + +# 2.5 (2022-07-03) + +* Mark imports in `__all__` as used (kreathon, #172, #282). +* Add whitelist for `pint.UnitRegistry.default_formatter` (Ben Elliston, #258). + +# 2.4 (2022-05-19) + +* Print absolute filepaths as relative again (as in version 2.1 and before) + if they are below the current directory (The-Compiler, #246). +* Run tests and add PyPI trove for Python 3.10 (chayim, #266). +* Allow using the `del` keyword to mark unused variables (sshishov, #279). + +# 2.3 (2021-01-16) + +* Add [pre-commit](https://pre-commit.com) hook (Clément Robert, #244). + +# 2.2 (2021-01-15) + +* Only parse format strings when being used with `locals()` (jingw, #225). +* Don't override paths in pyproject.toml with empty CLI paths (bcbnz, #228). +* Run continuous integration tests for Python 3.9 (ju-sh, #232). +* Use pathlib internally (ju-sh, #226). + +# 2.1 (2020-08-19) + +* Treat `getattr/hasattr(obj, "constant_string", ...)` as a reference to + `obj.constant_string` (jingw, #219). +* Fix false positives when assigning to `x.some_name` but reading via + `some_name`, at the cost of potential false negatives (jingw, #221). +* Allow reading options from `pyproject.toml` (Michel Albert, #164, #215). + +# 2.0 (2020-08-11) + +* Parse `# type: ...` comments if on Python 3.8+ (jingw, #220). +* Bump minimum Python version to 3.6 (Jendrik Seipp, #218). The last + Vulture release that supports Python 2.7 and Python 3.5 is version 1.6. +* Consider all files under `test` or `tests` directories test files + (Jendrik Seipp). +* Ignore `logging.Logger.propagate` attribute (Jendrik Seipp). + +# 1.6 (2020-07-28) + +* Differentiate between functions and methods (Jendrik Seipp, #112, #209). +* Move from Travis to GitHub actions (RJ722, #211). + +# 1.5 (2020-05-24) + +* Support flake8 "noqa" error codes F401 (unused import) and F841 (unused + local variable) (RJ722, #195). +* Detect unreachable code in conditional expressions + (Agathiyan Bragadeesh, #178). + +# 1.4 (2020-03-30) + +* Ignore unused import statements in `__init__.py` (RJ722, #192). +* Report first decorator's line number for unused decorated objects on + Python 3.8+ (RJ722, #200). +* Check code with black and pyupgrade. + +# 1.3 (2020-02-03) + +* Detect redundant 'if' conditions without 'else' blocks. +* Add whitelist for `string.Formatter` (Joseph Bylund, #183). + +# 1.2 (2019-11-22) + +* Fix tests for Python 3.8 (#166). +* Use new `Constant` AST node under Python 3.8+ (#175). +* Add test for f-strings (#177). +* Add whitelist for `logging` module. + +# 1.1 (2019-09-23) + +* Add `sys.excepthook` to `sys` whitelist. +* Add whitelist for `ctypes` module. +* Check that type annotations are parsed and type comments are ignored + (thanks @kx-chen). +* Support checking files with BOM under Python 2.7 (#170). + +# 1.0 (2018-10-23) + +* Add `--ignore-decorators` flag (thanks @RJ722). +* Add whitelist for `threading` module (thanks @andrewhalle). + +# 0.29 (2018-07-31) + +* Add `--ignore-names` flag for ignoring names matching the given glob + patterns (thanks @RJ722). + +# 0.28 (2018-07-05) + +* Add `--make-whitelist` flag for reporting output in whitelist format + (thanks @RJ722). +* Ignore case of `--exclude` arguments on Windows. +* Add `*-test.py` to recognized test file patterns. +* Add `failureException`, `longMessage` and `maxDiff` to `unittest` + whitelist. +* Refer to actual objects rather than their mocks in default + whitelists (thanks @RJ722). +* Don't import any Vulture modules in setup.py (thanks @RJ722). + +# 0.27 (2018-06-05) + +* Report `while (True): ... else: ...` as unreachable (thanks @RJ722). +* Use `argparse` instead of `optparse`. +* Whitelist Mock.return\_value and Mock.side\_effect in unittest.mock + module. +* Drop support for Python 2.6 and 3.3. +* Improve documentation and test coverage (thanks @RJ722). + +# 0.26 (2017-08-28) + +* Detect `async` function definitions (thanks @RJ722). +* Add `Item.get_report()` method (thanks @RJ722). +* Move method for finding Python modules out of Vulture class. + +# 0.25 (2017-08-15) + +* Detect unsatisfiable statements containing `and`, `or` and `not`. +* Use filenames and line numbers as tie-breakers when sorting by size. +* Store first and last line numbers in Item objects. +* Pass relevant options directly to `scavenge()` and `report()`. + +# 0.24 (2017-08-14) + +* Detect unsatisfiable `while`-conditions (thanks @RJ722). +* Detect unsatisfiable `if`- and `else`-conditions (thanks @RJ722). +* Handle null bytes in source code. + +# 0.23 (2017-08-10) + +* Add `--min-confidence` flag (thanks @RJ722). + +# 0.22 (2017-08-04) + +* Detect unreachable code after `return`, `break`, `continue` and + `raise` (thanks @RJ722). +* Parse all variable and attribute names in new format strings. +* Extend ast whitelist. + +# 0.21 (2017-07-26) + +* If an unused item is defined multiple times, report it multiple + times. +* Make size estimates for function calls more accurate. +* Create wheel files for Vulture (thanks @RJ722). + +# 0.20 (2017-07-26) + +* Report unused tuple assignments as dead code. +* Report attribute names that have the same names as variables as dead + code. +* Let Item class inherit from `object` (thanks @RJ722). +* Handle names imported as aliases like all other used variable names. +* Rename Vulture.used\_vars to Vulture.used\_names. +* Use function for determining which imports to ignore. +* Only try to import each whitelist file once. +* Store used names and used attributes in sets instead of lists. +* Fix estimating the size of code containing ellipses (...). +* Refactor and simplify code. + +# 0.19 (2017-07-20) + +* Don't ignore <span class="title-ref">\_\_foo</span> variable names. +* Use separate methods for determining whether to ignore classes and + functions. +* Only try to find a whitelist for each defined import once (thanks + @roivanov). +* Fix finding the last child for many types of AST nodes. + +# 0.18 (2017-07-17) + +* Make <span class="title-ref">--sort-by-size</span> faster and more + accurate (thanks @RJ722). + +# 0.17 (2017-07-17) + +* Add <span class="title-ref">get\_unused\_code()</span> method. +* Return with exit code 1 when syntax errors are found or files can't + be read. + +# 0.16 (2017-07-12) + +* Differentiate between unused classes and functions (thanks @RJ722). +* Add --sort-by-size option (thanks @jackric and @RJ722). +* Count imports as used if they are accessed as module attributes. + +# 0.15 (2017-07-04) + +* Automatically include whitelists based on imported modules (thanks + @RJ722). +* Add --version parameter (thanks @RJ722). +* Add appveyor tests for testing on Windows (thanks @RJ722). + +# 0.14 (2017-04-06) + +* Add stub whitelist file for Python standard library (thanks @RJ722) +* Ignore class names starting with "Test" in "test\_" files (thanks + @thisch). +* Ignore "test\_" functions only in "test\_" files. + +# 0.13 (2017-03-06) + +* Ignore star-imported names since we cannot detect whether they are + used. +* Move repository to GitHub. + +# 0.12 (2017-01-05) + +* Detect unused imports. +* Use tokenize.open() on Python \>= 3.2 for reading input files, + assume UTF-8 encoding on older Python versions. + +# 0.11 (2016-11-27) + +* Use the system's default encoding when reading files. +* Report syntax errors instead of aborting. + +# 0.10 (2016-07-14) + +* Detect unused function and method arguments (issue #15). +* Detect unused \*args and \*\*kwargs parameters. +* Change license from GPL to MIT. + +# 0.9 (2016-06-29) + +* Don't flag attributes as unused if they are used as global variables + in another module (thanks Florian Bruhin). +* Don't consider "True" and "False" variable names. +* Abort with error message when invoked on .pyc files. + +# 0.8.1 (2015-09-28) + +* Fix code for Python 3. + +# 0.8 (2015-09-28) + +* Do not flag names imported with "import as" as dead code (thanks Tom + Terrace). + +# 0.7 (2015-09-26) + +* Exit with exitcode 1 if path on commandline can't be found. +* Test vulture with vulture using a whitelist module for false + positives. +* Add tests that run vulture as a script. +* Add "python setup.py test" command for running tests. +* Add support for tox. +* Raise test coverage to 100%. +* Remove ez\_setup.py. + +# 0.6 (2014-09-06) + +* Ignore function names starting with "test\_". +* Parse variable names in new format strings (e.g. "This is + {x}".format(x="nice")). +* Only parse alphanumeric variable names in format strings and ignore + types. +* Abort with exit code 1 on syntax errors. +* Support installation under Windows by using setuptools (thanks + Reuben Fletcher-Costin). + +# 0.5 (2014-05-09) + +* If dead code is found, exit with 1. + +# 0.4.1 (2013-09-17) + +* Only warn if a path given on the command line cannot be found. + +# 0.4 (2013-06-23) + +* Ignore unused variables starting with an underscore. +* Show warning for syntax errors instead of aborting directly. +* Print warning if a file cannot be found. + +# 0.3 (2012-03-19) + +* Add support for python3 +* Report unused attributes +* Find tuple assignments in comprehensions +* Scan files given on the command line even if they don't end with .py + +# 0.2 (2012-03-18) + +* Only format nodes in verbose mode (gives 4x speedup). + +# 0.1 (2012-03-17) + +* First release. + + +%package -n python3-vulture +Summary: Find dead code +Provides: python-vulture +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-vulture +# Vulture - Find dead code + + +[](https://codecov.io/gh/jendrikseipp/vulture?branch=main) + +Vulture finds unused code in Python programs. This is useful for +cleaning up and finding errors in large code bases. If you run Vulture +on both your library and test suite you can find untested code. + +Due to Python's dynamic nature, static code analyzers like Vulture are +likely to miss some dead code. Also, code that is only called implicitly +may be reported as unused. Nonetheless, Vulture can be a very helpful +tool for higher code quality. + +## Features + +* fast: uses static code analysis +* tested: tests itself and has complete test coverage +* complements pyflakes and has the same output syntax +* sorts unused classes and functions by size with `--sort-by-size` +* supports Python \>= 3.6 + +## Installation + + $ pip install vulture + +## Usage + + $ vulture myscript.py # or + $ python3 -m vulture myscript.py + $ vulture myscript.py mypackage/ + $ vulture myscript.py --min-confidence 100 # Only report 100% dead code. + +The provided arguments may be Python files or directories. For each +directory Vulture analyzes all contained +<span class="title-ref">\*.py</span> files. + +After you have found and deleted dead code, run Vulture again, because +it may discover more dead code. + +## Types of unused code + +In addition to finding unused functions, classes, etc., Vulture can detect +unreachable code. Each chunk of dead code is assigned a *confidence value* +between 60% and 100%, where a value of 100% signals that it is certain that the +code won't be executed. Values below 100% are *very rough* estimates (based on +the type of code chunk) for how likely it is that the code is unused. + +| Code type | Confidence value | +| ------------------- | -- | +| function/method/class argument, unreachable code | 100% | +| import | 90% | +| attribute, class, function, method, property, variable | 60% | + +You can use the `--min-confidence` flag to set the minimum confidence +for code to be reported as unused. Use `--min-confidence 100` to only +report code that is guaranteed to be unused within the analyzed files. + +## Handling false positives + +When Vulture incorrectly reports chunks of code as unused, you have +several options for suppressing the false positives. If fixing your false +positives could benefit other users as well, please file an issue report. + +#### Whitelists + +The recommended option is to add used code that is reported as unused to a +Python module and add it to the list of scanned paths. To obtain such a +whitelist automatically, pass `--make-whitelist` to Vulture: + + $ vulture mydir --make-whitelist > whitelist.py + $ vulture mydir whitelist.py + +Note that the resulting `whitelist.py` file will contain valid Python +syntax, but for Python to be able to *run* it, you will usually have to +make some modifications. + +We collect whitelists for common Python modules and packages in +`vulture/whitelists/` (pull requests are welcome). + +#### Ignoring files + +If you want to ignore a whole file or directory, use the `--exclude` parameter +(e.g., `--exclude "*settings.py,*/docs/*.py,*/test_*.py,*/.venv/*.py"`). The +exclude patterns are matched against absolute paths. + +#### Flake8 noqa comments + +<!-- Hide noqa docs until we decide whether we want to support it. +Another way of ignoring errors is to annotate the line causing the false +positive with `# noqa: <ERROR_CODE>` in a trailing comment (e.g., `# +noqa: V103`). The `ERROR_CODE` specifies what kind of dead code to +ignore (see the table below for the list of error codes). In case no +error code is specified, Vulture ignores all results for the line. +(Note that the line number for decorated objects is the line number of +the first decorator.) +--> + +For compatibility with [flake8](https://flake8.pycqa.org/), Vulture +supports the [F401 and +F841](https://flake8.pycqa.org/en/latest/user/error-codes.html) error +codes for ignoring unused imports (`# noqa: F401`) and unused local +variables (`# noqa: F841`). However, we recommend using whitelists instead +of `noqa` comments, since `noqa` comments add visual noise to the code and +make it harder to read. + +#### Ignoring names + +You can use `--ignore-names foo*,ba[rz]` to let Vulture ignore all names +starting with `foo` and the names `bar` and `baz`. Additionally, the +`--ignore-decorators` option can be used to ignore functions decorated +with the given decorator. This is helpful for example in Flask projects, +where you can use `--ignore-decorators "@app.route"` to ignore all +functions with the `@app.route` decorator. + +We recommend using whitelists instead of `--ignore-names` or +`--ignore-decorators` whenever possible, since whitelists are +automatically checked for syntactic correctness when passed to Vulture +and often you can even pass them to your Python interpreter and let it +check that all whitelisted code actually still exists in your project. + +#### Marking unused variables + +There are situations where you can't just remove unused variables, e.g., +in function signatures. The recommended solution is to use the `del` +keyword as described in the +[PyLint manual](http://pylint-messages.wikidot.com/messages:w0613) and on +[StackOverflow](https://stackoverflow.com/a/14836005): + +```python +def foo(x, y): + del y + return x + 3 +``` + +Vulture will also ignore all variables that start with an underscore, so +you can use `_x, y = get_pos()` to mark unused tuple assignments or +function arguments, e.g., `def foo(x, _y)`. + +#### Minimum confidence + +Raise the minimum [confidence value](#types-of-unused-code) with the `--min-confidence` flag. + +#### Unreachable code + +If Vulture complains about code like `if False:`, you can use a Boolean +flag `debug = False` and write `if debug:` instead. This makes the code +more readable and silences Vulture. + +#### Forward references for type annotations + +See [#216](https://github.com/jendrikseipp/vulture/issues/216). For +example, instead of `def foo(arg: "Sequence"): ...`, we recommend using + +``` python +from __future__ import annotations + +def foo(arg: Sequence): + ... +``` + +if you're using Python 3.7+. + + +## Configuration + +You can also store command line arguments in `pyproject.toml` under the +`tool.vulture` section. Simply remove leading dashes and replace all +remaining dashes with underscores. + +Options given on the command line have precedence over options in +`pyproject.toml`. + +Example Config: + +``` toml +[tool.vulture] +exclude = ["*file*.py", "dir/"] +ignore_decorators = ["@app.route", "@require_*"] +ignore_names = ["visit_*", "do_*"] +make_whitelist = true +min_confidence = 80 +paths = ["myscript.py", "mydir"] +sort_by_size = true +verbose = true +``` + +## Version control integration + +You can use a [pre-commit](https://pre-commit.com/#install) hook to run +Vulture before each commit. For this, install pre-commit and add the +following to the `.pre-commit-config.yaml` file in your repository: + +```yaml +repos: + - repo: https://github.com/jendrikseipp/vulture + rev: 'v2.3' # or any later Vulture version + hooks: + - id: vulture +``` + +Then run `pre-commit install`. Finally, create a `pyproject.toml` file +in your repository and specify all files that Vulture should check under +`[tool.vulture] --> paths` (see above). + +## How does it work? + +Vulture uses the `ast` module to build abstract syntax trees for all +given files. While traversing all syntax trees it records the names of +defined and used objects. Afterwards, it reports the objects which have +been defined, but not used. This analysis ignores scopes and only takes +object names into account. + +Vulture also detects unreachable code by looking for code after +`return`, `break`, `continue` and `raise` statements, and by searching +for unsatisfiable `if`- and `while`-conditions. + +## Sort by size + +When using the `--sort-by-size` option, Vulture sorts unused code by its +number of lines. This helps developers prioritize where to look for dead +code first. + +## Examples + +Consider the following Python script (`dead_code.py`): + +``` python +import os + +class Greeter: + def greet(self): + print("Hi") + +def hello_world(): + message = "Hello, world!" + greeter = Greeter() + func_name = "greet" + greet_func = getattr(greeter, func_name) + greet_func() + +if __name__ == "__main__": + hello_world() +``` + +Calling : + + $ vulture dead_code.py + +results in the following output: + + dead_code.py:1: unused import 'os' (90% confidence) + dead_code.py:4: unused function 'greet' (60% confidence) + dead_code.py:8: unused variable 'message' (60% confidence) + +Vulture correctly reports `os` and `message` as unused but it fails to +detect that `greet` is actually used. The recommended method to deal +with false positives like this is to create a whitelist Python file. + +**Preparing whitelists** + +In a whitelist we simulate the usage of variables, attributes, etc. For +the program above, a whitelist could look as follows: + +``` python +# whitelist_dead_code.py +from dead_code import Greeter +Greeter.greet +``` + +Alternatively, you can pass `--make-whitelist` to Vulture and obtain an +automatically generated whitelist. + +Passing both the original program and the whitelist to Vulture + + $ vulture dead_code.py whitelist_dead_code.py + +makes Vulture ignore the `greet` method: + + dead_code.py:1: unused import 'os' (90% confidence) + dead_code.py:8: unused variable 'message' (60% confidence) + +<!-- Hide noqa docs until we decide whether we want to support it. +**Using "# noqa"** + +```python +import os # noqa + +class Greeter: # noqa: V102 + def greet(self): # noqa: V103 + print("Hi") +``` + +## Error codes + +For compatibility with [flake8](https://flake8.pycqa.org/), Vulture +supports the [F401 and +F841](https://flake8.pycqa.org/en/latest/user/error-codes.html) error +codes. + +| Error codes | Description | +| ----------- | ----------------- | +| V101 | Unused attribute | +| V102 | Unused class | +| V103 | Unused function | +| V104, F401 | Unused import | +| V105 | Unused property | +| V106 | Unused method | +| V107, F841 | Unused variable | +| V201 | Unreachable code | + +--> + +## Exit codes + +| Exit code | Description | +| --------- | ------------------------------------------------------------- | +| 0 | No dead code found | +| 1 | Dead code found | +| 1 | Invalid input (file missing, syntax error, wrong encoding) | +| 2 | Invalid command line arguments | + +## Similar programs + + - [pyflakes](https://pypi.org/project/pyflakes/) finds unused imports + and unused local variables (in addition to many other programmatic + errors). + - [coverage](https://pypi.org/project/coverage/) finds unused code + more reliably than Vulture, but requires all branches of the code to + actually be run. + - [uncalled](https://pypi.org/project/uncalled/) finds dead code by + using the abstract syntax tree (like Vulture), regular expressions, + or both. + - [dead](https://pypi.org/project/dead/) finds dead code by using the + abstract syntax tree (like Vulture). + +## Participate + +Please visit <https://github.com/jendrikseipp/vulture> to report any +issues or to make pull requests. + + - Contributing guide: + [CONTRIBUTING.md](https://github.com/jendrikseipp/vulture/blob/main/CONTRIBUTING.md) + - Release notes: + [CHANGELOG.md](https://github.com/jendrikseipp/vulture/blob/main/CHANGELOG.md) + - Roadmap: + [TODO.md](https://github.com/jendrikseipp/vulture/blob/main/TODO.md) + + +# 2.7 (2023-01-08) + +* Ignore `setup_module()`, `teardown_module()`, etc. in pytest `test_*.py` files (Jendrik Seipp). +* Add whitelist for `socketserver.TCPServer.allow_reuse_address` (Ben Elliston). +* Clarify that `--exclude` patterns are matched against absolute paths (Jendrik Seipp, #260). +* Fix example in README file (Jendrik Seipp, #272). + +# 2.6 (2022-09-19) + +* Add basic `match` statement support (kreathon, #276, #291). + +# 2.5 (2022-07-03) + +* Mark imports in `__all__` as used (kreathon, #172, #282). +* Add whitelist for `pint.UnitRegistry.default_formatter` (Ben Elliston, #258). + +# 2.4 (2022-05-19) + +* Print absolute filepaths as relative again (as in version 2.1 and before) + if they are below the current directory (The-Compiler, #246). +* Run tests and add PyPI trove for Python 3.10 (chayim, #266). +* Allow using the `del` keyword to mark unused variables (sshishov, #279). + +# 2.3 (2021-01-16) + +* Add [pre-commit](https://pre-commit.com) hook (Clément Robert, #244). + +# 2.2 (2021-01-15) + +* Only parse format strings when being used with `locals()` (jingw, #225). +* Don't override paths in pyproject.toml with empty CLI paths (bcbnz, #228). +* Run continuous integration tests for Python 3.9 (ju-sh, #232). +* Use pathlib internally (ju-sh, #226). + +# 2.1 (2020-08-19) + +* Treat `getattr/hasattr(obj, "constant_string", ...)` as a reference to + `obj.constant_string` (jingw, #219). +* Fix false positives when assigning to `x.some_name` but reading via + `some_name`, at the cost of potential false negatives (jingw, #221). +* Allow reading options from `pyproject.toml` (Michel Albert, #164, #215). + +# 2.0 (2020-08-11) + +* Parse `# type: ...` comments if on Python 3.8+ (jingw, #220). +* Bump minimum Python version to 3.6 (Jendrik Seipp, #218). The last + Vulture release that supports Python 2.7 and Python 3.5 is version 1.6. +* Consider all files under `test` or `tests` directories test files + (Jendrik Seipp). +* Ignore `logging.Logger.propagate` attribute (Jendrik Seipp). + +# 1.6 (2020-07-28) + +* Differentiate between functions and methods (Jendrik Seipp, #112, #209). +* Move from Travis to GitHub actions (RJ722, #211). + +# 1.5 (2020-05-24) + +* Support flake8 "noqa" error codes F401 (unused import) and F841 (unused + local variable) (RJ722, #195). +* Detect unreachable code in conditional expressions + (Agathiyan Bragadeesh, #178). + +# 1.4 (2020-03-30) + +* Ignore unused import statements in `__init__.py` (RJ722, #192). +* Report first decorator's line number for unused decorated objects on + Python 3.8+ (RJ722, #200). +* Check code with black and pyupgrade. + +# 1.3 (2020-02-03) + +* Detect redundant 'if' conditions without 'else' blocks. +* Add whitelist for `string.Formatter` (Joseph Bylund, #183). + +# 1.2 (2019-11-22) + +* Fix tests for Python 3.8 (#166). +* Use new `Constant` AST node under Python 3.8+ (#175). +* Add test for f-strings (#177). +* Add whitelist for `logging` module. + +# 1.1 (2019-09-23) + +* Add `sys.excepthook` to `sys` whitelist. +* Add whitelist for `ctypes` module. +* Check that type annotations are parsed and type comments are ignored + (thanks @kx-chen). +* Support checking files with BOM under Python 2.7 (#170). + +# 1.0 (2018-10-23) + +* Add `--ignore-decorators` flag (thanks @RJ722). +* Add whitelist for `threading` module (thanks @andrewhalle). + +# 0.29 (2018-07-31) + +* Add `--ignore-names` flag for ignoring names matching the given glob + patterns (thanks @RJ722). + +# 0.28 (2018-07-05) + +* Add `--make-whitelist` flag for reporting output in whitelist format + (thanks @RJ722). +* Ignore case of `--exclude` arguments on Windows. +* Add `*-test.py` to recognized test file patterns. +* Add `failureException`, `longMessage` and `maxDiff` to `unittest` + whitelist. +* Refer to actual objects rather than their mocks in default + whitelists (thanks @RJ722). +* Don't import any Vulture modules in setup.py (thanks @RJ722). + +# 0.27 (2018-06-05) + +* Report `while (True): ... else: ...` as unreachable (thanks @RJ722). +* Use `argparse` instead of `optparse`. +* Whitelist Mock.return\_value and Mock.side\_effect in unittest.mock + module. +* Drop support for Python 2.6 and 3.3. +* Improve documentation and test coverage (thanks @RJ722). + +# 0.26 (2017-08-28) + +* Detect `async` function definitions (thanks @RJ722). +* Add `Item.get_report()` method (thanks @RJ722). +* Move method for finding Python modules out of Vulture class. + +# 0.25 (2017-08-15) + +* Detect unsatisfiable statements containing `and`, `or` and `not`. +* Use filenames and line numbers as tie-breakers when sorting by size. +* Store first and last line numbers in Item objects. +* Pass relevant options directly to `scavenge()` and `report()`. + +# 0.24 (2017-08-14) + +* Detect unsatisfiable `while`-conditions (thanks @RJ722). +* Detect unsatisfiable `if`- and `else`-conditions (thanks @RJ722). +* Handle null bytes in source code. + +# 0.23 (2017-08-10) + +* Add `--min-confidence` flag (thanks @RJ722). + +# 0.22 (2017-08-04) + +* Detect unreachable code after `return`, `break`, `continue` and + `raise` (thanks @RJ722). +* Parse all variable and attribute names in new format strings. +* Extend ast whitelist. + +# 0.21 (2017-07-26) + +* If an unused item is defined multiple times, report it multiple + times. +* Make size estimates for function calls more accurate. +* Create wheel files for Vulture (thanks @RJ722). + +# 0.20 (2017-07-26) + +* Report unused tuple assignments as dead code. +* Report attribute names that have the same names as variables as dead + code. +* Let Item class inherit from `object` (thanks @RJ722). +* Handle names imported as aliases like all other used variable names. +* Rename Vulture.used\_vars to Vulture.used\_names. +* Use function for determining which imports to ignore. +* Only try to import each whitelist file once. +* Store used names and used attributes in sets instead of lists. +* Fix estimating the size of code containing ellipses (...). +* Refactor and simplify code. + +# 0.19 (2017-07-20) + +* Don't ignore <span class="title-ref">\_\_foo</span> variable names. +* Use separate methods for determining whether to ignore classes and + functions. +* Only try to find a whitelist for each defined import once (thanks + @roivanov). +* Fix finding the last child for many types of AST nodes. + +# 0.18 (2017-07-17) + +* Make <span class="title-ref">--sort-by-size</span> faster and more + accurate (thanks @RJ722). + +# 0.17 (2017-07-17) + +* Add <span class="title-ref">get\_unused\_code()</span> method. +* Return with exit code 1 when syntax errors are found or files can't + be read. + +# 0.16 (2017-07-12) + +* Differentiate between unused classes and functions (thanks @RJ722). +* Add --sort-by-size option (thanks @jackric and @RJ722). +* Count imports as used if they are accessed as module attributes. + +# 0.15 (2017-07-04) + +* Automatically include whitelists based on imported modules (thanks + @RJ722). +* Add --version parameter (thanks @RJ722). +* Add appveyor tests for testing on Windows (thanks @RJ722). + +# 0.14 (2017-04-06) + +* Add stub whitelist file for Python standard library (thanks @RJ722) +* Ignore class names starting with "Test" in "test\_" files (thanks + @thisch). +* Ignore "test\_" functions only in "test\_" files. + +# 0.13 (2017-03-06) + +* Ignore star-imported names since we cannot detect whether they are + used. +* Move repository to GitHub. + +# 0.12 (2017-01-05) + +* Detect unused imports. +* Use tokenize.open() on Python \>= 3.2 for reading input files, + assume UTF-8 encoding on older Python versions. + +# 0.11 (2016-11-27) + +* Use the system's default encoding when reading files. +* Report syntax errors instead of aborting. + +# 0.10 (2016-07-14) + +* Detect unused function and method arguments (issue #15). +* Detect unused \*args and \*\*kwargs parameters. +* Change license from GPL to MIT. + +# 0.9 (2016-06-29) + +* Don't flag attributes as unused if they are used as global variables + in another module (thanks Florian Bruhin). +* Don't consider "True" and "False" variable names. +* Abort with error message when invoked on .pyc files. + +# 0.8.1 (2015-09-28) + +* Fix code for Python 3. + +# 0.8 (2015-09-28) + +* Do not flag names imported with "import as" as dead code (thanks Tom + Terrace). + +# 0.7 (2015-09-26) + +* Exit with exitcode 1 if path on commandline can't be found. +* Test vulture with vulture using a whitelist module for false + positives. +* Add tests that run vulture as a script. +* Add "python setup.py test" command for running tests. +* Add support for tox. +* Raise test coverage to 100%. +* Remove ez\_setup.py. + +# 0.6 (2014-09-06) + +* Ignore function names starting with "test\_". +* Parse variable names in new format strings (e.g. "This is + {x}".format(x="nice")). +* Only parse alphanumeric variable names in format strings and ignore + types. +* Abort with exit code 1 on syntax errors. +* Support installation under Windows by using setuptools (thanks + Reuben Fletcher-Costin). + +# 0.5 (2014-05-09) + +* If dead code is found, exit with 1. + +# 0.4.1 (2013-09-17) + +* Only warn if a path given on the command line cannot be found. + +# 0.4 (2013-06-23) + +* Ignore unused variables starting with an underscore. +* Show warning for syntax errors instead of aborting directly. +* Print warning if a file cannot be found. + +# 0.3 (2012-03-19) + +* Add support for python3 +* Report unused attributes +* Find tuple assignments in comprehensions +* Scan files given on the command line even if they don't end with .py + +# 0.2 (2012-03-18) + +* Only format nodes in verbose mode (gives 4x speedup). + +# 0.1 (2012-03-17) + +* First release. + + +%package help +Summary: Development documents and examples for vulture +Provides: python3-vulture-doc +%description help +# Vulture - Find dead code + + +[](https://codecov.io/gh/jendrikseipp/vulture?branch=main) + +Vulture finds unused code in Python programs. This is useful for +cleaning up and finding errors in large code bases. If you run Vulture +on both your library and test suite you can find untested code. + +Due to Python's dynamic nature, static code analyzers like Vulture are +likely to miss some dead code. Also, code that is only called implicitly +may be reported as unused. Nonetheless, Vulture can be a very helpful +tool for higher code quality. + +## Features + +* fast: uses static code analysis +* tested: tests itself and has complete test coverage +* complements pyflakes and has the same output syntax +* sorts unused classes and functions by size with `--sort-by-size` +* supports Python \>= 3.6 + +## Installation + + $ pip install vulture + +## Usage + + $ vulture myscript.py # or + $ python3 -m vulture myscript.py + $ vulture myscript.py mypackage/ + $ vulture myscript.py --min-confidence 100 # Only report 100% dead code. + +The provided arguments may be Python files or directories. For each +directory Vulture analyzes all contained +<span class="title-ref">\*.py</span> files. + +After you have found and deleted dead code, run Vulture again, because +it may discover more dead code. + +## Types of unused code + +In addition to finding unused functions, classes, etc., Vulture can detect +unreachable code. Each chunk of dead code is assigned a *confidence value* +between 60% and 100%, where a value of 100% signals that it is certain that the +code won't be executed. Values below 100% are *very rough* estimates (based on +the type of code chunk) for how likely it is that the code is unused. + +| Code type | Confidence value | +| ------------------- | -- | +| function/method/class argument, unreachable code | 100% | +| import | 90% | +| attribute, class, function, method, property, variable | 60% | + +You can use the `--min-confidence` flag to set the minimum confidence +for code to be reported as unused. Use `--min-confidence 100` to only +report code that is guaranteed to be unused within the analyzed files. + +## Handling false positives + +When Vulture incorrectly reports chunks of code as unused, you have +several options for suppressing the false positives. If fixing your false +positives could benefit other users as well, please file an issue report. + +#### Whitelists + +The recommended option is to add used code that is reported as unused to a +Python module and add it to the list of scanned paths. To obtain such a +whitelist automatically, pass `--make-whitelist` to Vulture: + + $ vulture mydir --make-whitelist > whitelist.py + $ vulture mydir whitelist.py + +Note that the resulting `whitelist.py` file will contain valid Python +syntax, but for Python to be able to *run* it, you will usually have to +make some modifications. + +We collect whitelists for common Python modules and packages in +`vulture/whitelists/` (pull requests are welcome). + +#### Ignoring files + +If you want to ignore a whole file or directory, use the `--exclude` parameter +(e.g., `--exclude "*settings.py,*/docs/*.py,*/test_*.py,*/.venv/*.py"`). The +exclude patterns are matched against absolute paths. + +#### Flake8 noqa comments + +<!-- Hide noqa docs until we decide whether we want to support it. +Another way of ignoring errors is to annotate the line causing the false +positive with `# noqa: <ERROR_CODE>` in a trailing comment (e.g., `# +noqa: V103`). The `ERROR_CODE` specifies what kind of dead code to +ignore (see the table below for the list of error codes). In case no +error code is specified, Vulture ignores all results for the line. +(Note that the line number for decorated objects is the line number of +the first decorator.) +--> + +For compatibility with [flake8](https://flake8.pycqa.org/), Vulture +supports the [F401 and +F841](https://flake8.pycqa.org/en/latest/user/error-codes.html) error +codes for ignoring unused imports (`# noqa: F401`) and unused local +variables (`# noqa: F841`). However, we recommend using whitelists instead +of `noqa` comments, since `noqa` comments add visual noise to the code and +make it harder to read. + +#### Ignoring names + +You can use `--ignore-names foo*,ba[rz]` to let Vulture ignore all names +starting with `foo` and the names `bar` and `baz`. Additionally, the +`--ignore-decorators` option can be used to ignore functions decorated +with the given decorator. This is helpful for example in Flask projects, +where you can use `--ignore-decorators "@app.route"` to ignore all +functions with the `@app.route` decorator. + +We recommend using whitelists instead of `--ignore-names` or +`--ignore-decorators` whenever possible, since whitelists are +automatically checked for syntactic correctness when passed to Vulture +and often you can even pass them to your Python interpreter and let it +check that all whitelisted code actually still exists in your project. + +#### Marking unused variables + +There are situations where you can't just remove unused variables, e.g., +in function signatures. The recommended solution is to use the `del` +keyword as described in the +[PyLint manual](http://pylint-messages.wikidot.com/messages:w0613) and on +[StackOverflow](https://stackoverflow.com/a/14836005): + +```python +def foo(x, y): + del y + return x + 3 +``` + +Vulture will also ignore all variables that start with an underscore, so +you can use `_x, y = get_pos()` to mark unused tuple assignments or +function arguments, e.g., `def foo(x, _y)`. + +#### Minimum confidence + +Raise the minimum [confidence value](#types-of-unused-code) with the `--min-confidence` flag. + +#### Unreachable code + +If Vulture complains about code like `if False:`, you can use a Boolean +flag `debug = False` and write `if debug:` instead. This makes the code +more readable and silences Vulture. + +#### Forward references for type annotations + +See [#216](https://github.com/jendrikseipp/vulture/issues/216). For +example, instead of `def foo(arg: "Sequence"): ...`, we recommend using + +``` python +from __future__ import annotations + +def foo(arg: Sequence): + ... +``` + +if you're using Python 3.7+. + + +## Configuration + +You can also store command line arguments in `pyproject.toml` under the +`tool.vulture` section. Simply remove leading dashes and replace all +remaining dashes with underscores. + +Options given on the command line have precedence over options in +`pyproject.toml`. + +Example Config: + +``` toml +[tool.vulture] +exclude = ["*file*.py", "dir/"] +ignore_decorators = ["@app.route", "@require_*"] +ignore_names = ["visit_*", "do_*"] +make_whitelist = true +min_confidence = 80 +paths = ["myscript.py", "mydir"] +sort_by_size = true +verbose = true +``` + +## Version control integration + +You can use a [pre-commit](https://pre-commit.com/#install) hook to run +Vulture before each commit. For this, install pre-commit and add the +following to the `.pre-commit-config.yaml` file in your repository: + +```yaml +repos: + - repo: https://github.com/jendrikseipp/vulture + rev: 'v2.3' # or any later Vulture version + hooks: + - id: vulture +``` + +Then run `pre-commit install`. Finally, create a `pyproject.toml` file +in your repository and specify all files that Vulture should check under +`[tool.vulture] --> paths` (see above). + +## How does it work? + +Vulture uses the `ast` module to build abstract syntax trees for all +given files. While traversing all syntax trees it records the names of +defined and used objects. Afterwards, it reports the objects which have +been defined, but not used. This analysis ignores scopes and only takes +object names into account. + +Vulture also detects unreachable code by looking for code after +`return`, `break`, `continue` and `raise` statements, and by searching +for unsatisfiable `if`- and `while`-conditions. + +## Sort by size + +When using the `--sort-by-size` option, Vulture sorts unused code by its +number of lines. This helps developers prioritize where to look for dead +code first. + +## Examples + +Consider the following Python script (`dead_code.py`): + +``` python +import os + +class Greeter: + def greet(self): + print("Hi") + +def hello_world(): + message = "Hello, world!" + greeter = Greeter() + func_name = "greet" + greet_func = getattr(greeter, func_name) + greet_func() + +if __name__ == "__main__": + hello_world() +``` + +Calling : + + $ vulture dead_code.py + +results in the following output: + + dead_code.py:1: unused import 'os' (90% confidence) + dead_code.py:4: unused function 'greet' (60% confidence) + dead_code.py:8: unused variable 'message' (60% confidence) + +Vulture correctly reports `os` and `message` as unused but it fails to +detect that `greet` is actually used. The recommended method to deal +with false positives like this is to create a whitelist Python file. + +**Preparing whitelists** + +In a whitelist we simulate the usage of variables, attributes, etc. For +the program above, a whitelist could look as follows: + +``` python +# whitelist_dead_code.py +from dead_code import Greeter +Greeter.greet +``` + +Alternatively, you can pass `--make-whitelist` to Vulture and obtain an +automatically generated whitelist. + +Passing both the original program and the whitelist to Vulture + + $ vulture dead_code.py whitelist_dead_code.py + +makes Vulture ignore the `greet` method: + + dead_code.py:1: unused import 'os' (90% confidence) + dead_code.py:8: unused variable 'message' (60% confidence) + +<!-- Hide noqa docs until we decide whether we want to support it. +**Using "# noqa"** + +```python +import os # noqa + +class Greeter: # noqa: V102 + def greet(self): # noqa: V103 + print("Hi") +``` + +## Error codes + +For compatibility with [flake8](https://flake8.pycqa.org/), Vulture +supports the [F401 and +F841](https://flake8.pycqa.org/en/latest/user/error-codes.html) error +codes. + +| Error codes | Description | +| ----------- | ----------------- | +| V101 | Unused attribute | +| V102 | Unused class | +| V103 | Unused function | +| V104, F401 | Unused import | +| V105 | Unused property | +| V106 | Unused method | +| V107, F841 | Unused variable | +| V201 | Unreachable code | + +--> + +## Exit codes + +| Exit code | Description | +| --------- | ------------------------------------------------------------- | +| 0 | No dead code found | +| 1 | Dead code found | +| 1 | Invalid input (file missing, syntax error, wrong encoding) | +| 2 | Invalid command line arguments | + +## Similar programs + + - [pyflakes](https://pypi.org/project/pyflakes/) finds unused imports + and unused local variables (in addition to many other programmatic + errors). + - [coverage](https://pypi.org/project/coverage/) finds unused code + more reliably than Vulture, but requires all branches of the code to + actually be run. + - [uncalled](https://pypi.org/project/uncalled/) finds dead code by + using the abstract syntax tree (like Vulture), regular expressions, + or both. + - [dead](https://pypi.org/project/dead/) finds dead code by using the + abstract syntax tree (like Vulture). + +## Participate + +Please visit <https://github.com/jendrikseipp/vulture> to report any +issues or to make pull requests. + + - Contributing guide: + [CONTRIBUTING.md](https://github.com/jendrikseipp/vulture/blob/main/CONTRIBUTING.md) + - Release notes: + [CHANGELOG.md](https://github.com/jendrikseipp/vulture/blob/main/CHANGELOG.md) + - Roadmap: + [TODO.md](https://github.com/jendrikseipp/vulture/blob/main/TODO.md) + + +# 2.7 (2023-01-08) + +* Ignore `setup_module()`, `teardown_module()`, etc. in pytest `test_*.py` files (Jendrik Seipp). +* Add whitelist for `socketserver.TCPServer.allow_reuse_address` (Ben Elliston). +* Clarify that `--exclude` patterns are matched against absolute paths (Jendrik Seipp, #260). +* Fix example in README file (Jendrik Seipp, #272). + +# 2.6 (2022-09-19) + +* Add basic `match` statement support (kreathon, #276, #291). + +# 2.5 (2022-07-03) + +* Mark imports in `__all__` as used (kreathon, #172, #282). +* Add whitelist for `pint.UnitRegistry.default_formatter` (Ben Elliston, #258). + +# 2.4 (2022-05-19) + +* Print absolute filepaths as relative again (as in version 2.1 and before) + if they are below the current directory (The-Compiler, #246). +* Run tests and add PyPI trove for Python 3.10 (chayim, #266). +* Allow using the `del` keyword to mark unused variables (sshishov, #279). + +# 2.3 (2021-01-16) + +* Add [pre-commit](https://pre-commit.com) hook (Clément Robert, #244). + +# 2.2 (2021-01-15) + +* Only parse format strings when being used with `locals()` (jingw, #225). +* Don't override paths in pyproject.toml with empty CLI paths (bcbnz, #228). +* Run continuous integration tests for Python 3.9 (ju-sh, #232). +* Use pathlib internally (ju-sh, #226). + +# 2.1 (2020-08-19) + +* Treat `getattr/hasattr(obj, "constant_string", ...)` as a reference to + `obj.constant_string` (jingw, #219). +* Fix false positives when assigning to `x.some_name` but reading via + `some_name`, at the cost of potential false negatives (jingw, #221). +* Allow reading options from `pyproject.toml` (Michel Albert, #164, #215). + +# 2.0 (2020-08-11) + +* Parse `# type: ...` comments if on Python 3.8+ (jingw, #220). +* Bump minimum Python version to 3.6 (Jendrik Seipp, #218). The last + Vulture release that supports Python 2.7 and Python 3.5 is version 1.6. +* Consider all files under `test` or `tests` directories test files + (Jendrik Seipp). +* Ignore `logging.Logger.propagate` attribute (Jendrik Seipp). + +# 1.6 (2020-07-28) + +* Differentiate between functions and methods (Jendrik Seipp, #112, #209). +* Move from Travis to GitHub actions (RJ722, #211). + +# 1.5 (2020-05-24) + +* Support flake8 "noqa" error codes F401 (unused import) and F841 (unused + local variable) (RJ722, #195). +* Detect unreachable code in conditional expressions + (Agathiyan Bragadeesh, #178). + +# 1.4 (2020-03-30) + +* Ignore unused import statements in `__init__.py` (RJ722, #192). +* Report first decorator's line number for unused decorated objects on + Python 3.8+ (RJ722, #200). +* Check code with black and pyupgrade. + +# 1.3 (2020-02-03) + +* Detect redundant 'if' conditions without 'else' blocks. +* Add whitelist for `string.Formatter` (Joseph Bylund, #183). + +# 1.2 (2019-11-22) + +* Fix tests for Python 3.8 (#166). +* Use new `Constant` AST node under Python 3.8+ (#175). +* Add test for f-strings (#177). +* Add whitelist for `logging` module. + +# 1.1 (2019-09-23) + +* Add `sys.excepthook` to `sys` whitelist. +* Add whitelist for `ctypes` module. +* Check that type annotations are parsed and type comments are ignored + (thanks @kx-chen). +* Support checking files with BOM under Python 2.7 (#170). + +# 1.0 (2018-10-23) + +* Add `--ignore-decorators` flag (thanks @RJ722). +* Add whitelist for `threading` module (thanks @andrewhalle). + +# 0.29 (2018-07-31) + +* Add `--ignore-names` flag for ignoring names matching the given glob + patterns (thanks @RJ722). + +# 0.28 (2018-07-05) + +* Add `--make-whitelist` flag for reporting output in whitelist format + (thanks @RJ722). +* Ignore case of `--exclude` arguments on Windows. +* Add `*-test.py` to recognized test file patterns. +* Add `failureException`, `longMessage` and `maxDiff` to `unittest` + whitelist. +* Refer to actual objects rather than their mocks in default + whitelists (thanks @RJ722). +* Don't import any Vulture modules in setup.py (thanks @RJ722). + +# 0.27 (2018-06-05) + +* Report `while (True): ... else: ...` as unreachable (thanks @RJ722). +* Use `argparse` instead of `optparse`. +* Whitelist Mock.return\_value and Mock.side\_effect in unittest.mock + module. +* Drop support for Python 2.6 and 3.3. +* Improve documentation and test coverage (thanks @RJ722). + +# 0.26 (2017-08-28) + +* Detect `async` function definitions (thanks @RJ722). +* Add `Item.get_report()` method (thanks @RJ722). +* Move method for finding Python modules out of Vulture class. + +# 0.25 (2017-08-15) + +* Detect unsatisfiable statements containing `and`, `or` and `not`. +* Use filenames and line numbers as tie-breakers when sorting by size. +* Store first and last line numbers in Item objects. +* Pass relevant options directly to `scavenge()` and `report()`. + +# 0.24 (2017-08-14) + +* Detect unsatisfiable `while`-conditions (thanks @RJ722). +* Detect unsatisfiable `if`- and `else`-conditions (thanks @RJ722). +* Handle null bytes in source code. + +# 0.23 (2017-08-10) + +* Add `--min-confidence` flag (thanks @RJ722). + +# 0.22 (2017-08-04) + +* Detect unreachable code after `return`, `break`, `continue` and + `raise` (thanks @RJ722). +* Parse all variable and attribute names in new format strings. +* Extend ast whitelist. + +# 0.21 (2017-07-26) + +* If an unused item is defined multiple times, report it multiple + times. +* Make size estimates for function calls more accurate. +* Create wheel files for Vulture (thanks @RJ722). + +# 0.20 (2017-07-26) + +* Report unused tuple assignments as dead code. +* Report attribute names that have the same names as variables as dead + code. +* Let Item class inherit from `object` (thanks @RJ722). +* Handle names imported as aliases like all other used variable names. +* Rename Vulture.used\_vars to Vulture.used\_names. +* Use function for determining which imports to ignore. +* Only try to import each whitelist file once. +* Store used names and used attributes in sets instead of lists. +* Fix estimating the size of code containing ellipses (...). +* Refactor and simplify code. + +# 0.19 (2017-07-20) + +* Don't ignore <span class="title-ref">\_\_foo</span> variable names. +* Use separate methods for determining whether to ignore classes and + functions. +* Only try to find a whitelist for each defined import once (thanks + @roivanov). +* Fix finding the last child for many types of AST nodes. + +# 0.18 (2017-07-17) + +* Make <span class="title-ref">--sort-by-size</span> faster and more + accurate (thanks @RJ722). + +# 0.17 (2017-07-17) + +* Add <span class="title-ref">get\_unused\_code()</span> method. +* Return with exit code 1 when syntax errors are found or files can't + be read. + +# 0.16 (2017-07-12) + +* Differentiate between unused classes and functions (thanks @RJ722). +* Add --sort-by-size option (thanks @jackric and @RJ722). +* Count imports as used if they are accessed as module attributes. + +# 0.15 (2017-07-04) + +* Automatically include whitelists based on imported modules (thanks + @RJ722). +* Add --version parameter (thanks @RJ722). +* Add appveyor tests for testing on Windows (thanks @RJ722). + +# 0.14 (2017-04-06) + +* Add stub whitelist file for Python standard library (thanks @RJ722) +* Ignore class names starting with "Test" in "test\_" files (thanks + @thisch). +* Ignore "test\_" functions only in "test\_" files. + +# 0.13 (2017-03-06) + +* Ignore star-imported names since we cannot detect whether they are + used. +* Move repository to GitHub. + +# 0.12 (2017-01-05) + +* Detect unused imports. +* Use tokenize.open() on Python \>= 3.2 for reading input files, + assume UTF-8 encoding on older Python versions. + +# 0.11 (2016-11-27) + +* Use the system's default encoding when reading files. +* Report syntax errors instead of aborting. + +# 0.10 (2016-07-14) + +* Detect unused function and method arguments (issue #15). +* Detect unused \*args and \*\*kwargs parameters. +* Change license from GPL to MIT. + +# 0.9 (2016-06-29) + +* Don't flag attributes as unused if they are used as global variables + in another module (thanks Florian Bruhin). +* Don't consider "True" and "False" variable names. +* Abort with error message when invoked on .pyc files. + +# 0.8.1 (2015-09-28) + +* Fix code for Python 3. + +# 0.8 (2015-09-28) + +* Do not flag names imported with "import as" as dead code (thanks Tom + Terrace). + +# 0.7 (2015-09-26) + +* Exit with exitcode 1 if path on commandline can't be found. +* Test vulture with vulture using a whitelist module for false + positives. +* Add tests that run vulture as a script. +* Add "python setup.py test" command for running tests. +* Add support for tox. +* Raise test coverage to 100%. +* Remove ez\_setup.py. + +# 0.6 (2014-09-06) + +* Ignore function names starting with "test\_". +* Parse variable names in new format strings (e.g. "This is + {x}".format(x="nice")). +* Only parse alphanumeric variable names in format strings and ignore + types. +* Abort with exit code 1 on syntax errors. +* Support installation under Windows by using setuptools (thanks + Reuben Fletcher-Costin). + +# 0.5 (2014-05-09) + +* If dead code is found, exit with 1. + +# 0.4.1 (2013-09-17) + +* Only warn if a path given on the command line cannot be found. + +# 0.4 (2013-06-23) + +* Ignore unused variables starting with an underscore. +* Show warning for syntax errors instead of aborting directly. +* Print warning if a file cannot be found. + +# 0.3 (2012-03-19) + +* Add support for python3 +* Report unused attributes +* Find tuple assignments in comprehensions +* Scan files given on the command line even if they don't end with .py + +# 0.2 (2012-03-18) + +* Only format nodes in verbose mode (gives 4x speedup). + +# 0.1 (2012-03-17) + +* First release. + + +%prep +%autosetup -n vulture-2.7 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-vulture -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Thu Mar 09 2023 Python_Bot <Python_Bot@openeuler.org> - 2.7-1 +- Package Spec generated @@ -0,0 +1 @@ +41c14d613727030c44a4a6468c212dea vulture-2.7.tar.gz |