Package: pydeps
Python module dependency visualization.This package is primarily intended to be used from the command line through thepydepscommand.ContentsHow to installUsageExampleNotesConfiguration filesBacon (Scoring)Import cyclesClusteringMaximum module depthGraph directionCollapsing target packageIntermediate formatVersion historyContributingFeature requests and bug reports:Please report bugs and feature requests on GitHub athttps://github.com/thebjorn/pydeps/issuesHow to installpip install pydepsTo create graphs withpydepsyou also need to installGraphviz. Please follow the
installation instructions provided in the Graphviz link (and make
sure thedotcommand is on your path).Usageusage: 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]
              [--show-cycles] [--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]
              fnamepositional arguments:fname                 filenameoptional arguments:-h,--helpshow this help message and exit--debugturn on all the show and verbose options (mainly for debugging pydeps itself)--configFILEspecify config file--no-configdisable processing of config files--versionprint pydeps version-LLOG,--logLOGset log-level to one of CRITICAL, ERROR, WARNING, INFO, DEBUG, NOTSET.--find-packagetries to automatically find the name of the current package.-v,--verbosebe more verbose (-vv, -vvv for more verbosity)-ofilewrite output to ‘file’-TFORMAToutput format (svg|png)--displayPROGRAMprogram to use to display the graph (png or svg file depending on the T parameter)--noshow,--no-showdon’t call external program to display graph--show-depsshow output of dependency analysis--show-raw-depsshow output of dependency analysis before removing skips--deps-outputwrite output of dependency analysis to file (instead of screen)--show-dotshow output of dot conversion--dot-outputwrite dot code to file (instead of screen)--nodot,--no-dotskip dot conversion--no-outputdon’t create .svg/.png file, implies –no-show (-t/-o will be ignored)--show-cyclesshow only import cycles--debug-mfINTset the ModuleFinder.debug flag to this value--noise-levelINTexclude sources or sinks with degree greater than noise-level--max-baconINTexclude nodes that are more than n hops away (default=2, 0 -> infinite)--max-module-depthINTcoalesce deep modules to at most n levels--pylibinclude python std lib modules--pylib-allinclude python all std lib modules (incl. C modules)--include-missinginclude modules that are not installed (or can’t be found on sys.path)--onlyMODULE_PATHonly include modules that start with MODULE_PATH, multiple paths can be provided--externalscreate list of direct external dependencies--reversedraw arrows to (instead of from) imported modules--rankdirset 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)--clusterdraw external dependencies as separate clusters--min-cluster-sizeINTthe minimum number of nodes a dependency must have before being clustered (default=0)--max-cluster-sizeINTthe maximum number of nodes a dependency can have before the cluster is collapsed to a single node (default=0)--keep-target-clusterdraw target module as a cluster--collapse-target-clustercollapse target module (this implies –cluster)--rmprefixPREFIXremove PREFIX from the displayed name of the nodes (multiple prefixes can be provided)-xPATTERN,--excludePATTERNinput files to skip (e.g.foo.*), multiple patterns can be provided--exclude-exactMODULE(shorthand -xx MODULE) same as –exclude, except requires the full match.-xx foo.barwill exclude foo.bar, but not foo.bar.blobNote:if an option with a variable number of arguments (like-x) is provided
