setupext-janitor

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/