[Checkins] SVN: zc.buildout/branches/documentation/doc/system-python-virtualenv-and-buildout.rest Initial version of runyaga's tutorial.

[Hector Edwardo Velade Diaz]

Log message for revision 122991:
  Initial version of runyaga's tutorial.

Changed:
  A   zc.buildout/branches/documentation/doc/system-python-virtualenv-and-buildout.rest

-=-
Added: zc.buildout/branches/documentation/doc/system-python-virtualenv-and-buildout.rest
===================================================================
--- zc.buildout/branches/documentation/doc/system-python-virtualenv-and-buildout.rest	                        (rev 0)
+++ zc.buildout/branches/documentation/doc/system-python-virtualenv-and-buildout.rest	2011-09-28 21:35:21 UTC (rev 122991)
@@ -0,0 +1,142 @@
+System Python, Virtualenv and Buildout
+--------------------------------------
+
+This document explains why installing Python packages (eggs) in your
+system-level Python is not recommended during the software development
+lifecycle. It will also provide an overview of the benefits and drawbacks of
+virtualenv and Buildout. Virtualenv [#]_ and Buildout are two approaches for
+isolating and reproducing a python environment in a repeatable fashion. The
+aim of this document is to reduce the evaluation time required to understand
+the differences of these technologies.
+
+"easy_install" [#]_ provides a mechanism to install a Python package (a.k.a.
+"egg") into a Python environment. By using easy_install with your system-level
+Python the package will be available system wide. Both virtualenv and Buildout
+provide facilities to isolate a Python package (egg) installation so packages
+are not available system wide.
+
+Here are some reasons for isolate egg installation:
+
+  * You may not have write access to the main Python environment
+  
+  * You want to experiment with a egg but not pollute your main Python
+    environment
+
+  * There is no easy way to differentiate eggs which have been installed in
+    the Python environment by yourself or by system-level package installers
+    (Ã  la Red Hat).
+  
+  * While developing in Python you may depend on a system-level Python
+    package. Someone consuming your software may not have the required system
+    library or worse may have an incompatible version of this required
+    library. Isolation ensures you can capture all requirements for your
+    package.
+
+Package/egg isolation are design goals of both virtualenv and Buildout.
+Buildout's design allows for isolation but, unlike virtualenv isolation, is
+not buildout's primary goal. Let's install both environments and look at how
+they work. 
+
+You will need curl and version 2.4 of Python or later. Do not install Python
+3.0 or higher at this point. You should download binary versions:
+
+  * curl with SSL can be downloaded from http://curl.haxx.se/download.html
+
+  * Python can be downloaded from http://python.org/download/
+  
+Let's create a sandbox with virtualenv and install 2 eggs, nose and mock.
+
+On Linux::
+
+  ~$ curl --insecure -O https://raw.github.com/pypa/virtualenv/master/virtualenv.py
+  ~$ python virtualenv.py myvirtualenv
+  ~$ cd myvirtualenv
+  ~/myvirtualenv$ bin/pip install nose mock
+
+On Windows::
+
+  C:\Users\runyaga> curl --insecure -O https://raw.github.com/pypa/virtualenv/master/virtualenv.py
+  C:\Users\runyaga> C:\Python27\python virtualenv.py --no-site-packages myvirtualenv
+  C:\Users\runyaga> cd myvirtualenv
+  C:\Users\runyaga\myvirtualenv> bin\pip install nose mock
+
+You now have a sandboxed Python environment in the directory "myvirtualenv".
+Installing new eggs in virtualenv is accomplished by running
+myvirtualenv/bin/pip. The myvirtualenv/bin/python is a copy of the Python
+interpreter you used to execute virtualenv.py script. You can see nose and
+mock packages inside of myvirtualenv/Lib/python/site-packages directory.
+
+Now, install buildout.
+
+On Linux::
+
+  ~$ mkdir mybuildout
+  ~$ cd mybuildout
+  ~/mybuildout$ curl -O http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py
+  ~/mybuildout$ python -S bootstrap.py -d init nose mock ./src
+
+On Windows::
+
+  C:\Users\runyaga> mkdir mybuildout
+  C:\Users\runyaga> cd mybuildout
+  C:\Users\runyaga\mybuildout> curl -O http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py
+  C:\Users\runyaga\mybuildout> C:\Python27\python bootstrap.py -S init nose mock ./src
+
+You now have a Buildout configuration file, buildout.cfg and an associated
+structure in your directory "mybuildout" which was generated by
+mybuildout/bin/buildout. The above bootstrap.py usage is a shortcut to
+generate a config file (buildout.cfg) which bin/buildout uses to assembly the
+environment. The normal process is edit .cfg file and re-run buildout which
+re-generates the sandbox.  
+
+If you look at the buildout.cfg you will see::
+
+  [buildout]
+  parts = py
+  
+  [py]
+  recipe = zc.recipe.egg
+  eggs = nose
+         mock
+  interpreter = python
+  extra-paths = ./src
+
+Another tutorial will describe the buildout configuration file and how the
+recipe eco-system will make your life easier.
+
+Now that you have virtualenv and buildout installed you can start your
+experimentation.
+
+Let's conclude this overview with a technical comparison between the two
+sandbox approaches:
+
+virtualenv clones your Python interpreter binary into a new directory and
+creates a Python library directory structure. Installing packages and working
+with python is identical to working with the system-level Python. Pip is used
+to install/remove packages from your virtualenv. Pip also has a feature which
+will generate a .txt file which can be used to re-create a isolated
+environment with those eggs installed.
+
+Buildout does not clone your intrepreter. Buildout creates a directory
+structure and scripts (.cfg driven) which may be used for a wider set of tasks
+[#]_ such as compiling C extensions[#]_ (e.g. configure; make; make install).
+You do not install eggs into buildout directly. You edit a .cfg file and
+re-run buildout which will add the packages to script paths (e.g.
+mybuildout/bin/nosetests). At any point you can regenerate your sandbox with
+the .cfg file. mybuildout/bin/python script puts eggs into sys.path
+explicitly; edit the mybuildout/bin/python (on Linux) or
+mybuildout/bin/python-script.py (on Windows).  
+
+In conclusion if you want to isolate your Python environment you can use
+either virtualenv or Buildout. If you work with a mix of C (development
+libraries) and Python you will want to use Buildout. Once you invest the time
+into understanding buildout you can pick and choose from the 300+ recipes in
+PyPI. Nowadays it is very unlikely you will need to create a recipe from
+scratch.
+
+.. [#] What virtualenv Does. http://www.virtualenv.org/en/latest/index.html#what-it-does
+.. [#] Distribute is a setuptools fork.  http://packages.python.org/distribute/setuptools.html
+.. [#] Buildout recipes at PYthon Package Index (Pypi) http://bit.ly/buildout_recipes
+.. [#] zc.recipe.cmmi handles configure, make, make install for C extensions
+   http://pypi.python.org/pypi/zc.recipe.cmmi
+