beforefname, separate the arguments from the filename with--otherwisefnamewill be parsed as an argument of the option. Example:$ pydeps-xos sys--pydeps.You can of course also importpydepsfrom Python and use it as a library, look intests/test_relative_imports.pyfor examples.ExampleThis is the result of runningpydepson itself (pydeps pydeps):(full disclosure: this is for an early version of pydeps)Notespydeps finds imports by looking for import-opcodes in
python bytecodes (think.pycfiles). 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-missingflag.Displaying the graph:To display the resulting.svgor.pngfiles,pydepsby default
calls an appropriate opener for the platform, likexdg-openfoo.svg.This can be overridden with the--displayPROGRAMoption, wherePROGRAMis an
executable that can display the image file of the graph.You can also export the name of such a viewer in either thePYDEPS_DISPLAYorBROWSERenvironment variable, which changes the default behaviour
when--displayis not used.Configuration filesAll options can also be set in a.pydepsfile using.inifile
syntax (parsable byConfigParser). Command line options override
options in the.pydepsfile in the current directory, which again
overrides options in the user’s home directory
(%USERPROFILE%\.pydepson Windows and${HOME}/.pydepsotherwise).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 inpyproject.toml(under[tool.pydeps]) andsetup.cfg(under[pydeps]).Bacon (Scoring)pydepsalso 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--max-bacon2(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:Import cyclespydepscan detect and display cycles with the--show-cyclesparameter.  This will _only_ display the cycles, and for big libraries
it is not a particularly fast operation.  Given a folder with the
following contents (this uses yaml to define a directory structure,
like in the tests):relimp:
    - __init__.py
    - a.py: |
        from . import b
    - b.py: |
        from . import apydeps relimp--show-cyclesdisplays:ClusteringRunningpydeps pydeps –max-bacon=4on version 1.8.0 of pydeps gives the following graph:If you are not interested in the internal structure of external modules, you can add the--clusterflag, which
will collapse external modules into folder-shaped objects:shell> pydeps pydeps --max-bacon=4 --clusterTo see the internal structure _and_ delineate external modules, use the--max-cluster-sizeflag, which controls
how many nodes can be in a cluster before it is collapsed to a folder icon:shell> pydeps pydeps --max-bacon=4 --cluster --max-cluster-size=1000or, using a smaller max-cluster-size:shell> pydeps pydeps --max-bacon=4 --cluster --max-cluster-size=3To remove clusters with too few nodes, use the--min-cluster-sizeflag:shell> pydeps pydeps --max-bacon=4 --cluster --max-cluster-size=3 --min-cluster-size=2In some situations it can be useful to draw the target module as a cluster:shell> pydeps pydeps --max-bacon=4 --cluster --max-cluster-size=3 --min-cluster-size=2 --keep-target-cluster..and since the cluster boxes include the module name, we can remove those prefixes:shell> pydeps pydeps --max-bacon=4 --cluster --max-cluster-size=3 --min-cluster-size=2 --keep-target-cluster --rmprefix pydeps. stdlib_list.Maximum module depthFor Python packages that have a module structure more than two levels deep, the graph can easily become overwhelmingly complex.
Use the--max-module-depth=nflag to examine the internal dependencies of a package while limiting the module depth
(private and testing-related modules are removed to further simplify the graph using-x...):shell> pydeps pandas --only pandas --max-module-depth=2 -x pandas._* pandas.test* pandas.conftestGraph directionThe direction of the graph can be specified using the--rankdirflag.Top to bottom (default):shell> pydeps pydeps --rankdir TBBottom to top:shell> pydeps pydeps --rankdir BTLeft to right:shell> pydeps pydeps --rankdir LRRight to left:shell> pydeps pydeps --rankdir RLCollapsing target packageWhen internal target package dependencies are unimportant, they can be collapsed using the--collapse-target-clusterflag. This option also implies--cluster:shell> pydeps pydeps --collapse-target-clusterIntermediate formatAn attempt has been made to keep the intermediate formats readable,
eg. the output frompydeps--show-deps..looks like this:...
"pydeps.mf27": {
    "imported_by": [
        "__main__",
        "pydeps.py2depgraph"
    ],
    "kind": "imp.PY_SOURCE",
    "name": "pydeps.mf27",
    "path": "pydeps\\mf27.py"
},
"pydeps.py2depgraph": {
    "imported_by": [
        "__main__",
        "pydeps.pydeps"
    ],
    "imports": [
        "pydeps.depgraph",
        "pydeps.mf27"
    ],
    "kind": "imp.PY_SOURCE",
    "name": "pydeps.py2depgraph",
    "path": "pydeps\\py2depgraph.py"
}, ...Version historyVersion 1.12.13Better docs for larger packages.
Seemaximum_module_depthfor an example.
Thanks tosheromonfor the PR.Version 1.12.5Pydeps can now read configuration data frompyproject.toml.
Thanks toseptatrixfor pushing the idea and for countering my toml-rant with
an informative argument.Version 1.11.0drop support for Python 3.6.
Thanks topawamoyfor removing imports of the deprecatedimpmodule.
(Parts of it has been vendorized due to a Python bug, see the code for details.)Version 1.10.1Thanks tovector400for a new option--rankdirwhich
renders the graph in different directions.Version 1.10.0supports Python 3.10.Version 1.9.15Thanks toPipeline Foundationfor a very much improved CI
pipeline, and a CD pipeline as well.Version 1.9.14Thanks toponeillfor fixing a cryptic error message when
run in a directory without an__init__.pyfile.Version 1.9.13Thanks toglumiaandSimonBiggsfor improving the documentation.Version 1.9.10no_showis now honored when placed in.pydepsfile.
Thanks toromain-dartiguesfor the PR.Version 1.9.8Fix formaximum recursion depth exceededwhen using large
frameworks (likesympy).  Thanks totanujkhattarfor finding the fix and tobalopatfor reporting it.Version 1.9.7CheckPYDEPS_DISPLAYandBROWSERfor a program to open
the graph, PR byjhermannVersion 1.9.1graphs are now stable on Python 3.x as well -
this was already the case for Py2.7 (thanks topawamoyfor reporting
and testing the issue and tokinowfor helping with testing).Version 1.9.0supports Python 3.8.Version 1.8.7includes a new flag--rmprefixwhich lets you remove
prefixes from the node-labels in the graph. The _name_ of the nodes are not effected
so this does not cause merging of nodes, nor does it change coloring - but it
can lead to multiple nodes with the same label (hovering over the node will
give the full name). Thanks toarobergefor the enhancement request.Version 1.8.5With svg as the output format (which is the default),
paths are now hilighted on mouse hover (thanks totomasito665for the
enhancement request).Version 1.8.2incldes a new flag--onlythat causes pydeps to
only report on the paths specified:shell> pydeps mypackage --only mypackage.a mypackage.bVersion 1.8.0includes 4 new flags for drawing external dependencies as
clusters. Seeclusteringfor examples.
Additionally, the arrowheads now have the color of the source node.Version 1.7.3includes a new flag-xxor--exclude-exactwhich
matches the functionality of the--excludeflag, except it requires an
exact match, i.e.-xxfoo.barwill exclude foo.bar, but notfoo.bar.blob(thanks toAvenzaOlegfor the PR).Version 1.7.2includes a new flag,--no-output, which prevents
creation of the .svg/.png file.Version 1.7.1fixes excludes in .pydeps files (thanks toeqvisfor the bug report).Version 1.7.0The new--reverseflag reverses the direction
of the arrows in the dependency graph, so they point _to_ the imported
module instead of _from_ the imported module (thanks togoetzkfor
the bug report andtobiasmaierfor the PR!).Version 1.5.0Python 3 support (thanks toeight04for the PR).Version 1.3.4--externalswill now include modules that
haven’t been installed (whatmodulefindercallsbadmodules).Version 1.2.8A shortcut for finding the direct external dependencies
of a package was added:pydeps --externals mypackagewhich will print a json formatted list of module names to the screen, e.g.:(dev) go|c:\srv\lib\dk-tasklib> pydeps --externals dktasklib
[
    "dkfileutils"
]which means that thedktasklibpackage only depends on thedkfileutilspackage.This functionality is also available programmatically:import os
from pydeps.pydeps import externals
# the directory that contains setup.py (one level up from actual package):
os.chdir('package-directory')
print externals('mypackage')Version 1.2.5:The defaults are now sensible, such that:shell> pydeps mypackagewill likely do what you want. It is the same aspydeps--show--max-bacon=2mypackagewhich means display the
dependency graph in your browser, but limit it to two hops (which
includes only the modules that your module imports – not continuing
down the import chain).  The old default behavior is available withpydeps--noshow--max-bacon=0mypackage.ContributingFork itIt is appreciated (but not required) if you raise an issue first:https://github.com/thebjorn/pydeps/issuesCreate your feature branch (git checkout -b my-new-feature)Commit your changes (git commit -am ‘Add some feature’)Push to the branch (git push origin my-new-feature)Create new Pull Request