Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

rst format fix, ~~~ was being used instead of --- under subsections c… #939

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

rst format fix, ~~~ was being used instead of --- under subsections c… #939

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f485375
rst format fix, ~~~ was being used instead of --- under subsections c…
daniel-demelo Nov 25, 2018
62fa79d
image path fixed
daniel-demelo Nov 25, 2018
42846b0
headings fix and img path revert
daniel-demelo Nov 26, 2018
ac7ea52
autoenv hierarchy change / style applied to document
daniel-demelo Nov 27, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 56 additions & 46 deletions docs/dev/virtualenvs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
.. _virtualenvironments-ref:

#############################
Pipenv & Virtual Environments
=============================
#############################

.. image:: /_static/photos/35294660055_42c02b2316_k_d.jpg

Expand All @@ -15,12 +16,13 @@ presented here is most directly applicable to the development and deployment of
network services (including web applications), but is also very well suited to
managing development and testing environments for any kind of project.

.. Note:: This guide is written for Python 3, however, these instructions
.. note:: This guide is written for Python 3, however, these instructions
should work fine on Python 2.7—if you are still using it, for some reason.


*********************************
Make sure you've got Python & pip
---------------------------------
*********************************

Before you go any further, make sure you have Python and that it's available
from your command line. You can check this by simply running:
Expand All @@ -33,13 +35,14 @@ You should get some output like ``3.6.2``. If you do not have Python, please
install the latest 3.x version from `python.org`_ or refer to the
`Installing Python`_ section of this guide.

.. Note:: If you're newcomer and you get an error like this:
.. note::
If you're newcomer and you get an error like this:

.. code-block:: python

>>> python
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "<stdin>", line 1, in <module>
NameError: name 'python' is not defined

It's because this command is intended to be run in a *shell* (also called
Expand All @@ -65,8 +68,9 @@ using your OS package manager, you may have to `install pip <https://pip.pypa.io
.. _Installing Python: https://docs.python-guide.org/starting/installation/


*****************
Installing Pipenv
-----------------
*****************

`Pipenv`_ is a dependency manager for Python projects. If you're familiar
with Node.js' `npm`_ or Ruby's `bundler`_, it is similar in spirit to those
Expand All @@ -81,7 +85,8 @@ Use ``pip`` to install Pipenv:
$ pip install --user pipenv


.. Note:: This does a `user installation`_ to prevent breaking any system-wide
.. note::
This does a `user installation`_ to prevent breaking any system-wide
packages. If ``pipenv`` isn't available in your shell after installation,
you'll need to add the `user base`_'s binary directory to your ``PATH``.

Expand Down Expand Up @@ -110,7 +115,7 @@ Use ``pip`` to install Pipenv:
.. _Control Panel: https://msdn.microsoft.com/en-us/library/windows/desktop/bb776899(v=vs.85).aspx

Installing packages for your project
------------------------------------
====================================

Pipenv manages dependencies on a per-project basis. To install packages,
change into your project's directory (or just an empty directory for this
Expand Down Expand Up @@ -141,15 +146,15 @@ when you share your project with others. You should get output similar to this
Virtualenv location: ~/.local/share/virtualenvs/tmp-agwWamBd
Installing requests...
Collecting requests
Using cached requests-2.18.4-py2.py3-none-any.whl
Using cached requests-2.18.4-py2.py3-none-any.whl
Collecting idna<2.7,>=2.5 (from requests)
Using cached idna-2.6-py2.py3-none-any.whl
Using cached idna-2.6-py2.py3-none-any.whl
Collecting urllib3<1.23,>=1.21.1 (from requests)
Using cached urllib3-1.22-py2.py3-none-any.whl
Using cached urllib3-1.22-py2.py3-none-any.whl
Collecting chardet<3.1.0,>=3.0.2 (from requests)
Using cached chardet-3.0.4-py2.py3-none-any.whl
Using cached chardet-3.0.4-py2.py3-none-any.whl
Collecting certifi>=2017.4.17 (from requests)
Using cached certifi-2017.7.27.1-py2.py3-none-any.whl
Using cached certifi-2017.7.27.1-py2.py3-none-any.whl
Installing collected packages: idna, urllib3, chardet, certifi, requests
Successfully installed certifi-2017.7.27.1 chardet-3.0.4 idna-2.6 requests-2.18.4 urllib3-1.22

Expand All @@ -158,9 +163,8 @@ when you share your project with others. You should get output similar to this

.. _Requests: https://python-requests.org


Using installed packages
------------------------
========================

Now that Requests is installed you can create a simple ``main.py`` file to
use it:
Expand Down Expand Up @@ -189,16 +193,15 @@ Using ``$ pipenv run`` ensures that your installed packages are available to
your script. It's also possible to spawn a new shell that ensures all commands
have access to your installed packages with ``$ pipenv shell``.


Next steps
----------
==========

Congratulations, you now know how to install and use Python packages! ✨ 🍰 ✨



***********************
Lower level: virtualenv
=======================
***********************

`virtualenv <http://pypi.python.org/pypi/virtualenv>`_ is a tool to create
isolated Python environments. virtualenv creates a folder which contains all the
Expand All @@ -210,23 +213,23 @@ Install virtualenv via pip:

