Implement --output to centralize choosing an output format (#519)

Resolves #349.

Author: kemzeb

README.md

@@ -221,42 +221,47 @@ In earlier versions, `--json`, `--json-tree` and `--graph-output` options overri
 
 ## Usage
 
-```bash
+```text
 % pipdeptree --help
-usage: pipdeptree [-h] [-v] [-w [{silence,suppress,fail}]] [--python PYTHON] [--path PATH] [-p P] [-e P] [-l | -u] [-f] [--encoding E] [-a] [-d D] [-r] [--license] [-j | --json-tree | --mermaid | --graph-output FMT]
+usage: pipdeptree [-h] [-v] [-w {silence,suppress,fail}] [--python PYTHON] [--path PATH] [-p P] [-e P] [--exclude-dependencies] [-l | -u] [-f] [--encoding E] [-a] [-d D] [-r] [--license]
+                  [-j | --json-tree | --mermaid | --graph-output FMT | -o FMT]
 
 Dependency tree of the installed python packages
 
 options:
   -h, --help          show this help message and exit
   -v, --version       show program's version number and exit
-  -w [{silence,suppress,fail}], --warn [{silence,suppress,fail}]
+  -w {silence,suppress,fail}, --warn {silence,suppress,fail}
                       warning control: suppress will show warnings but return 0 whether or not they are present; silence will not show warnings at all and always return 0; fail will show warnings and return 1 if any are present (default:
                       suppress)
 
 select:
   choose what to render
 
   --python PYTHON     Python interpreter to inspect. With "auto", it attempts to detect your virtual environment and fails if it can't. (default: /usr/local/bin/python)
-  --path PATH         Passes a path used to restrict where packages should be looked for (can be used multiple times) (default: None)
+  --path PATH         passes a path used to restrict where packages should be looked for (can be used multiple times) (default: None)
   -p P, --packages P  comma separated list of packages to show - wildcards are supported, like 'somepackage.*' (default: None)
   -e P, --exclude P   comma separated list of packages to not show - wildcards are supported, like 'somepackage.*'. (cannot combine with -p or -a) (default: None)
+  --exclude-dependencies
+                      used along with --exclude to also exclude dependencies of packages (default: False)
   -l, --local-only    if in a virtualenv that has global access do not show globally installed packages (default: False)
   -u, --user-only     only show installations in the user site dir (default: False)
 
 render:
-  choose how to render the dependency tree (by default will use text mode)
+  choose how to render the dependency tree
 
-  -f, --freeze        print names so as to write freeze files (default: False)
+  -f, --freeze        (Deprecated, use -o) print names so as to write freeze files (default: False)
   --encoding E        the encoding to use when writing to the output (default: utf-8)
   -a, --all           list all deps at top level (text and freeze render only) (default: False)
   -d D, --depth D     limit the depth of the tree (text and freeze render only) (default: inf)
   -r, --reverse       render the dependency tree in the reverse fashion ie. the sub-dependencies are listed with the list of packages that need them under them (default: False)
   --license           list the license(s) of a package (text render only) (default: False)
-  -j, --json          raw JSON - this will yield output that may be used by external tools (default: False)
-  --json-tree         nested JSON - mimics the text format layout (default: False)
-  --mermaid           https://mermaid.js.org flow diagram (default: False)
-  --graph-output FMT  Graphviz rendering with the value being the graphviz output e.g.: dot, jpeg, pdf, png, svg (default: None)
+  -j, --json          (Deprecated, use -o) raw JSON - this will yield output that may be used by external tools (default: False)
+  --json-tree         (Deprecated, use -o) nested JSON - mimics the text format layout (default: False)
+  --mermaid           (Deprecated, use -o) https://mermaid.js.org flow diagram (default: False)
+  --graph-output FMT  (Deprecated, use -o) Graphviz rendering with the value being the graphviz output e.g.: dot, jpeg, pdf, png, svg (default: None)
+  -o FMT, --output FMT
+                      specify how to render the tree; supported formats: freeze, json, json-tree, mermaid, text, or graphviz-* (e.g. graphviz-png, graphviz-dot) (default: text)
 ```
 
 ## Known issues

src/pipdeptree/__main__.py

@@ -5,7 +5,7 @@
 import sys
 from typing import TYPE_CHECKING
 
-from pipdeptree._cli import get_options
+from pipdeptree._cli import Options, get_options
 from pipdeptree._detect_env import detect_active_interpreter
 from pipdeptree._discovery import InterpreterQueryError, get_installed_distributions
 from pipdeptree._models import PackageDAG
@@ -23,8 +23,7 @@ def main(args: Sequence[str] | None = None) -> int | None:
     options = get_options(args)
 
     # Warnings are only enabled when using text output.
-    is_text_output = not any([options.json, options.json_tree, options.output_format])
-    if not is_text_output:
+    if not _is_text_output(options):
         options.warn = "silence"
     warning_printer = get_warning_printer()
     warning_printer.warning_type = WarningType.from_str(options.warn)
@@ -72,6 +71,12 @@ def main(args: Sequence[str] | None = None) -> int | None:
     return _determine_return_code(warning_printer)
 
 
+def _is_text_output(options: Options) -> bool:
+    if any([options.json, options.json_tree, options.graphviz_format, options.mermaid]):
+        return False
+    return options.output_format in {"freeze", "text"}
+
+
 def _determine_return_code(warning_printer: WarningPrinter) -> int:
     return 1 if warning_printer.has_warned_with_failure() else 0
 

src/pipdeptree/_cli.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import sys
-from argparse import ArgumentDefaultsHelpFormatter, ArgumentParser, Namespace
+from argparse import ArgumentDefaultsHelpFormatter, ArgumentParser, ArgumentTypeError, Namespace
 from typing import TYPE_CHECKING, cast
 
 from .version import __version__
@@ -25,12 +25,17 @@ class Options(Namespace):
     json: bool
     json_tree: bool
     mermaid: bool
-    output_format: str | None
+    graphviz_format: str | None
+    output_format: str
     depth: float
     encoding: str
     license: bool
 
 
+# NOTE: graphviz-* has been intentionally left out. Users of this var should handle it separately.
+ALLOWED_RENDER_FORMATS = ["freeze", "json", "json-tree", "mermaid", "text"]
+
+
 class _Formatter(ArgumentDefaultsHelpFormatter):
     def __init__(self, prog: str) -> None:
         super().__init__(prog, max_help_position=22, width=240)
@@ -63,7 +68,7 @@ def build_parser() -> ArgumentParser:
     )
     select.add_argument(
         "--path",
-        help="Passes a path used to restrict where packages should be looked for (can be used multiple times)",
+        help="passes a path used to restrict where packages should be looked for (can be used multiple times)",
         action="append",
     )
     select.add_argument(
@@ -81,7 +86,7 @@ def build_parser() -> ArgumentParser:
     )
     select.add_argument(
         "--exclude-dependencies",
-        help="Used along with --exclude to also exclude dependencies of packages",
+        help="used along with --exclude to also exclude dependencies of packages",
         action="store_true",
     )
 
@@ -96,9 +101,11 @@ def build_parser() -> ArgumentParser:
 
     render = parser.add_argument_group(
         title="render",
-        description="choose how to render the dependency tree (by default will use text mode)",
+        description="choose how to render the dependency tree",
+    )
+    render.add_argument(
+        "-f", "--freeze", action="store_true", help="(Deprecated, use -o) print names so as to write freeze files"
     )
-    render.add_argument("-f", "--freeze", action="store_true", help="print names so as to write freeze files")
     render.add_argument(
         "--encoding",
         dest="encoding",
@@ -139,41 +146,79 @@ def build_parser() -> ArgumentParser:
         "--json",
         action="store_true",
         default=False,
-        help="raw JSON - this will yield output that may be used by external tools",
+        help="(Deprecated, use -o) raw JSON - this will yield output that may be used by external tools",
     )
     render_type.add_argument(
         "--json-tree",
         action="store_true",
         default=False,
-        help="nested JSON - mimics the text format layout",
+        help="(Deprecated, use -o) nested JSON - mimics the text format layout",
     )
     render_type.add_argument(
         "--mermaid",
         action="store_true",
         default=False,
-        help="https://mermaid.js.org flow diagram",
+        help="(Deprecated, use -o) https://mermaid.js.org flow diagram",
     )
     render_type.add_argument(
         "--graph-output",
         metavar="FMT",
+        dest="graphviz_format",
+        help="(Deprecated, use -o) Graphviz rendering with the value being the graphviz output e.g.:\
+              dot, jpeg, pdf, png, svg",
+    )
+    render_type.add_argument(
+        "-o",
+        "--output",
+        metavar="FMT",
         dest="output_format",
-        help="Graphviz rendering with the value being the graphviz output e.g.: dot, jpeg, pdf, png, svg",
+        type=_validate_output_format,
+        default="text",
+        help=f"specify how to render the tree; supported formats: {', '.join(ALLOWED_RENDER_FORMATS)}, or graphviz-*\
+            (e.g. graphviz-png, graphviz-dot)",
     )
     return parser
 
 
 def get_options(args: Sequence[str] | None) -> Options:
     parser = build_parser()
     parsed_args = parser.parse_args(args)
+    options = cast("Options", parsed_args)
 
-    if parsed_args.exclude_dependencies and not parsed_args.exclude:
+    options.output_format = _handle_legacy_render_options(options)
+
+    if options.exclude_dependencies and not options.exclude:
         return parser.error("must use --exclude-dependencies with --exclude")
-    if parsed_args.license and parsed_args.freeze:
+    if options.license and options.freeze:
         return parser.error("cannot use --license with --freeze")
-    if parsed_args.path and (parsed_args.local_only or parsed_args.user_only):
+    if options.path and (options.local_only or options.user_only):
         return parser.error("cannot use --path with --user-only or --local-only")
 
-    return cast("Options", parsed_args)
+    return options
+
+
+def _handle_legacy_render_options(options: Options) -> str:
+    if options.freeze:
+        return "freeze"
+    if options.json:
+        return "json"
+    if options.json_tree:
+        return "json-tree"
+    if options.mermaid:
+        return "mermaid"
+    if options.graphviz_format:
+        return f"graphviz-{options.graphviz_format}"
+
+    return options.output_format
+
+
+def _validate_output_format(value: str) -> str:
+    if value in ALLOWED_RENDER_FORMATS:
+        return value
+    if value.startswith("graphviz-"):
+        return value
+    msg = f'"{value}" is not a known output format. Must be one of {", ".join(ALLOWED_RENDER_FORMATS)}, or graphviz-*'
+    raise ArgumentTypeError(msg)
 
 
 __all__ = [

src/pipdeptree/_models/package.py

@@ -39,7 +39,7 @@ def licenses(self) -> str:
         except PackageNotFoundError:
             return self.UNKNOWN_LICENSE_STR
 
-        if license_str := dist_metadata.get("License-Expression"):
+        if license_str := dist_metadata[("License-Expression")]:
             return f"({license_str})"
 
         license_strs: list[str] = []

src/pipdeptree/_render/__init__.py

@@ -15,16 +15,17 @@
 
 
 def render(options: Options, tree: PackageDAG) -> None:
-    if options.json:
+    output_format = options.output_format
+    if output_format == "json":
         render_json(tree)
-    elif options.json_tree:
+    elif output_format == "json-tree":
         render_json_tree(tree)
-    elif options.mermaid:
+    elif output_format == "mermaid":
         render_mermaid(tree)
-    elif options.output_format:
-        render_graphviz(tree, output_format=options.output_format, reverse=options.reverse)
-    elif options.freeze:
+    elif output_format == "freeze":
         render_freeze(tree, max_depth=options.depth, list_all=options.all)
+    elif output_format.startswith("graphviz-"):
+        render_graphviz(tree, output_format=output_format[len("graphviz-") :], reverse=options.reverse)
     else:
         render_text(
             tree,

tests/_models/test_package.py

@@ -107,13 +107,13 @@ def test_dist_package_as_dict() -> None:
     ("mocked_metadata", "expected_output"),
     [
         pytest.param(
-            Mock(get=Mock(return_value=None), get_all=Mock(return_value=[])),
+            Mock(__getitem__=Mock(return_value=None), get_all=Mock(return_value=[])),
             Package.UNKNOWN_LICENSE_STR,
             id="no-license",
         ),
         pytest.param(
             Mock(
-                get=Mock(return_value=None),
+                __getitem__=Mock(return_value=None),
                 get_all=Mock(
                     return_value=[
                         "License :: OSI Approved :: GNU General Public License v2 (GPLv2)",
@@ -126,7 +126,7 @@ def test_dist_package_as_dict() -> None:
         ),
         pytest.param(
             Mock(
-                get=Mock(return_value=None),
+                __getitem__=Mock(return_value=None),
                 get_all=Mock(
                     return_value=[
                         "License :: OSI Approved :: GNU General Public License v2 (GPLv2)",
@@ -138,13 +138,13 @@ def test_dist_package_as_dict() -> None:
             id="more-than-one-license",
         ),
         pytest.param(
-            Mock(get=Mock(return_value="MIT"), get_all=Mock(return_value=[])),
+            Mock(__getitem__=Mock(return_value="MIT"), get_all=Mock(return_value=[])),
             "(MIT)",
             id="license-expression",
         ),
         pytest.param(
             Mock(
-                get=Mock(return_value="MIT"),
+                __getitem__=Mock(return_value="MIT"),
                 get_all=Mock(
                     return_value=[
                         "License :: OSI Approved :: MIT License",

tests/render/test_render.py

@@ -4,43 +4,51 @@
 from typing import TYPE_CHECKING
 from unittest.mock import ANY
 
+import pytest
+
 from pipdeptree.__main__ import main
 
 if TYPE_CHECKING:
     from pytest_mock import MockerFixture
 
 
-def test_json_routing(mocker: MockerFixture) -> None:
+@pytest.mark.parametrize("option", [["--json"], ["--output", "json"]])
+def test_json_routing(option: list[str], mocker: MockerFixture) -> None:
     render = mocker.patch("pipdeptree._render.render_json")
-    main(["--json"])
+    main(option)
     render.assert_called_once_with(ANY)
 
 
-def test_json_tree_routing(mocker: MockerFixture) -> None:
+@pytest.mark.parametrize("option", [["--json-tree"], ["--output", "json-tree"]])
+def test_json_tree_routing(option: list[str], mocker: MockerFixture) -> None:
     render = mocker.patch("pipdeptree._render.render_json_tree")
-    main(["--json-tree"])
+    main(option)
     render.assert_called_once_with(ANY)
 
 
-def test_mermaid_routing(mocker: MockerFixture) -> None:
+@pytest.mark.parametrize("option", [["--mermaid"], ["--output", "mermaid"]])
+def test_mermaid_routing(option: list[str], mocker: MockerFixture) -> None:
     render = mocker.patch("pipdeptree._render.render_mermaid")
-    main(["--mermaid"])
+    main(option)
     render.assert_called_once_with(ANY)
 
 
-def test_grahpviz_routing(mocker: MockerFixture) -> None:
+@pytest.mark.parametrize("option", [["--graph-output", "dot"], ["--output", "graphviz-dot"]])
+def test_grahpviz_routing(option: list[str], mocker: MockerFixture) -> None:
     render = mocker.patch("pipdeptree._render.render_graphviz")
-    main(["--graph-output", "dot"])
+    main(option)
     render.assert_called_once_with(ANY, output_format="dot", reverse=False)
 
 
-def test_text_routing(mocker: MockerFixture) -> None:
+@pytest.mark.parametrize("option", [[], ["--output", "text"]])
+def test_text_routing(option: list[str], mocker: MockerFixture) -> None:
     render = mocker.patch("pipdeptree._render.render_text")
-    main([])
+    main(option)
     render.assert_called_once_with(ANY, encoding="utf-8", max_depth=inf, list_all=False, include_license=False)
 
 
-def test_freeze_routing(mocker: MockerFixture) -> None:
+@pytest.mark.parametrize("option", [["--freeze"], ["--output", "freeze"]])
+def test_freeze_routing(option: list[str], mocker: MockerFixture) -> None:
     render = mocker.patch("pipdeptree._render.render_freeze")
-    main(["--freeze"])
+    main(option)
     render.assert_called_once_with(ANY, max_depth=inf, list_all=False)