1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
:orphan:
.. _using-virtualenv:
Using virtualenv
================
`virtualenv`_ is a tool for creating and activating isolated Python
environments that allow installing and experimenting with Python packages
without disrupting your production Python environment. When using commands
such as ``python setup.py develop``, for example, it is strongly recommended to
do so within a virtualenv. This is generally preferable to installing a
development version of Astropy into your system site-packages and having to
keep track of whether or not your environment is in a "known good"
configuration for production/science use.
Using a virtualenv is also a good way to try out new versions of software that
you're not actively doing development work on without disrupting your normal
production environment.
We won't provide a full tutorial on using virtualenv here |emdash| the
virtualenv documentation linked to above is a better place to start. But here
is a quick overview on how to set up a virtualenv for Astropy development with
your default Python version:
#. Install virtualenv::
$ pip install virtualenv
or (on Debian/Ubuntu)::
$ sudo apt-get install python-virtualenv
etc.
#. (Recommended) Create a root directory for all your virtualenvs under a path
you have write access to. For example::
$ mkdir ~/.virtualenvs
#. Create the Astropy virtualenv::
$ virtualenv --distribute --system-site-packages ~/.virtualenvs/astropy-dev
The ``--system-site-packages`` option inherits all packages already
installed in your system site-packages directory; this frees you from having
to reinstall packages like Numpy and Scipy in the virtualenv. However, if
you would like your virtualenv to use a development version of Numpy, for
example, you can still install Numpy into the virtualenv and it will take
precedence over the version installed in site-packages.
#. Activate the virtualenv::
$ source ~/.virtualenvs/astropy-dev/bin/activate
or if you're using a csh-variant::
$ source ~/.virtualenvs/astropy-dev/bin/activate.csh
virtualenv works on Windows too |emdash| see the documentation for details.
#. If the virtualenv successfully activated its name should appear in your
shell prompt::
(astropy-dev) $
The virtualenv can be disabled at any time by entering::
(astropy-dev) $ deactivate
#. Now as long as the virtualenv is activated, packages you install with
``pip``, or by manually running ``python setup.py install`` will
automatically install into your virtualenv instead of the system
site-packages. Consider installing Astropy in develop mode into the
virtualenv as described :ref:`activate_development_astropy`.
Using virtualenv with IPython
-----------------------------
.. note::
As of IPython 0.13 this functionality is built into IPython and these steps
are not necessary for IPython to recognize that it's running with a
virtualenv enabled.
Each virtualenv has its own ``bin/``, and as IPython is written in pure Python
one can always install IPython directly into a virtualenv. However, if you
would rather not have to install IPython every time you create a virtualenv, it
also suffices to make IPython virtualenv-aware.
1. Check to see if you already have an IPython profile in
``~/.ipython/profile_default/``; if not, create one::
$ ipython profile create
2. Edit ``~/.ipython/profile_default/ipython_config.py`` and add the
following to the end::
import os
execfile(os.path.join(os.environ['HOME'], '.ipython', 'virtualenv.py'))
3. Finally, create the ``~/.ipython/virtualenv.py`` module::
import site
from os import environ
from os.path import join
from sys import version_info
if 'VIRTUAL_ENV' in environ:
virtual_env = join(environ.get('VIRTUAL_ENV'),
'lib',
'python%d.%d' % version_info[:2],
'site-packages')
site.addsitedir(virtual_env)
print 'VIRTUAL_ENV ->', virtual_env
del virtual_env
del site, environ, join, version_info
Now IPython will import all packages from your virtualenv where applicable.
.. note::
This is not magic. If you switch to a virtualenv that uses a different
Python version from your main IPython installation this won't help you
|emdash| instead use the appropriate IPython installation for the Python
version in question.
virtualenvwrapper
-----------------
`virtualenvwrapper`_ is a set of enhancements to virtualenv mostly
implemented through simple shell scripts and aliases. It automatically
organizes all your virtualenvs under a single directory (as suggested
above). To create a new virtualenv you can just use the ``'mkvirtualenv
<env_name>'`` command and it will automatically create a new virtualenv of
that name in the default location.
To activate a virtualenv with virtualenvwrapper you don't need to think
about the environment's location of the filesystem or which activate script
to run. Simply run ``'workon <env_name>'``. You can also list all
virtualenvs with ``lsvirtualenv``. That just scratches the surface of the
goodies included with virtualenvwrapper.
The one caveat is that it does not support csh-like shells. For csh-like
shells there exists `virtualenvwrapper-csh`_, which implements most of the
virtualenvwrapper functionality and is otherwise compatible with the original.
There also exists `virtualenvwrapper-win`_, which ports virtualenvwrapper to
Windows batch scripts.
venv
----
virtualenv is so commonly used in the Python development community that its
functionality was finally added to the standard library in Python 3.3 under
the name `venv`_. venv has not gained wide use yet and is not explicitly
supported by tools like virtualenvwrapper, but it is expected to see wider
adoption in the future.
.. include:: links.inc
|
