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.  The simplest way to use this extension is to install
it into the environment and use it.  The package extends the ``clean``
command by installing a `distutils extension`_::

   $ pip install -q 'setupext-janitor'
   $ ./setup.py clean --dist --eggs
   running clean
   removing './my_package.egg-info' (and everything under it)
   removing 'dist' (and everything under it)

You can also install the command from within your *setup.py* 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_janitor`` 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_janitor 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,
      entry_points={
         # normal parameters, ie. console_scripts[]
         'distutils.commands': [
            ' clean = setupext_janitor.janitor:CleanCommand']
         }
   )

This approach **is not recommended** since the ``install_requires`` keyword
will install ``setupext_janitor`` into a target environment when installing
your package from a source distribution.  Not to mention that amount of
gynmastics required to safely use it from within *setup.py*,

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

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

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

``setup.py clean --eggs``
   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.org/project/setupext-janitor           |
+---------------+-----------------------------------------------------+
| Documentation | http://setupext-janitor.readthedocs.io/en/latest    |
+---------------+-----------------------------------------------------+
| Issues        | https://github.com/dave-shawley/setupext-janitor    |
+---------------+-----------------------------------------------------+

.. _distutils extension: https://setuptools.readthedocs.io/en/latest
   /setuptools.html#extending-and-reusing-setuptools
.. _setuptools: https://setuptools.readthedocs.io/en/latest/

.. |Version| image:: https://img.shields.io/pypi/v/setupext-janitor.svg?
   :target: https://pypi.org/project/setupext-janitor/
.. |Downloads| image:: https://img.shields.io/pypi/dm/setupext-janitor.svg
   :target: https://pypi.org/project/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://img.shields.io/github/license/dave-shawley/setupext-janitor.svg
   :target: https://setupext-janitor.readthedocs.io/
