Skip to content

Commit 506da41

Browse files
miracle2kmiracle2k
committed
Merged upstream.
2 parents 0583721 + 5b6033a commit 506da41

19 files changed

+930
-58
lines changed

‎announce.rst

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
=======================
2-
virtualenvwrapper 2.8
2+
virtualenvwrapper 2.9
33
=======================
44

55
What is virtualenvwrapper
@@ -11,14 +11,25 @@ virtual environments and otherwise managing your development workflow,
1111
making it easier to work on more than one project at a time without
1212
introducing conflicts in their dependencies.
1313

14-
What's New in 2.8
14+
What's New in 2.9
1515
=================
1616

17-
This release includes a fix to make ``cpvirtualenv`` use the copy of
18-
``virtualenv`` specified by the ``VIRTUALENVWRAPPER_VIRTUALENV``
19-
variable. It also adds support for running the wrapper commands under
20-
the MSYS environment on Microsoft Windows systems (contributed by
21-
noirbizarre).
17+
This release merges in the project directory management features
18+
previously delivered separately as ``virtualenvwrapper.project``. The
19+
new command ``mkproject`` creates a working directory associated with
20+
a virtualenv, and can apply templates to populate the directory (for
21+
example, to create a new Django site).
22+
23+
This release also adds a ``-r`` option to ``mkvirtualenv`` to specify
24+
a pip requirements file for packages that should be installed into the
25+
new environment after is is created.
26+
27+
Upgrading to 2.9
28+
================
29+
30+
Version 2.9 includes the features previously delivered separately by
31+
``virtualenvwrapper.project``. If you have an older verison of the
32+
project extensions installed, remove them before upgrading.
2233

2334
.. _virtualenv: http://pypi.python.org/pypi/virtualenv
2435

‎docs/en/command_ref.rst

Lines changed: 107 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,11 @@ Create a new environment, in the WORKON_HOME.
2222

2323
Syntax::
2424

25-
mkvirtualenv [options] ENVNAME
25+
mkvirtualenv [-r requirements_file] [virtualenv options] ENVNAME
2626

27-
All command line options are passed directly to ``virtualenv``. The
28-
new environment is automatically activated after being initialized.
27+
All command line options except ``-r`` and ``-h`` are passed directly
28+
to ``virtualenv``. The new environment is automatically activated
29+
after being initialized.
2930

3031
::
3132

@@ -40,10 +41,17 @@ new environment is automatically activated after being initialized.
4041
mynewenv
4142
(mynewenv)$
4243

44+
The ``-r`` option can be used to specify a text file listing packages
45+
to be installed. The argument value is passed to ``pip -r`` to be
46+
installed.
47+
4348
.. seealso::
4449

4550
* :ref:`scripts-premkvirtualenv`
4651
* :ref:`scripts-postmkvirtualenv`
52+
* `requirements file format`_
53+
54+
.. _requirements file format: http://www.pip-installer.org/en/latest/requirement-format.html
4755

4856
.. _command-lsvirtualenv:
4957

