pydeps

.. image:: https://readthedocs.org/projects/pydeps/badge/?version=latest :target: https://readthedocs.org/projects/pydeps/?badge=latest :alt: Documentation Status

.. image:: https://github.com/thebjorn/pydeps/actions/workflows/ci-cd.yml/badge.svg :target: https://github.com/thebjorn/pydeps/actions/workflows/ci-cd.yml

.. image:: https://codecov.io/gh/thebjorn/pydeps/branch/master/graph/badge.svg?token=VsYwrSFcJa :target: https://codecov.io/gh/thebjorn/pydeps

.. image:: https://pepy.tech/badge/pydeps :target: https://pepy.tech/project/pydeps :alt: Downloads

Python module dependency visualization.

This package is primarily intended to be used from the command line through the pydeps command.

.. contents:: :depth: 2

Feature requests and bug reports:

Please report bugs and feature requests on GitHub at https://github.com/thebjorn/pydeps/issues

How to install

::

pip install pydeps

To create graphs with pydeps you also need to install Graphviz_. Please follow the installation instructions provided in the Graphviz link (and make sure the dot command is on your path).

Usage

::

usage: pydeps [-h] [--debug] [--config FILE] [--no-config] [--version] [-L LOG]
              [--find-package] [-v] [-o file] [-T FORMAT] [--display PROGRAM]
              [--noshow] [--show-deps] [--show-raw-deps] [--deps-output DEPS_OUT]
              [--show-dot] [--dot-output DOT_OUT] [--nodot] [--no-output]
              [--debug-mf INT] [--noise-level INT]
              [--max-bacon INT] [--max-module-depth INT] [--pylib] [--pylib-all]
              [--include-missing] [-x PATTERN [PATTERN ...]]
              [-xx MODULE [MODULE ...]] [--only MODULE_PATH [MODULE_PATH ...]]
              [--externals] [--reverse] [--rankdir {TB,BT,LR,RL}] [--cluster]
              [--min-cluster-size INT] [--max-cluster-size INT]
              [--keep-target-cluster] [--collapse-target-cluster]
              [--rmprefix PREFIX [PREFIX ...]] [--start-color INT]
              fname

positional arguments:
  fname                 filename

