Issue #227, Feature/pathformat, adds --absolute-paths option

.gitignore

@@ -9,3 +9,4 @@ vulture.egg-info/
 .pytest_cache/
 .tox/
 .venv/
+.idea/

CHANGELOG.md

@@ -1,5 +1,8 @@
 # unreleased
 
+* added --absolute-paths option to have vulture output absolute paths instead of relative paths (mcooperman, #227)
+  changed git signing key to correct verification
+
 * Only parse format strings when being used with `locals()` (jingw, #225).
 
 # 2.1 (2020-08-19)

README.md

@@ -152,6 +152,7 @@ ignore_names = ["visit_*", "do_*"]
 make_whitelist = true
 min_confidence = 80
 sort_by_size = true
+absolute_paths = false
 verbose = true
 paths = ["myscript.py", "mydir"]
 ```
@@ -174,6 +175,54 @@ 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.
 
+## Path Formatting
+
+The `—path-format` option allows control of how file paths are emitted in the output of vulture.
+
+This can be useful when using vulture as a plugin tool for IDEs like PyCharm. Using absolute paths enables ‘jump-to-code’ from the output error messages when vulture is used in PyCharm.
+
+Currently supported formats are:
+
+* `relative` (default) this is the original behavior of vulture before this feature was added
+* `absolute` absolute file path
+
+additional formats my be added in the future
+
+### vulture inside PyCharm
+
+Reference test platform: *macOS 10.14 (Mojave), anaconda python distribution, PyCharm Community 2019.3*
+
+Assumes:
+
+* vulture installed in your (virtual) python environment
+* the same (virtual) environment configured into your PyCharm project settings
+
+Navigate from **PyCharm** menu -> **Preferences** -> **Tools** -> **External Tools**
+
+**Add a new tool** using the PLUS (+) icon
+
+Suggested Settings:
+
+* Name: `vulture`
+
+* Group: `External Tools`
+
+* Description: `dead code identification`
+
+* Tool Settings / Program: `$PyInterpreterDirectory$/python`
+
+* Tool Settings / Arguments: `-m vulture --path-format absolute $FilePath$`
+
+* Tool Settings / Working directory: `$ProjectFileDir$`
+
+* Select all checkboxes under Advanced Options
+
+* Add these Output Filters:
+  * `$FILE_PATH$\:$LINE$\:$COLUMN$\:.*`
+  * `$FILE_PATH$\:$LINE$\:.*`
+
+Save the settings
+
 ## Examples
 
 Consider the following Python script (`dead_code.py`):
@@ -209,6 +258,24 @@ 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.
 
+**Absolute Paths**
+
+Calling:
+
+```
+$ vulture --path-format absolute dead_code.py
+```
+
+results in output similar to the following, depending on your exact path:
+
+```
+/Users/<user>/PycharmProjects/vulture/dead_code.py:1: unused import 'os' (90% confidence)
+/Users/<user>/PycharmProjects/vulture/dead_code.py:4: unused function 'greet' (60% confidence)
+/Users/<user>/PycharmProjects/vulture/dead_code.py:8: unused variable 'message' (60% confidence)
+```
+
+
+
 **Preparing whitelists**
 
 In a whitelist we simulate the usage of variables, attributes, etc. For

tests/test_config.py

@@ -27,6 +27,7 @@ def test_cli_args():
         ignore_names=["name1", "name2"],
         make_whitelist=True,
         min_confidence=10,
+        path_format="relative",
         sort_by_size=True,
         verbose=True,
     )
@@ -39,6 +40,7 @@ def test_cli_args():
             "--min-confidence=10",
             "--sort-by-size",
             "--verbose",
+            "--path-format=relative",
             "path1",
             "path2",
         ]
@@ -60,6 +62,7 @@ def test_toml_config():
         min_confidence=10,
         sort_by_size=True,
         verbose=True,
+        path_format="relative",
     )
     data = StringIO(
         dedent(
@@ -73,6 +76,7 @@ def test_toml_config():
         sort_by_size = true
         verbose = true
         paths = ["path1", "path2"]
+        path_format = "relative"
         """
         )
     )
@@ -97,6 +101,7 @@ def test_config_merging():
         min_confidence = 10
         sort_by_size = false
         verbose = false
+        path_format = "relative"
         paths = ["toml_path"]
         """
         )
@@ -108,6 +113,7 @@ def test_config_merging():
         "--make-whitelist",
         "--min-confidence=20",
         "--sort-by-size",
+        "--path-format=relative",
         "--verbose",
         "cli_path",
     ]
@@ -120,6 +126,7 @@ def test_config_merging():
         make_whitelist=True,
         min_confidence=20,
         sort_by_size=True,
+        path_format="relative",
         verbose=True,
     )
     assert result == expected

tests/test_utils.py

@@ -1,7 +1,34 @@
 import ast
+from pathlib import Path, PurePath
 
 from vulture import utils
 
+PATH_FORMATTERS = {
+    "relative": utils.RelativePathFormat(),
+    "absolute": utils.AbsolutePathFormat(),
+}
+
+
+def check_paths(filename, format_name="relative"):
+    assert format_name in PATH_FORMATTERS
+    # only checks relative vs absolute right now
+    pathstr = PATH_FORMATTERS[format_name].m_format_path(Path(filename))
+    # platform dependencies and path types need to be accounted for
+    pure_path = PurePath(pathstr)
+    check = pure_path.is_absolute()
+    if format_name == "absolute":
+        assert check
+    # even if absolute == True, the path might have been specified absolute
+    # so can't conclude negatively
+
+
+def test_absolute_path():
+    check_paths(__file__, format_name="absolute")
+
+
+def test_relative_path():
+    check_paths(__file__, format_name="relative")
+
 
 def check_decorator_names(code, expected_names):
     decorator_names = []

vulture/config.py

@@ -20,6 +20,7 @@
     "make_whitelist": False,
     "sort_by_size": False,
     "verbose": False,
+    "path_format": "relative",
 }
 
 
@@ -69,6 +70,7 @@ def _parse_toml(infile):
         make_whitelist = true
         min_confidence = 10
         sort_by_size = true
+        path_format = relative
         verbose = true
         paths = ["path1", "path2"]
     """
@@ -149,6 +151,14 @@ def csv(exclude):
         default=missing,
         help="Sort unused functions and classes by their lines of code.",
     )
+    parser.add_argument(
+        "--path-format",
+        type=str,
+        action="store",
+        default="relative",
+        required=False,
+        help="Specify path format.",
+    )
     parser.add_argument(
         "-v", "--verbose", action="store_true", default=missing
     )