Pip Requ
========

A set of command line tools to help you keep your pip-based packages
fresh, even when you've pinned them.  `You do pin them, right?`__

__ http://nvie.com/posts/pin-your-packages

Pip Requ is a fork of pip-tools_ by Vincent Driessen.

.. _pip-tools: https://github.com/nvie/pip-tools

Installation
------------

.. code::

   $ pip install --upgrade pip  # Pip Requ needs pip==8.0 or higher
   $ pip install pip-requ


Example usage for ``pip-requ compile``
--------------------------------------

Suppose you have a Flask project, and want to pin it for production.
Write the following line to a file:

.. code::

   # requirements.in
   Flask

Now, run ``pip-requ compile requirements.in``:

.. code::

   $ pip-requ compile requirements.in
   #
   # This file is autogenerated by pip-requ compile
   # Make changes in requirements.in, then run this to update:
   #
   #    pip-requ compile requirements.in
   #
   flask==0.10.1
   itsdangerous==0.24        # via flask
   jinja2==2.7.3             # via flask
   markupsafe==0.23          # via jinja2
   werkzeug==0.10.4          # via flask

And it will produce your ``requirements.txt``, with all the Flask
dependencies (and all underlying dependencies) pinned.  Put this file
under version control as well.

To update all packages, periodically re-run ``pip-requ compile
--upgrade``.

To update a specific package to the latest or a specific version use the
``--upgrade-package`` or ``-P`` flag:

.. code::

   pip-requ compile --upgrade-package flask
     # only update the flask package
   pip-requ compile --upgrade-package flask --upgrade-package requests
     # update both the flask and requests packages
   pip-requ compile -P flask -P requests==2.0.0
     # update the flask package to the latest, and requests to v2.0.0


Example usage for ``pip-requ sync``
-----------------------------------

Now that you have a ``requirements.txt``, you can use ``pip-requ sync``
to update your virtual env to reflect exactly what's in there.  Note:
this will install/upgrade/uninstall everything necessary to match the
``requirements.txt`` contents.

.. code::

   $ pip-requ sync
   Uninstalling flake8-2.4.1:
     Successfully uninstalled flake8-2.4.1
   Collecting click==4.1
     Downloading click-4.1-py2.py3-none-any.whl (62kB)
       100% |████████████████████████████████| 65kB 1.8MB/s
     Found existing installation: click 4.0
       Uninstalling click-4.0:
         Successfully uninstalled click-4.0
   Successfully installed click-4.1


To sync multiple ``*.txt`` dependency lists, just pass them in via command
line arguments e.g.::

   $ pip-requ sync dev-requirements.txt requirements.txt

Passing in empty arguments would cause it to default to
``requirements.txt``.