@@ -394,3 +402,99 @@ output.
394402
Enabled global site-packages
395403
(env1)$ toggleglobalsitepackages -q
396404
(env1)$
405+
406+
============================
407+
Project Directory Management
408+
============================
409+
410+
.. seealso::
411+
412+
:ref:`project-management`
413+
414+
.. _command-mkproject:
415+
416+
mkproject
417+
---------
418+
419+
Create a new virtualenv in the WORKON_HOME and project directory in
420+
PROJECT_HOME.
421+
422+
Syntax::
423+
424+
mkproject [-t template] [virtualenv_options] ENVNAME
425+
426+
The template option may be repeated to have several templates used to
427+
create a new project. The templates are applied in the order named on
428+
the command line. All other options are passed to ``mkvirtualenv`` to
429+
create a virtual environment with the same name as the project.
430+
431+
::
432+
433+
$ mkproject myproj
434+
New python executable in myproj/bin/python
435+
Installing distribute.............................................
436+
..................................................................
437+
..................................................................
438+
done.
439+
Creating /Users/dhellmann/Devel/myproj
440+
(myproj)$ pwd
441+
/Users/dhellmann/Devel/myproj
442+
(myproj)$ echo $VIRTUAL_ENV
443+
/Users/dhellmann/Envs/myproj
444+
(myproj)$
445+
446+
.. seealso::
447+
448+
* :ref:`scripts-premkproject`
449+
* :ref:`scripts-postmkproject`
450+
451+
setvirtualenvproject
452+
--------------------
453+
454+
Bind an existing virtualenv to an existing project.
455+
456+
Syntax::
457+
458+
setvirtualenvproject [virtualenv_path project_path]
459+
460+
The arguments to ``setvirtualenvproject`` are the full paths to the
461+
virtualenv and project directory. An association is made so that when
462+
``workon`` activates the virtualenv the project is also activated.
463+
464+
::
465+
466+
$ mkproject myproj
467+
New python executable in myproj/bin/python
468+
Installing distribute.............................................
469+
..................................................................
470+
..................................................................
471+
done.
472+
Creating /Users/dhellmann/Devel/myproj
473+
(myproj)$ mkvirtualenv myproj_new_libs
474+
New python executable in myproj/bin/python
475+
Installing distribute.............................................
476+
..................................................................
477+
..................................................................
478+
done.
479+
Creating /Users/dhellmann/Devel/myproj
480+
(myproj_new_libs)$ setvirtualenvproject $VIRTUAL_ENV $(pwd)
481+
482+
When no arguments are given, the current virtualenv and current
483+
directory are assumed.
484+
485+
Any number of virtualenvs can refer to the same project directory,
486+
making it easy to switch between versions of Python or other
487+
dependencies for testing.
488+
489+
.. _command-cdproject:
490+
491+
cdproject
492+
---------
493+
494+
Change the current working directory to the one specified as the
495+
project directory for the active virtualenv.
496+
497+
Syntax::
498+
499+
cdproject
500+

‎docs/en/developers.rst

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,3 +91,30 @@ the ``tests`` directory.
9191
.. _shunit2: http://shunit2.googlecode.com/
9292

9393
.. _tox: http://codespeak.net/tox
94+
95+
.. _developer-templates:
96+
97+
Creating a New Template
98+
=======================
99+
100+
virtualenvwrapper.project templates work like `virtualenvwrapper
101+
plugins
102+
<http://www.doughellmann.com/docs/virtualenvwrapper/plugins.html>`__.
103+
The *entry point* group name is
104+
``virtualenvwrapper.project.template``. Configure your entry point to
105+
refer to a function that will **run** (source hooks are not supported
106+
for templates).
107+
108+
The argument to the template function is the name of the project being
109+
created. The current working directory is the directory created to
110+
hold the project files (``$PROJECT_HOME/$envname``).
111+
112+
Help Text
113+
---------
114+
115+
One difference between project templates and other virtualenvwrapper
116+
extensions is that only the templates specified by the user are run.
117+
The ``mkproject`` command has a help option to give the user a list of
118+
the available templates. The names are taken from the registered
119+
entry point names, and the descriptions are taken from the docstrings
120+
for the template functions.

‎docs/en/extensions.rst

Lines changed: 33 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -5,25 +5,6 @@
55
Below is a list of some of the extensions available for use with
66
virtualenvwrapper.
77

8-
.. _extensions-user_scripts:
9-
10-
project
11-
=======
12-
13-
The project_ extension adds development directory management with
14-
templates to virtualenvwrapper.
15-
16-
bitbucket
17-
---------
18-
19-
The bitbucket_ project template creates a working directory and
20-
automatically clones the repository from BitBucket. Requires
21-
project_.
22-
23-
.. _project: http://www.doughellmann.com/projects/virtualenvwrapper.project/
24-
25-
.. _bitbucket: http://www.doughellmann.com/projects/virtualenvwrapper.bitbucket/
26-
278
emacs-desktop
289
=============
2910

@@ -37,6 +18,8 @@ one when activating a new virtualenv using ``workon``.
3718

3819
.. _emacs-desktop: http://www.doughellmann.com/projects/virtualenvwrapper-emacs-desktop/
3920

21+
.. _extensions-user_scripts:
22+
4023
user_scripts
4124
============
4225

@@ -53,3 +36,34 @@ virtualenvwrapper, vim-virtualenv identifies the virtualenv to
5336
activate based on the name of the file being edited.
5437

