Skip to content

Commit a554f0f

Browse files
kennethreitzkennethreitz
authored
Update virtualenvs.rst
1 parent 6a8feb0 commit a554f0f

File tree

1 file changed

+168
-14
lines changed

1 file changed

+168
-14
lines changed

‎docs/dev/virtualenvs.rst

Lines changed: 168 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3,33 +3,187 @@
33
Pipenv & Virtual Environments
44
=============================
55

6-
A Virtual Environment is a tool to keep the dependencies required by different
7-
projects in separate places, by creating virtual Python environments for them.
8-
It solves the "Project X depends on version 1.x but, Project Y needs 4.x"
9-
dilemma, and keeps your global site-packages directory clean and manageable.
6+
This tutorial walks you through installing and using Python packages. It will
7+
show you how to install and use the necessary tools and make strong
8+
recommendations on best practices. Keep in mind that Python is used for a great
9+
many different purposes, and precisely how you want to manage your dependencies
10+
may change based on how you decide to publish your software. The guidance
11+
presented here is most directly applicable to the development and deployment of
12+
network services (including web applications), but is also very well suited to
13+
managing development and testing environments for any kind of project.
1014

11-
For example, you can work on a project which requires Django 1.10 while also
12-
maintaining a project which requires Django 1.8.
15+
.. Note:: This guide is written for Python 3, however, these instructions
16+
should work fine on Python 2.7.
1317

1418

15-
Pipenv
16-
------
19+
Make sure you've got Python & pip
20+
---------------------------------
1721

18-
**Pipenv** is a project that aims to bring the best of all packaging worlds to the Python world. It harnesses `Pipfile <https://github.com/pypa/pipfile>`_, `pip <https://github.com/pypa/pip>`_, and `virtualenv <https://github.com/pypa/virtualenv>`_ into one single toolchain. It features very pretty terminal colors.
22+
Before you go any further, make sure you have Python and that it's avalable
23+
from your command line. You can check this by simply running:
1924

20-
It automatically creates and manages a virtualenv for your projects, as well as adds/removes packages from your ``Pipfile`` as you install/uninstall packages. The ``lock`` command generates a lockfile (``Pipfile.lock``).
25+
.. code-block:: bash
2126
27+
python --version
2228
23-
Install Pipenv with pip::
29+
You should get some output like ``3.6.2``. If you do not have Python, please
30+
install the latest 3.x version from `python.org`_ or refer to the
31+
`Installing Python`_ section of the Hitchhiker's Guide to Python.
2432

25-
$ pip install pipenv
26-
✨🍰✨
33+
.. Note:: If you're newcomer and you get an error like this:
2734