optional arguments:
  -h, --help                             show this help message and exit
  --debug                                turn on all the show and verbose options (mainly for debugging pydeps itself)
  --config FILE                          specify config file
  --no-config                            disable processing of config files
  --version                              print pydeps version
  -L LOG, --log LOG                      set log-level to one of CRITICAL, ERROR, WARNING, INFO, DEBUG, NOTSET.
  --find-package                         tries to automatically find the name of the current package.
  -v, --verbose                          be more verbose (-vv, -vvv for more verbosity)
  -o file                                write output to 'file'
  -T FORMAT                              output format (svg|png)
  --display PROGRAM                      program to use to display the graph (png or svg file depending on the T parameter)
  --noshow, --no-show                    don't call external program to display graph
  --show-deps                            show output of dependency analysis
  --show-raw-deps                        show output of dependency analysis before removing skips
  --deps-output                          write output of dependency analysis to file (instead of screen)
  --show-dot                             show output of dot conversion
  --dot-output                           write dot code to file (instead of screen)
  --nodot, --no-dot                      skip dot conversion
  --no-output                            don't create .svg/.png file, implies --no-show (-t/-o will be ignored)
  --show-cycles                          [deprecated] show only import cycles
  --debug-mf INT                         set the ModuleFinder.debug flag to this value
  --noise-level INT                      exclude sources or sinks with degree greater than noise-level
  --max-bacon INT                        exclude nodes that are more than n hops away (default=2, 0 -> infinite)
  --max-module-depth INT                 coalesce deep modules to at most n levels
  --pylib                                include python std lib modules
  --pylib-all                            include python all std lib modules (incl. C modules)
  --include-missing                      include modules that are not installed (or can't be found on sys.path)
  --only MODULE_PATH                     only include modules that start with MODULE_PATH, multiple paths can be provided
  --externals                            create list of direct external dependencies
  --reverse                              draw arrows to (instead of from) imported modules
  --rankdir                              set the direction of the graph, legal values are TB (default, imported modules above importing modules), BT (opposite direction of TB), LR (left-to-right), and RL (right-to-left)
  --cluster                              draw external dependencies as separate clusters
  --min-cluster-size INT                 the minimum number of nodes a dependency must have before being clustered (default=0)
  --max-cluster-size INT                 the maximum number of nodes a dependency can have before the cluster is collapsed to a single node (default=0)
  --keep-target-cluster                  draw target module as a cluster
  --collapse-target-cluster              collapse target module (this implies --cluster)
  --rmprefix PREFIX                      remove PREFIX from the displayed name of the nodes (multiple prefixes can be provided)
  -x PATTERN, --exclude PATTERN          input files to skip (e.g. `foo.*`), multiple patterns can be provided
  --exclude-exact MODULE                 (shorthand -xx MODULE) same as --exclude, except requires the full match. `-xx foo.bar` will exclude foo.bar, but not foo.bar.blob

Note: if an option with a variable number of arguments (like -x) is provided before fname, separate the arguments from the filename with -- otherwise fname will be parsed as an argument of the option. Example: $ pydeps -x os sys -- pydeps.

Note: the --show-cycles option is deprecated and will be removed in a future release, cycles are now always shown.

You can of course also import pydeps from Python and use it as a library, look in tests/test_relative_imports.py for examples.

Example

This is the result of running pydeps on itself (pydeps pydeps):

.. image:: https://raw.githubusercontent.com/thebjorn/pydeps/master/docs/_static/pydeps.svg?sanitize=true

(full disclosure: this is for an early version of pydeps)

Notes

pydeps finds imports by looking for import-opcodes in python bytecodes (think .pyc files). Therefore, only imported files will be found (ie. pydeps will not look at files in your directory that are not imported). Additionally, only files that can be found using the Python import machinery will be considered (ie. if a module is missing or not installed, it will not be included regardless if it is being imported). This can be modified by using the --include-missing flag.

Displaying the graph:

To display the resulting .svg or .png files, pydeps by default calls an appropriate opener for the platform, like xdg-open foo.svg.

This can be overridden with the --display PROGRAM option, where PROGRAM is an executable that can display the image file of the graph.

You can also export the name of such a viewer in either the PYDEPS_DISPLAY or BROWSER environment variable, which changes the default behaviour when --display is not used.

Configuration files

All options can also be set in a .pydeps file using .ini file syntax (parsable by ConfigParser). Command line options override options in the .pydeps file in the current directory, which again overrides options in the user's home directory (%USERPROFILE%\.pydeps on Windows and ${HOME}/.pydeps otherwise).

An example .pydeps file::

[pydeps]
max_bacon = 2
no_show = True
verbose = 0
pylib = False
exclude =
    os
    re
    sys
    collections
    __future__

pydeps will also look for configuration data in pyproject.toml (under [tool.pydeps]) and setup.cfg (under [pydeps]).

Bacon (Scoring)

pydeps also contains an Erdős-like scoring function (a.k.a. Bacon number, from Six degrees of Kevin Bacon (http://en.wikipedia.org/wiki/Six_Degrees_of_Kevin_Bacon) that lets you filter out modules that are more than a given number of 'hops' away from the module you're interested in. This is useful for finding the interface a module has to the rest of the world.

To find pydeps' interface to the Python stdlib (less some very common modules).

::

shell> pydeps pydeps --show --max-bacon 2 --pylib -x os re types _* enum

.. image:: https://raw.githubusercontent.com/thebjorn/pydeps/master/docs/_static/pydeps-pylib.svg?sanitize=true

--max-bacon 2 (the default) gives the modules that are at most 2 hops away, and modules that belong together have similar colors. Compare that to the output with the --max-bacon=0 (infinite) filter:

.. image:: https://raw.githubusercontent.com/thebjorn/pydeps/master/docs/_static/pydeps-pylib-all.svg?sanitize=true :width: 40%

Import cycles

pydeps detects and displays cycles. Given a folder with the following contents (this uses yaml to define a directory structure, like in the tests)::

    cycles:
        __init__.py: ''
        a.py: from . import b
        b.py: fro