Managing python installations ----------------------------- virtualenv ~~~~~~~~~~ The basic building block for Python-based components is creation of virtualenvs (to separate package installations from each other): .. code-block:: python self += VirtualEnv('2.7') .. py:class:: batou.lib.python.VirtualEnv(version) Creates a virtualenv for the given Python version in the working directory of the parent component. (Requires that ``pythonX.Y`` is in the ``PATH``) .. py:attribute:: executable Full path to the Python executable to create the virtualenv for (default: ``pythonX.Y`` based on the version attribute). batou downloads a compatible version of `virtualenv`_ (depending on the Python version you need) to ensure everything works as expected and to avoid problems with incompatibilities or unexpected behaviours of whatever version might be installed already on the system. (virtualenv base installations are shared by all components for creating new virtualenvs, it is installed to ``work/.virtualenv``). .. _`virtualenv`: http://virtualenv.org/ Installing packages ~~~~~~~~~~~~~~~~~~~ Python packages are installed from a package index such as `PyPI`_. batou uses `pip`_ or easy_install for this purpose (but that actually is an implementation detail and depends on the specifics of the Python and virtualenv version). Packages must be added to a virtual environment. .. _`PyPI`: https://pypi.python.org/ .. _`pip`: http://www.pip-installer.org/ .. code-block:: python venv = VirtualEnv('2.7') self += venv venv += Package('Sphinx', version='1.1.3') .. py:class:: batou.lib.python.Package(package) Install the Python package with the given name into the virtualenv of the parent component. Using :py:class:`Package` requires that it is added to a :py:class:`~batou.lib.python.VirtualEnv` instance. .. py:attribute:: version The version of the package to install (**required**). .. py:attribute:: install_options List of options that are passed to pip/easy_install on the command line. [Default: depends on the Python/virtualenv version in use] .. py:attribute:: check_package_is_module Verify that the package is installed by trying to ``import`` it (more precisely, the first component of its dotted name). This is a stopgap against https://github.com/pypa/pip/issues/3, but should be pretty safe to disable if it causes trouble for specific packages (``distribute`` is a notable example, since it installs a Python module named ``setuptools``). [Default: True] .. py:attribute:: timeout A timeout (in seconds) that the installer should use to limit stalling network activity. Only works when using ``pip``. [Default: equal to the environment's timeout setting] .. py:attribute:: dependencies Whether only the package itself or its dependencies should be installed. [Default: True] zc.buildout ~~~~~~~~~~~ batou has in-depth support for managing installations that use buildout. It automatically wraps them in a virtualenv, installs the appropriate buildout version, and takes care of running buildout whenever changes to configuration files makes it necessary. A typical usage example: .. code-block:: python self += Buildout(python='3.7', version='2.2', setuptools='1.0', pip='21.1', additional_config=[Directory('profiles', source='profiles')]) .. py:class:: batou.lib.buildout.Buildout() Manage a buildout installation .. py:attribute:: python Python version (**required**) .. py:attribute:: executable Full path to the python executable to create the virtualenv for (used instead of ``pythonX.Y``). .. py:attribute:: version Version of zc.buildout to install (**required**) .. py:attribute:: setuptools Version of setuptools to install into the virtualenv (must be appropriate to the buildout version, e.g. since 2.2 buildout requires setuptools, but some versions before that required distribute) (**required**) .. py:attribute:: pip Version of pip to install into the virtualenv (must be appropriate to the buildout version). .. py:attribute:: distribute Version of distribute to install into the virtualenv. Mutually exclusive with :py:attr:`setuptools`, of course. .. py:attribute:: config If a different configuration file name than ``buildout.cfg`` should be used, pass in a :py:attr:`~batou.lib.file.File` or :py:attr:`Component` instance. .. py:attribute:: additional_config Optional list of component instances (e.g. :py:attr:`~batou.lib.file.File` or :py:attr:`~batou.lib.file.Directory`) that contain further configuration files (so :py:attr:`~batou.lib.buildout.Buildout` knows when running buildout is needed).