Merge github.com:pypa/virtualenv into develop

.travis.yml

@@ -7,20 +7,22 @@ env:
   - TOXENV=py33
   - TOXENV=py34
   - TOXENV=pypy
+  - TOXENV=pypy3
+  - TOXENV=docs
 
-install:
-  - "if [[ $TOXENV == 'py34' ]]; then .travis/py34.sh; fi"
-  - pip install tox
+install: pip install tox
 
 script: tox
 
 branches:
   only:
     - master
     - develop
-    - 1.9.X
-    - 1.10.X
     - 1.11.X
 
 notifications:
-  irc: "irc.freenode.org#pip"
+  irc:
+    channels:
+      - "irc.freenode.org#pypa-dev"
+    use_notice: true
+    skip_join: true

CONTRIBUTING.rst

@@ -0,0 +1,21 @@
+virtualenv
+==========
+
+See docs/index.rst for user documentation.
+
+Contributor notes
+-----------------
+
+* virtualenv is designed to work on python 2 and 3 with a single code base.
+  Use Python 3 print-function syntax, and always ``use sys.exc_info()[1]``
+  inside the ``except`` block to get at exception objects.
+
+* virtualenv uses git-flow_ to `coordinate development`_. The latest stable
+  version should exist on the *master* branch, and new work should be
+  integrated to *develop*.
+
+* All changes to files inside virtualenv_embedded should be integrated to
+  ``virtualenv.py`` with ``bin/rebuild-script.py``.
+
+.. _git-flow: https://github.com/nvie/gitflow
+.. _coordinate development: http://nvie.com/posts/a-successful-git-branching-model/

README.rst

@@ -7,4 +7,4 @@ virtualenv
 .. image:: https://secure.travis-ci.org/pypa/virtualenv.png?branch=develop
    :target: http://travis-ci.org/pypa/virtualenv
 
-For documentation, see http://www.virtualenv.org/
+For documentation, see https://virtualenv.pypa.io/

docs/news.rst → docs/changes.rst

@@ -1,19 +1,45 @@
-Changes & News
---------------
+Release History
+===============
 
-.. warning::
+12.1.0 (unreleased)
+~~~~~~~~~~~~~~~~~~~
+
+12.0.2 (2014-12-23)
+~~~~~~~~~~~~~~~~~~~
+
+* Upgraded pip to 6.0.2
+
+12.0.1 (2014-12-22)
+~~~~~~~~~~~~~~~~~~~
+
+* Upgraded pip to 6.0.1
 
-   Python bugfix releases 2.6.8, 2.7.3, 3.1.5 and 3.2.3 include a change that
-   will cause "import random" to fail with "cannot import name urandom" on any
-   virtualenv created on a Unix host with an earlier release of Python
-   2.6/2.7/3.1/3.2, if the underlying system Python is upgraded. This is due to
-   the fact that a virtualenv uses the system Python's standard library but
-   contains its own copy of the Python interpreter, so an upgrade to the system
-   Python results in a mismatch between the version of the Python interpreter
-   and the version of the standard library. It can be fixed by removing
-   ``$ENV/bin/python`` and re-running virtualenv on the same target directory
-   with the upgraded Python.
 
+12.0 (2014-12-22)
+~~~~~~~~~~~~~~~~~
+
+* **PROCESS** Version numbers are now simply ``X.Y`` where the leading ``1``
+  has been dropped.
+* Split up documentation into structured pages
+* Now using pytest framework
+* Correct sys.path ordering for debian, issue #461
+* Correctly throws error on older Pythons, issue #619
+* Allow for empty $PATH, pull #601
+* Don't set prompt if $env:VIRTUAL_ENV_DISABLE_PROMPT is set for Powershell
+* Updated setuptools to 7.0
+
+1.11.6 (2014-05-16)
+~~~~~~~~~~~~~~~~~~~
+
+* Updated setuptools to 3.6
+* Updated pip to 1.5.6
+
+1.11.5 (2014-05-03)
+~~~~~~~~~~~~~~~~~~~
+
+* Updated setuptools to 3.4.4
+* Updated documentation to use https://virtualenv.pypa.io/
+* Updated pip to 1.5.5
 
 1.11.4 (2014-02-21)
 ~~~~~~~~~~~~~~~~~~~
@@ -197,7 +223,7 @@ Changes & News
   Branden Rolston.
 
 * Fix a bug in the config option parser that prevented setting negative
-  options with environemnt variables. Thanks Ralf Schmitt.
+  options with environment variables. Thanks Ralf Schmitt.
 
 * Allow setting ``--no-site-packages`` from the config file.
 