.. code-block:: console

$ pip install virtualenv
$ pip install virtualenv

Test your installation

.. code-block:: console

$ virtualenv --version
$ virtualenv --version

Basic Usage
~~~~~~~~~~~
===========

1. Create a virtual environment for a project:

.. code-block:: console

$ cd my_project_folder
$ virtualenv my_project
$ cd my_project_folder
$ virtualenv my_project

``virtualenv my_project`` will create a folder in the current directory which will
contain the Python executable files, and a copy of the ``pip`` library which you
Expand All @@ -242,19 +245,19 @@ You can also use the Python interpreter of your choice (like

.. code-block:: console

$ virtualenv -p /usr/bin/python2.7 my_project
$ virtualenv -p /usr/bin/python2.7 my_project

or change the interpreter globally with an env variable in ``~/.bashrc``:

.. code-block:: console

$ export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python2.7
$ export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python2.7

2. To begin using the virtual environment, it needs to be activated:

.. code-block:: console

$ source my_project/bin/activate
$ source my_project/bin/activate

The name of the current virtual environment will now appear on the left of
the prompt (e.g. ``(my_project)Your-Computer:your_project UserName$)`` to let you know
Expand All @@ -272,7 +275,7 @@ Install packages as usual, for example:

.. code-block:: console

$ deactivate
$ deactivate

This puts you back to the system's default Python interpreter with all its
installed libraries.
Expand All @@ -285,7 +288,7 @@ littered across your system, and its possible you'll forget their names or
where they were placed.

Other Notes
~~~~~~~~~~~
===========

Running ``virtualenv`` with the option ``--no-site-packages`` will not
include the packages that are installed globally. This can be useful
Expand Down Expand Up @@ -318,8 +321,10 @@ control by adding it to the ignore list (see :ref:`Version Control Ignores<versi

.. _virtualenvwrapper-ref:


*****************
virtualenvwrapper
-----------------
*****************

`virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/en/latest/index.html>`_
provides a set of commands which makes working with virtual environments much
Expand All @@ -329,9 +334,9 @@ To install (make sure **virtualenv** is already installed):

.. code-block:: console

$ pip install virtualenvwrapper
$ export WORKON_HOME=~/Envs
$ source /usr/local/bin/virtualenvwrapper.sh
$ pip install virtualenvwrapper
$ export WORKON_HOME=~/Envs
$ source /usr/local/bin/virtualenvwrapper.sh

(`Full virtualenvwrapper install instructions <https://virtualenvwrapper.readthedocs.io/en/latest/install.html>`_.)

Expand All @@ -341,34 +346,34 @@ To install (make sure **virtualenv** is already installed):

.. code-block:: console

$ pip install virtualenvwrapper-win
$ pip install virtualenvwrapper-win

In Windows, the default path for WORKON_HOME is %USERPROFILE%\Envs

Basic Usage
~~~~~~~~~~~
===========

1. Create a virtual environment:

.. code-block:: console

$ mkvirtualenv my_project
$ mkvirtualenv my_project

This creates the :file:`my_project` folder inside :file:`~/Envs`.

2. Work on a virtual environment:

.. code-block:: console

$ workon my_project
$ workon my_project

Alternatively, you can make a project, which creates the virtual environment,
and also a project directory inside ``$WORKON_HOME``, which is ``cd`` -ed into
when you ``workon myproject``.

.. code-block:: console

$ mkproject myproject
$ mkproject myproject

**virtualenvwrapper** provides tab-completion on environment names. It really
helps when you have a lot of environments and have trouble remembering their
Expand All @@ -381,16 +386,16 @@ can quickly switch between environments.

.. code-block:: console

$ deactivate
$ deactivate

4. To delete:

.. code-block:: console

$ rmvirtualenv venv
$ rmvirtualenv venv

Other useful commands
~~~~~~~~~~~~~~~~~~~~~
=====================

``lsvirtualenv``
List all of the environments.
Expand All @@ -407,26 +412,31 @@ Other useful commands

`Full list of virtualenvwrapper commands <https://virtualenvwrapper.readthedocs.io/en/latest/command_ref.html>`_.


******************
virtualenv-burrito
------------------
******************

With `virtualenv-burrito <https://github.com/brainsik/virtualenv-burrito>`_, you
can have a working virtualenv + virtualenvwrapper environment in a single command.


*******
autoenv
-------
*******

When you ``cd`` into a directory containing a :file:`.env`, `autoenv <https://github.com/kennethreitz/autoenv>`_
automagically activates the environment.

Install it on Mac OS X using ``brew``:

.. code-block:: console

$ brew install autoenv
$ brew install autoenv

And on Linux:

.. code-block:: console

$ git clone git://github.com/kennethreitz/autoenv.git ~/.autoenv
$ echo 'source ~/.autoenv/activate.sh' >> ~/.bashrc
$ git clone git://github.com/kennethreitz/autoenv.git ~/.autoenv
$ echo 'source ~/.autoenv/activate.sh' >> ~/.bashrc