35+
.. code-block:: python
2836
37+
>>> python
38+
Traceback (most recent call last):
39+
File "<stdin>", line 1, in <module>
40+
NameError: name 'python' is not defined
2941
30-
virtualenv
42+
It's because this command is intended to be run in a *shell* (also called
43+
a *terminal* or *console*). See the Python for Beginners
44+
`getting started tutorial`_ for an introduction to using your operating
45+
system's shell and interacting with Python.
46+
47+
Additionally, you'll need to make sure you have :ref:`pip` available. You can
48+
check this by running:
49+
50+
.. code-block:: bash
51+
52+
pip --version
53+
54+
If you installed Python from source, with an installer from `python.org`_, or
55+
via `Homebrew`_ you should already have pip. If you're on Linux and installed
56+
using your OS package manager, you may have to install pip separately, see
57+
:doc:`/guides/installing-using-linux-tools`.
58+
59+
.. _getting started tutorial: https://opentechschool.github.io/python-beginners/en/getting_started.html#what-is-python-exactly
60+
.. _python.org: https://python.org
61+
.. _Homebrew: https://brew.sh
62+
.. _Installing Python: http://docs.python-guide.org/en/latest/starting/installation/
63+
64+
65+
Installing Pipenv
66+
-----------------
67+
68+
:ref:`Pipenv` is a dependency manager for Python projects. If you're familiar
69+
with Node.js' `npm`_ or Ruby's `bundler`_, it is similar in spirit to those
70+
tools. While :ref:`pip` can install Python packages, Pipenv is recommended as
71+
it's a higher-level tool that simplifies dependency management for common use
72+
cases.
73+
74+
Use ``pip`` to install Pipenv:
75+
76+
.. code-block:: python
77+
78+
pip install --user pipenv
79+
80+
81+
.. Note:: This does a `user installation`_ to prevent breaking any system-wide
82+
packages. If ``pipenv`` isn't available in your shell after installation,
83+
you'll need to add the `user base`_'s ``bin`` directory to your ``PATH``.
84+
You can find the user base by running ``python -m site`` which will print
85+
site information including the user base. For example, on Linux this will
86+
return ``USER_BASE: '~/.local'`` so you'll need to add ``~/.local/bin`` to
87+
your ``PATH``. On Linux and macOS you can set your ``PATH`` permanently
88+
by `modifying ~/.profile`_. On Windows you can set the user
89+
``PATH`` permanently in the `Control Panel`_.
90+
91+
.. _npm: https://www.npmjs.com/
92+
.. _bundler: http://bundler.io/
93+
.. _user base: https://docs.python.org/3/library/site.html#site.USER_BASE
94+
.. _user installation: https://pip.pypa.io/en/stable/user_guide/#user-installs
95+
.. _modifying ~/.profile: https://stackoverflow.com/a/14638025
96+
.. _Control Panel: https://msdn.microsoft.com/en-us/library/windows/desktop/bb776899(v=vs.85).aspx
97+
98+
Installing packages for your project
99+
------------------------------------
100+
101+
Pipenv manages dependencies on a per-project basis. To install packages,
102+
change into your project's directory (or just an empty directory for this
103+
tutorial) and run:
104+
105+
.. code-block:: bash
106+
107+
cd myproject
108+
pipenv install requests
109+
110+
Pipenv will install the excellent `Requests`_ library and create a ``Pipfile``
111+
for you in your project's directory. The :ref:`Pipfile` is used to track which
112+
dependencies your project needs in case you need to re-install them, such as
113+
when you share your project with others. You should get output similar to this
114+
(although the exact paths shown will vary):
115+
116+
.. code-block:: text
117+
118+
Creating a Pipfile for this project...
119+
Creating a virtualenv for this project...
120+
Using base prefix '/usr/local/Cellar/python3/3.6.2/Frameworks/Python.framework/Versions/3.6'
121+
New python executable in ~/.local/share/virtualenvs/tmp-agwWamBd/bin/python3.6
122+
Also creating executable in ~/.local/share/virtualenvs/tmp-agwWamBd/bin/python
123+
Installing setuptools, pip, wheel...done.
124+
125+
Virtualenv location: ~/.local/share/virtualenvs/tmp-agwWamBd
126+
Installing requests...
127+
Collecting requests
128+
Using cached requests-2.18.4-py2.py3-none-any.whl
129+
Collecting idna<2.7,>=2.5 (from requests)
130+
Using cached idna-2.6-py2.py3-none-any.whl
131+
Collecting urllib3<1.23,>=1.21.1 (from requests)
132+
Using cached urllib3-1.22-py2.py3-none-any.whl
133+
Collecting chardet<3.1.0,>=3.0.2 (from requests)
134+
Using cached chardet-3.0.4-py2.py3-none-any.whl
135+
Collecting certifi>=2017.4.17 (from requests)
136+
Using cached certifi-2017.7.27.1-py2.py3-none-any.whl
137+
Installing collected packages: idna, urllib3, chardet, certifi, requests
138+
Successfully installed certifi-2017.7.27.1 chardet-3.0.4 idna-2.6 requests-2.18.4 urllib3-1.22
139+
140+
Adding requests to Pipfile's [packages]...
141+
P.S. You have excellent taste! ✨ 🍰 ✨
142+
143+
.. _Requests: https://python-requests.org
144+
145+
146+
Using installed packages
147+
------------------------
148+
149+
Now that Requests is installed you can create a simple ``main.py`` file to
150+
use it:
151+
152+
.. code-block:: python
153+
154+
import requests
155+
156+
response = requests.get('https://httpbin.org/ip')
157+
158+
print('Your IP is {0}'.format(response.json['origin']))
159+
160+
Then you can run this script using ``pipenv run``:
161+
162+
.. code-block:: bash
163+
164+
pipenv run python main.py
165+
166+
You should get output similar to this:
167+
168+
.. code-block:: text
169+
170+
Your IP is 8.8.8.8
171+
172+
Using ``pipenv run`` ensures that your installed packages are available to
173+
your script. It's also possible to spawn a new shell that ensures all commands
174+
have access to your installed packages with ``pipenv shell``.
175+
176+
177+
Next steps
31178
----------
32179

180+
Congratulations, you now know how to install and use Python packages! ✨ 🍰 ✨
181+
182+
183+
184+
virtualenv
185+
==========
186+
33187
`virtualenv <http://pypi.python.org/pypi/virtualenv>`_ is a tool to create
34188
isolated Python environments. virtualenv creates a folder which contains all the
35189
necessary executables to use the packages that a Python project would need.

0 commit comments

Comments
 (0)