janitor Setuptools Extension
============================

|Version| |Downloads| |Status| |License|

Extends the ``clean`` command to remove stuff generated by the
development process.

Wait... Why? What??
-------------------
So ``setup.py clean`` is useful for developers of C extensions or
anything else that takes advantage of the ``setup.py build`` command.
Pure Python packages generate their own set of artifacts that clutter
up the source tree.  This package extends the clean command so that
it removes the following artifacts as well:

* The distribution directory as generated by the ``sdist`` and ``bdist*``
  commands
* Top-level *.egg-info* and *.egg* directories that *setup.py* creates
* Local virtual environment directories
* *__pycache__* directories

I come from a C/C++ background where the *Makefile* usually provide house
keeping targets such as *clean*, *dist-clean*, and *maintainer-clean*.
This extension is inspired by the same desire for a clean working
environment.

Installation
~~~~~~~~~~~~
The ``setuptools`` package contains a number of interesting ways in which
it can be extended.  If you develop Python packages, then you can include
extension packages using the ``setup_requires`` and ``cmdclass`` keyword
parameters to the ``setup`` function call.  This is a little more
difficult than it should be since the ``setupext`` package needs to be
imported into *setup.py* so that it can be passed as a keyword parameter
**before** it is downloaded.  The easiest way to do this is to catch the
``ImportError`` that happens if it is not already downloaded::

   import setuptools
   try:
      from setupext import janitor
      CleanCommand = janitor.CleanCommand
   except ImportError:
      CleanCommand = None

   cmd_classes = {}
   if CleanCommand is not None:
      cmd_classes['clean'] = CleanCommand

   setup(
      # normal parameters
      setup_requires=['setupext.janitor'],
      cmdclass=cmd_classes,
   )

You can use a different approach if you are simply a developer that wants
to have this functionality available for your own use, then you can install
it into your working environment.  This package installs itself into the
environment as a `distutils extension`_ so that it is available to any
*setup.py* script as if by magic.

Usage
~~~~~
Once the extension is installed, the ``clean`` command will accept a
few new command line parameters.

``setup.py clean --dist``
   Removes directories that the various *dist* commands produce.

``setup.py clean --egg``
   Removes *.egg* and *.egg-info* directories.

``setup.py clean --environment``
   Removes the currently active virtual environment as indicated by the
   ``$VIRTUAL_ENV`` environment variable.  The name of the directory can
   also be specified using the ``--virtualenv-dir`` command line option.

``setup.py clean --pycache``
   Recursively removes directories named *__pycache__*.

``setup.py clean --all``
   Remove all of by-products.  This is the same as using ``--dist --egg
   --environment --pycache``.

Where can I get this extension from?
------------------------------------
+---------------+-----------------------------------------------------+
| Source        | https://github.com/dave-shawley/setupext-janitor    |
+---------------+-----------------------------------------------------+
| Status        | https://travis-ci.org/dave-shawley/setupext-janitor |
+---------------+-----------------------------------------------------+
| Download      | https://pypi.python.org/pypi/setupext-janitor       |
+---------------+-----------------------------------------------------+
| Documentation | http://setupext-janitor.readthedocs.org/en/latest   |
+---------------+-----------------------------------------------------+
| Issues        | https://github.com/dave-shawley/setupext-janitor    |
+---------------+-----------------------------------------------------+

.. _distutils extension: https://pythonhosted.org/setuptools/setuptools.html
   #extending-and-reusing-setuptools
.. _setuptools: https://pythonhosted.org/setuptools/

.. |Version| image:: https://badge.fury.io/py/setupext-janitor.svg?
   :target: https://badge.fury.io/
.. |Downloads| image:: https://pypip.in/d/setupext-janitor/badge.svg?
   :target: https://pypi.python.org/pypi/setupext-janitor
.. |Status| image:: https://travis-ci.org/dave-shawley/setupext-janitor.svg
   :target: https://travis-ci.org/dave-shawley/setupext-janitor
.. |License| image:: https://pypip.in/license/setupext-janitor/badge.svg?
   :target: https://setupext-janitor.readthedocs.org/