@@ -333,7 +359,7 @@ Changes & News
 * Updated embedded pip release to 1.0.2.
 
 * Fixed #141 - Be smarter about finding pkg_resources when using the
-  non-default Python intepreter (by using the ``-p`` option).
+  non-default Python interpreter (by using the ``-p`` option).
 
 * Fixed #112 - Fixed path in docs.
 

docs/conf.py

@@ -83,13 +83,14 @@
 # given in html_static_path.
 #html_style = 'default.css'
 
-if os.environ.get('DOCS_LOCAL'):
-    import sphinx_rtd_theme
-    html_theme = "sphinx_rtd_theme"
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-else:
-    # on RTD
-    html_theme = 'default'
+html_theme = 'default'
+if not on_rtd:
+    try:
+        import sphinx_rtd_theme
+        html_theme = 'sphinx_rtd_theme'
+        html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+    except ImportError:
+        pass
 
 
 # Add any paths that contain custom static files (such as style sheets) here,

docs/development.rst

@@ -0,0 +1,61 @@
+Development
+===========
+
+Contributing
+------------
+
+Refer to the `pip development`_ documentation - it applies equally to
+virtualenv, except that virtualenv issues should filed on the `virtualenv
+repo`_ at GitHub.
+
+Virtualenv's release schedule is tied to pip's -- each time there's a new pip
+release, there will be a new virtualenv release that bundles the new version of
+pip.
+
+Files in the `virtualenv_embedded/` subdirectory are embedded into
+`virtualenv.py` itself as base64-encoded strings (in order to support
+single-file use of `virtualenv.py` without installing it). If your patch
+changes any file in `virtualenv_embedded/`, run `bin/rebuild-script.py` to
+update the embedded version of that file in `virtualenv.py`; commit that and
+submit it as part of your patch / pull request.
+
+.. _pip development: http://www.pip-installer.org/en/latest/development.html
+.. _virtualenv repo: https://github.com/pypa/virtualenv/
+
+Running the tests
+-----------------
+
+Virtualenv's test suite is small and not yet at all comprehensive, but we aim
+to grow it.
+
+The easy way to run tests (handles test dependencies automatically)::
+
+    $ python setup.py test
+
+If you want to run only a selection of the tests, you'll need to run them
+directly with pytest instead. Create a virtualenv, and install required
+packages::
+
+    $ pip install pytest mock
+
+Run pytest::
+
+    $ pytest
+
+Or select just a single test file to run::
+
+    $ pytest tests/test_virtualenv
+
+Status and License
+------------------
+
+``virtualenv`` is a successor to `workingenv
+<http://cheeseshop.python.org/pypi/workingenv.py>`_, and an extension
+of `virtual-python
+<http://peak.telecommunity.com/DevCenter/EasyInstall#creating-a-virtual-python>`_.
+
+It was written by Ian Bicking, sponsored by the `Open Planning
+Project <http://openplans.org>`_ and is now maintained by a
+`group of developers <https://github.com/pypa/virtualenv/raw/master/AUTHORS.txt>`_.
+It is licensed under an
+`MIT-style permissive license <https://github.com/pypa/virtualenv/raw/master/LICENSE.txt>`_.

docs/index.rst

@@ -1,18 +1,137 @@
-
-virtualenv
+Virtualenv
 ==========
 
-`Changes & News <news.html>`_ |
 `Mailing list <http://groups.google.com/group/python-virtualenv>`_ |
 `Issues <https://github.com/pypa/virtualenv/issues>`_ |
 `Github <https://github.com/pypa/virtualenv>`_ |
 `PyPI <https://pypi.python.org/pypi/virtualenv/>`_ |
-IRC: #pip
+User IRC: #pypa
+Dev IRC: #pypa-dev
 
