Rooba
/
pipdeptree
mirror of https://github.com/tox-dev/pipdeptree.git
1
1
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve README for upcoming beta release

This commit is contained in:
Vineet Naik 2020-06-13 00:58:22 +05:30
parent 2081fa33ba
commit edd9eb8f7a
1 changed files with 91 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

153
README.rst
View File

@ -12,13 +12,11 @@ installed globally on a machine as well as in a virtualenv. Since
which are the top level packages and which packages do they depend on which are the top level packages and which packages do they depend on
requires some effort. It can also be tedious to resolve conflicting requires some effort. It can also be tedious to resolve conflicting
dependencies because ``pip`` doesn't have true dependency resolution dependencies because ``pip`` doesn't have true dependency resolution
yet. Looks like soon it will get `one yet [1]_. ``pipdeptree`` can help here by identifying conflicting
<https://github.com/pypa/pip/issues/6536>`_) but until then this dependencies installed in the environment.
utility tries to solve this problem of finding conflicting package
installs.
To some extent, this tool is inspired by ``lein deps :tree`` command To some extent, ``pipdeptree`` is inspired by the ``lein deps :tree``
of `Leiningen <http://leiningen.org/>`_. command of `Leiningen <http://leiningen.org/>`_.
Installation Installation
@ -28,24 +26,24 @@ Installation
$ pip install pipdeptree $ pip install pipdeptree
This will install the latest stable version of ``pipdeptree`` which is This will install the latest stable version which is ``0.13.2``. This
``0.13.2``. This version works well for the basic use case but has version works well for the basic use case but has many flaws and
many flaws and limitations. limitations.
Work on an improved version is in progress, which you can install from Work on an improved version is in progress and you can install it from
the ``v2beta`` branch, the ``v2beta`` branch as follows,
.. code-block:: bash .. code-block:: bash
$ sudo pip install git+https://git@github.com/naiquevin/pipdeptree.git@v2beta#egg=v2beta $ sudo pip install git+https://git@github.com/naiquevin/pipdeptree.git@v2beta#egg=v2beta
The current stable version is tested with 2.7, 3.4, 3.5 and 3.6. The current stable version is tested with ``2.7``, ``3.4``, ``3.5`` and ``3.6``.
The ``v2beta`` branch has been tested with Python 3.4, 3.5, 3.6, 3.7, The ``v2beta`` branch has been tested with Python ``3.4``, ``3.5``, ``3.6``, ``3.7``,
3.8 as well as 2.7. ``3.8`` as well as ``2.7``.
While Python 2.6 is way past it's end of life, if at all you need to Python ``2.6`` is way past it's end of life but if you ever find
run it on a legacy environment, use version ``0.9.0``. yourself stuck on a legacy environment, you can use version ``0.9.0``.
Usage and examples Usage and examples
@ -91,9 +89,9 @@ Is it possible to find out why a particular package is installed?
`New in ver. 0.5.0` `New in ver. 0.5.0`
Yes, there's a `--reverse` (or simply `-r`) flag for this. To find out Yes, there's a ``--reverse`` (or simply ``-r``) flag for this. To find
what all packages require paricular package(s), it can be combined out what all packages require particular package(s), it can be
with `--packages` flag as follows: combined with ``--packages`` flag as follows:
.. code-block:: bash .. code-block:: bash
@ -116,17 +114,18 @@ As seen in the above output, ``pipdeptree`` by default warns about
possible conflicting dependencies. Any package that's specified as a possible conflicting dependencies. Any package that's specified as a
dependency of multiple packages with a different version is considered dependency of multiple packages with a different version is considered
as a possible conflicting dependency. Conflicting dependencies are as a possible conflicting dependency. Conflicting dependencies are
possible due to pip's `lack of doesn't have true dependency resolution possible due to pip's `lack of true dependency resolution
<https://github.com/pypa/pip/issues/988>`_. The warning is printed to <https://github.com/pypa/pip/issues/988>`_ [1]_. The warning is
stderr instead of stdout and it can be completely silenced by using printed to stderr instead of stdout and it can be completely silenced
the ``-w silence`` or ``--warn silence`` flag. On the other hand, it by specifying the ``-w silence`` or ``--warn silence`` flag. On the
can be made mode strict with ``--warn fail`` in which case the command other hand, it can be made mode strict with ``--warn fail`` in which
will not only print the warnings to stderr but also exit with a case the command will not only print the warnings to stderr but also
non-zero status code. This could be useful if you want to fit this exit with a non-zero status code. This could be useful if you want to
tool into your CI pipeline. fit this tool into your CI pipeline.
**Note** The ``--warn`` flag was added in version ``0.6.0``. If you **Note** The ``--warn`` flag was added in version ``0.6.0``. If you
are using an older version, use ``--nowarn`` flag. are using an older version, use ``--nowarn`` flag to silence the
warnings.
Warnings about circular dependencies Warnings about circular dependencies
@ -189,16 +188,14 @@ lost. To fix this, ``pipdeptree`` must be run with a ``-f`` or
$ pipdeptree -f --warn silence | grep -E '^[a-zA-Z0-9\-]+' > requirements.txt $ pipdeptree -f --warn silence | grep -E '^[a-zA-Z0-9\-]+' > requirements.txt
Note that the ``-E`` works for BSD grep on MacOS. if you're on
linux, you'll need to use ``grep -P`` instead.
The freeze flag will also not output the hyphens for child The freeze flag will also not output the hyphens for child
dependencies, so you could dump the complete output of ``pipdeptree dependencies, so you could dump the complete output of ``pipdeptree
-f`` to the requirements.txt file making the file human-friendly (due -f`` to the requirements.txt file making the file human-friendly (due
to indentations) as well as pip-friendly. (Take care of duplicate to indentations) as well as pip-friendly.
dependencies though)
$ pipfreeze -f .. code-block:: bash
$ pipdeptree -f | tee locked-requirements.txt
Flask==0.10.1 Flask==0.10.1
itsdangerous==0.24 itsdangerous==0.24
Jinja2==2.11.2 Jinja2==2.11.2
@ -211,9 +208,17 @@ dependencies though)
setuptools==47.1.1 setuptools==47.1.1
wheel==0.34.2 wheel==0.34.2
If there are no conflicting dependencies, then you can treat this as a Once confirming that there are no conflicting dependencies, you can
"lock" file. There will be duplicate entries in the file but ``pip even treat this as a "lock file" where all packages, including the
install`` handles that. transient dependencies will be pinned to the currently installed
versions. Note that the ``locked-requirements.txt`` file could end up
with duplicate entries. Although ``pip install`` wouldn't complain
about that, you can avoid duplicate lines at the cost of losing
indentation,
.. code-block:: bash
$ pipdeptree -f | sed 's/ //g' | sort -u > locked-requirements.txt
Using pipdeptree with external tools Using pipdeptree with external tools
@ -221,9 +226,9 @@ Using pipdeptree with external tools
`New in ver. 0.5.0` `New in ver. 0.5.0`
It's also possible to have pipdeptree output json representation of It's also possible to have ``pipdeptree`` output json representation
the dependency tree so that it may be used as input to other external of the dependency tree so that it may be used as input to other
tools. external tools.
.. code-block:: bash .. code-block:: bash
@ -231,7 +236,9 @@ tools.
Note that ``--json`` will output a flat list of all packages with Note that ``--json`` will output a flat list of all packages with
their immediate dependencies. This is not very useful in itself. To their immediate dependencies. This is not very useful in itself. To
obtain nested json, use ``--json-tree`` (added in version ``0.11.0``). obtain nested json, use ``--json-tree``
`New in ver. 0.11.0`
.. code-block:: bash .. code-block:: bash
@ -307,27 +314,42 @@ Usage
Known issues Known issues
------------ ------------
* To work with packages installed inside a virtualenv, pipdeptree also 1. To work with packages installed inside a virtualenv, pipdeptree
needs to be installed in the same virtualenv even if it's already also needs to be installed in the same virtualenv even if it's
installed globally. already installed globally.
2. Due to (1), the output of ``pipdeptree`` also includes
``pipdeptree`` itself as a dependency along with ``pip``,
``setuptools`` and ``wheel`` which get installed in the virtualenv
by default. To ignore them, use the ``--exclude`` option.
3. ``pipdeptree`` relies on the internal API of ``pip``. I fully
understand that it's a bad idea but it mostly works! On rare
occasions, it breaks when a new version of ``pip`` is out with
backward incompatible changes in internal API. So beware if you are
using this tool in environments in which ``pip`` version is
unpinned, specially automation or CD/CI pipelines.
Alternatives Limitations & Alternatives
------------ --------------------------
``pipdeptree`` doesn't do any dependency resolution. It merely looks ``pipdeptree`` merely looks at the installed packages in the current
at the installed packages in the current environment using pip and environment using pip, constructs the tree, then outputs it in the
generates the tree. If you are looking for a tool for generating the specified format. If you want to generate the dependency tree without
tree without installing the packages, then you need a dependency installing the packages, then you need a dependency resolver. You
resolver. You might want to check alternatives such as `pipgrip might want to check alternatives such as `pipgrip
<https://github.com/ddelange/pipgrip>`_ or `poetry <https://github.com/ddelange/pipgrip>`_ or `poetry
<https://github.com/python-poetry/poetry>`_ <https://github.com/python-poetry/poetry>`_.
Also, stay tuned for the dependency resolver in upcoming versions of
pip [1]_.
Runing Tests (for contributors) Runing Tests (for contributors)
------------------------------- -------------------------------
There are 2 test suites in pipdeptree: There are 2 test suites in this repo:
1. Unit tests that use mock objects. These are configured to run on 1. Unit tests that use mock objects. These are configured to run on
every push to the repo and on every PR thanks to travis.ci every push to the repo and on every PR thanks to travis.ci
@ -342,11 +364,11 @@ Unit tests can be run against all version of python using `tox
$ make test-tox-all $ make test-tox-all
This assumes that you have python versions 2.7, 3.4, 3.5, 3.6, 3.7, This assumes that you have python versions specified in the
3.8 installed on your machine. (See more: ``tox.ini``) ``tox.ini`` file.
Or if you don't want to install all the versions of python but want to If you don't want to install all the versions of python but want to
run tests quickly against Python3.6 only: run tests quickly against ``Python3.6`` only:
.. code-block:: bash .. code-block:: bash
@ -361,12 +383,13 @@ with code coverage as follows,
On the other hand, end-to-end tests actually create virtualenvs, On the other hand, end-to-end tests actually create virtualenvs,
install packages and then run tests against them. These tests are more install packages and then run tests against them. These tests are more
reliable in the sense that they also test pipdeptree with the latest reliable in the sense that they also test ``pipdeptree`` with the
version of pip and setuptools (unpinned dependencies). latest version of ``pip`` and ``setuptools``.
The downside is that when new versions of pip and setuptools are The downside is that when new versions of ``pip`` or ``setuptools``
released, these need to be updated. At present the process is manual are released, these need to be updated. At present the process is
but I have plans to setup nightly builds for these for faster feedback. manual but I have plans to setup nightly builds for these for faster
feedback.
Release checklist Release checklist
@ -389,3 +412,9 @@ License
------- -------
MIT (See `LICENSE <./LICENSE>`_) MIT (See `LICENSE <./LICENSE>`_)
Footnotes
---------
.. [1] Soon we'll have `a dependency resolver in pip itself
<https://github.com/pypa/pip/issues/6536>`_