janitor Setuptools Extension¶
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
andbdist*
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?¶
Setting up your environment¶
The easiest way to start working with this code is to set up a virtual
environment and run env/bin/pip install -q '.[dev]'
. That will install
the necessary testing and development tools. Then you can run everything
else using env/bin/python setup.py
:
- setup.py nosetest will run the tests using nose to test against the and generate a coverage report to stdout.
- setup.py build_sphinx will generate HTML documentation into build/doc/html. This is the doc set that is uploaded to Read The Docs.
- setup.py flake8 will run the
flake8
utility and report on any static code analysis failures.
Changelog¶
- 1.1.2 (23-Nov-2019)
- 1.1.1 (07-May-2019)
- Fix
Requires-Python
metadata.
- Fix
- 1.1.0 (07-May-2019)
- Drop support for Python 2.6, and 3.0-3.4
- Move version and version_info from the janitor module into the top-level package. Also renamed __version__ to version
- Remove namespace packaging (thanks @ionelmc)
- Fix distribution cleanup on Windows (thanks @maphew)
- Clean up .eggs as well as .egg (thanks @maphew)
- Switch from pypip.in to shields.io (thanks @movermeyer)
- 1.0.0 (19-Nov-2014)
- Support removal of virtual environment directories.
- Support recursive removal of __pycache__ directories.
- Add support for –all.
- Support removal of .egg-info and .egg directories.
- Add support for –dry-run
- Support removal of distribution directories.