-.. comment: split here
+Introduction
+------------
+
+``virtualenv`` is a tool to create isolated Python environments.
+
+The basic problem being addressed is one of dependencies and versions,
+and indirectly permissions. Imagine you have an application that
+needs version 1 of LibFoo, but another application requires version
+2. How can you use both these applications?  If you install
+everything into ``/usr/lib/python2.7/site-packages`` (or whatever your
+platform's standard location is), it's easy to end up in a situation
+where you unintentionally upgrade an application that shouldn't be
+upgraded.
 
+Or more generally, what if you want to install an application *and
+leave it be*?  If an application works, any change in its libraries or
+the versions of those libraries can break the application.
+
+Also, what if you can't install packages into the global
+``site-packages`` directory?  For instance, on a shared host.
+
+In all these cases, ``virtualenv`` can help you. It creates an
+environment that has its own installation directories, that doesn't
+share libraries with other virtualenv environments (and optionally
+doesn't access the globally installed libraries either).
+
+.. comment: split here
 
 .. toctree::
    :maxdepth: 2
 
-   virtualenv
+   installation
+   userguide
+   reference
+   development
+   changes
+
+.. warning::
+
+   Python bugfix releases 2.6.8, 2.7.3, 3.1.5 and 3.2.3 include a change that
+   will cause "import random" to fail with "cannot import name urandom" on any
+   virtualenv created on a Unix host with an earlier release of Python
+   2.6/2.7/3.1/3.2, if the underlying system Python is upgraded. This is due to
+   the fact that a virtualenv uses the system Python's standard library but
+   contains its own copy of the Python interpreter, so an upgrade to the system
+   Python results in a mismatch between the version of the Python interpreter
+   and the version of the standard library. It can be fixed by removing
+   ``$ENV/bin/python`` and re-running virtualenv on the same target directory
+   with the upgraded Python.
+
+Other Documentation and Links
+-----------------------------
+
+* `Blog announcement of virtualenv`__.
+
+  .. __: http://blog.ianbicking.org/2007/10/10/workingenv-is-dead-long-live-virtualenv/
+
+* James Gardner has written a tutorial on using `virtualenv with
+  Pylons
+  <http://wiki.pylonshq.com/display/pylonscookbook/Using+a+Virtualenv+Sandbox>`_.
+
+* Chris Perkins created a `showmedo video including virtualenv
+  <http://showmedo.com/videos/video?name=2910000&fromSeriesID=291>`_.
+
+* Doug Hellmann's `virtualenvwrapper`_ is a useful set of scripts to make
+  your workflow with many virtualenvs even easier. `His initial blog post on it`__.
+  He also wrote `an example of using virtualenv to try IPython`__.
+
+  .. _virtualenvwrapper: https://pypi.python.org/pypi/virtualenvwrapper/
+  .. __: http://www.doughellmann.com/articles/CompletelyDifferent-2008-05-virtualenvwrapper/index.html
+  .. __: http://www.doughellmann.com/articles/CompletelyDifferent-2008-02-ipython-and-virtualenv/index.html
+
+* `Pew`_ is another wrapper for virtualenv that makes use of a different
+  activation technique.
+
+  .. _Pew: https://pypi.python.org/pypi/pew/
+
+* `Using virtualenv with mod_wsgi
+  <http://code.google.com/p/modwsgi/wiki/VirtualEnvironments>`_.
+
+* `virtualenv commands
+  <https://github.com/thisismedium/virtualenv-commands>`_ for some more
+  workflow-related tools around virtualenv.
+
+* PyCon US 2011 talk: `Reverse-engineering Ian Bicking's brain: inside pip and virtualenv
+  <http://pyvideo.org/video/568/reverse-engineering-ian-bicking--39-s-brain--insi>`_.
+  By the end of the talk, you'll have a good idea exactly how pip
+  and virtualenv do their magic, and where to go looking in the source
+  for particular behaviors or bug fixes.
+
+Compare & Contrast with Alternatives
+------------------------------------
+
+There are several alternatives that create isolated environments:
+
+* ``workingenv`` (which I do not suggest you use anymore) is the
+  predecessor to this library. It used the main Python interpreter,
+  but relied on setting ``$PYTHONPATH`` to activate the environment.
+  This causes problems when running Python scripts that aren't part of
+  the environment (e.g., a globally installed ``hg`` or ``bzr``). It
+  also conflicted a lot with Setuptools.
+
+* `virtual-python
+  <http://peak.telecommunity.com/DevCenter/EasyInstall#creating-a-virtual-python>`_
+  is also a predecessor to this library. It uses only symlinks, so it
+  couldn't work on Windows. It also symlinks over the *entire*
+  standard library and global ``site-packages``. As a result, it
+  won't see new additions to the global ``site-packages``.
+
+  This script only symlinks a small portion of the standard library
+  into the environment, and so on Windows it is feasible to simply
+  copy these files over. Also, it creates a new/empty
+  ``site-packages`` and also adds the global ``site-packages`` to the
+  path, so updates are tracked separately. This script also installs
+  Setuptools automatically, saving a step and avoiding the need for
+  network access.
+
+* `zc.buildout <http://pypi.python.org/pypi/zc.buildout>`_ doesn't
+  create an isolated Python environment in the same style, but
+  achieves similar results through a declarative config file that sets
+  up scripts with very particular packages. As a declarative system,
+  it is somewhat easier to repeat and manage, but more difficult to
+  experiment with. ``zc.buildout`` includes the ability to setup
+  non-Python systems (e.g., a database server or an Apache instance).
+
+I *strongly* recommend anyone doing application development or
+deployment use one of these tools.