5538
.. _vim-virtualenv: https://github.com/jmcantrell/vim-virtualenv
39+
40+
.. _extensions-templates:
41+
42+
Templates
43+
=========
44+
45+
Below is a list of some of the templates available for use with
46+
:ref:`command-mkproject`.
47+
48+
.. _templates-bitbucket:
49+
50+
bitbucket
51+
---------
52+
53+
The bitbucket_ extension automatically clones a mercurial repository
54+
from the specified bitbucket project.
55+
56+
.. _bitbucket: http://www.doughellmann.com/projects/virtualenvwrapper.bitbucket/
57+
58+
.. _templates-django:
59+
60+
django
61+
------
62+
63+
The django_ extension automatically creates a new Django project.
64+
65+
.. _django: http://www.doughellmann.com/projects/virtualenvwrapper.django/
66+
67+
.. seealso::
68+
69+
* :ref:`developer-templates`

‎docs/en/history.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,17 @@
22
Release History
33
===============
44

5+
2.9
6+
7+
- Change the shell function shell definition syntax so that ksh will
8+
treat typeset-declared variables as local. No kidding.
9+
- Merge the "project directory" features of the
10+
``virtualenvwrapper.project`` plugin into the main project, adding
11+
:ref:`command-mkproject`, :ref:`command-cdproject`, and
12+
:ref:`command-setvirtualenvproject` commands.
13+
- Add ``-r`` option to :ref:`command-mkvirtualenv` to install
14+
dependencies using a pip requirements file.
15+
516
2.8
617

718
- Use VIRTUALENVWRAPPER_VIRTUALENV in `cpvirtualenv` (:bbissue:`104`).

‎docs/en/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -175,6 +175,7 @@ Details
175175
install
176176
command_ref
177177
hooks
178+
projects
178179
tips
179180
developers
180181
extensions

‎docs/en/install.rst

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -106,11 +106,13 @@ add it to `your user local directory
106106
Shell Startup File
107107
==================
108108

109-
Add two lines to your shell startup file (``.bashrc``, ``.profile``,
110-
etc.) to set the location where the virtual environments should live
111-
and the location of the script installed with this package::
109+
Add three lines to your shell startup file (``.bashrc``, ``.profile``,
110+
etc.) to set the location where the virtual environments should live,
111+
the location of your development project directorkes, and the location
112+
of the script installed with this package::
112113

113114
export WORKON_HOME=$HOME/.virtualenvs
115+
export PROJECT_HOME=$HOME/Devel
114116
source /usr/local/bin/virtualenvwrapper.sh
115117

116118
After editing it, reload the startup file (e.g., run ``source
@@ -133,6 +135,8 @@ virtualenvwrapper can be customized by changing environment
133135
variables. Set the variables in your shell startup file *before*
134136
loading ``virtualenvwrapper.sh``.
135137

138+
.. _variable-WORKON_HOME:
139+
136140
Location of Environments
137141
------------------------
138142

@@ -141,6 +145,19 @@ your virtual environments. The default is ``$HOME/.virtualenvs``. If
141145
the directory does not exist when virtualenvwrapper is loaded, it will
142146
be created automatically.
143147

148+
.. _variable-PROJECT_HOME:
149+
150+
Location of Project Directories
151+
-------------------------------
152+
153+
The variable ``PROJECT_HOME`` tells virtualenvwrapper where to place
154+
your project working directories. The variable must be set and the
155+
directory created before :ref:`command-mkproject` is used.
156+
157+
.. seealso::
158+
159+
* :ref:`project-management`
160+
144161
.. _variable-VIRTUALENVWRAPPER_HOOK_DIR:
145162

146163
Location of Hook Scripts
@@ -150,6 +167,10 @@ The variable ``VIRTUALENVWRAPPER_HOOK_DIR`` tells virtualenvwrapper
150167
where the :ref:`user-defined hooks <scripts>` should be placed. The
151168
default is ``$WORKON_HOME``.
152169

170+
.. seealso::
171+
172+
* :ref:`scripts`
173+
153174
.. _variable-VIRTUALENVWRAPPER_LOG_DIR:
154175

155176
Location of Hook Logs
@@ -231,6 +252,13 @@ users of that shell will have virtualenvwrapper enabled, and they
231252
cannot disable it. Refer to the documentation for the shell to
232253
identify the appropriate file to edit.
233254

255+
Upgrading to 2.9
256+
================
257+
258+
Version 2.9 includes the features previously delivered separately by
259+
``virtualenvwrapper.project``. If you have an older verison of the
260+
project extensions installed, remove them before upgrading.
261+
234262
Upgrading from 1.x
235263
==================
236264

0 commit comments

Comments
 (0)