From 6711e7fde14d02ec3e881a1636eed04bcd0bdc56 Mon Sep 17 00:00:00 2001 From: Adam Nelson Date: Mon, 14 Mar 2016 12:33:49 -0400 Subject: [PATCH 1/8] Removed references to Setuptools/easy_install in favor of pip. A new Python user hardly needs to know that easy_install ever existed --- docs/starting/install/osx.rst | 44 ++++++++++++++++------------------- 1 file changed, 20 insertions(+), 24 deletions(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index cb0062cc7..db029822b 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -5,11 +5,11 @@ Installing Python on Mac OS X The latest version of Mac OS X, El Capitan, **comes with Python 2.7 out of the box**. -You do not need to install or configure anything else to use Python. Having -said that, I would strongly recommend that you install the tools and libraries -described in the next section before you start building Python applications -for real-world use. In particular, you should always install Setuptools, as it -makes it much easier for you to use other third-party Python libraries. +You do not need to install or configure anything else to use Python. Having said +that, I would strongly recommend that you install the tools and libraries +described in the next section before you start building Python applications for +real-world use. In particular, you should always install ``pip``, as it makes +it much easier for you to install and manage other third-party Python libraries. The version of Python that ships with OS X is great for learning but it's not good for development. The version shipped with OS X may be out of date from the @@ -33,11 +33,11 @@ package. diagnose. .. note:: - If you perform a fresh install of XCode, you will also need to add the + If you perform a fresh install of XCode, you will also need to add the commandline tools by running ``xcode-select --install`` on the terminal. While OS X comes with a large number of UNIX utilities, those familiar with -Linux systems will notice one key component missing: a decent package manager. +Linux systems will notice one key component missing: a package manager. `Homebrew `_ fills this void. To `install Homebrew `_, open :file:`Terminal` or @@ -63,37 +63,33 @@ Now, we can install Python 2.7: $ brew install python -This will take a minute or two. +This will take a minute or two. -Setuptools & Pip +Pip ---------------- -Homebrew installs Setuptools and ``pip`` for you. +Homebrew installs ``pip`` for you. -Setuptools enables you to download and install any compliant Python -software over a network (usually the Internet) with a single command -(``easy_install``). It also enables you to add this network installation -capability to your own Python software with very little work. - -``pip`` is a tool for easily installing and managing Python packages, -that is recommended over ``easy_install``. It is superior to ``easy_install`` in `several ways `_, +``pip`` is a tool for easily installing and managing Python packages, that is +recommended over the deprecated ``easy_install``. It is superior to +``easy_install`` in `several ways +`_, and is actively maintained. Virtual Environments -------------------- -A Virtual Environment is a tool to keep the dependencies required by different projects -in separate places, by creating virtual Python environments for them. It solves the -"Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps +A Virtual Environment (commonly referred to as a 'virtualenv') is a tool to keep the dependencies required by different projects +in separate places, by creating virtual Python environments for them. It solves the +"Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps your global site-packages directory clean and manageable. -For example, you can work on a project which requires Django 1.3 while also -maintaining a project which requires Django 1.0. - -To start using this and see more information: :ref:`Virtual Environments ` docs. +For example, you can work on a project which requires Django 1.10 while also +maintaining a project which requires Django 1.7. +To start using this and see more information: :ref:`Virtual Environments ` docs. -------------------------------- From 304728846623c831fa549c40c60b1329c99a1264 Mon Sep 17 00:00:00 2001 From: Adam Nelson Date: Mon, 14 Mar 2016 13:22:14 -0400 Subject: [PATCH 2/8] Removed references to main install page --- docs/starting/installation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index 04aaaa0b8..c0118f68c 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -7,14 +7,14 @@ If so, you do not need to install or configure anything else to use Python. Having said that, I would strongly recommend that you install the tools and libraries described in the guides below before you start building Python applications for real-world use. In particular, you should always install -Setuptools, Pip, and Virtualenv — they make it much easier for you to use +Pip, and Virtualenv — they make it much easier for you to use other third-party Python libraries. Installation Guides ------------------- These guides go over the proper installation of :ref:`Python 2.7 ` -for development purposes, as well as setuptools, pip, and virtualenv setup. +for development purposes, as well as pip and virtualenv. - :ref:`Mac OS X `. - :ref:`Microsoft Windows `. From 8da905eae316c897bc61ffbc9d093483f6341519 Mon Sep 17 00:00:00 2001 From: Adam Nelson Date: Mon, 14 Mar 2016 14:28:01 -0400 Subject: [PATCH 3/8] First stab at Python3 OS X docs --- docs/dev/virtualenvs.rst | 35 ++++++---- docs/starting/install/osx.rst | 3 + docs/starting/install3/osx.rst | 116 +++++++++++++++++++++++++++++++++ docs/starting/installation.rst | 10 +-- 4 files changed, 146 insertions(+), 18 deletions(-) create mode 100644 docs/starting/install3/osx.rst diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index bb3f9487c..90c7f19df 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -8,15 +8,22 @@ projects in separate places, by creating virtual Python environments for them. It solves the "Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps your global site-packages directory clean and manageable. -For example, you can work on a project which requires Django 1.3 while also -maintaining a project which requires Django 1.0. +For example, you can work on a project which requires Django 1.9 while also +maintaining a project which requires Django 1.8. + +If you are using Python 3, make sure you run something like the following (or +have it in your env variables in `~/.bashrc`): + +.. code-block:: console + + $ export VIRTUALENVWRAPPER_PYTHON=/usr/local/bin/python3 virtualenv ---------- `virtualenv `_ is a tool to create -isolated Python environments. virtualenv creates a folder which contains all the -necessary executables to use the packages that a Python project would need. +isolated Python environments. virtualenv creates a folder which contains all the +necessary executables to use the packages that a Python project would need. Install virtualenv via pip: @@ -43,13 +50,13 @@ in the current directory instead. This creates a copy of Python in whichever directory you ran the command in, placing it in a folder named :file:`venv`. -You can also use a Python interpreter of your choice. +You can also use the Python interpreter of your choice. .. code-block:: console - $ virtualenv -p /usr/bin/python2.7 venv + $ virtualenv -p /usr/local/bin/python3 venv -This will use the Python interpreter in :file:`/usr/bin/python2.7` +This will use the Python interpreter in :file:`/usr/local/bin/python3` 2. To begin using the virtual environment, it needs to be activated: @@ -57,9 +64,9 @@ This will use the Python interpreter in :file:`/usr/bin/python2.7` $ source venv/bin/activate -The name of the current virtual environment will now appear on the left of -the prompt (e.g. ``(venv)Your-Computer:your_project UserName$)`` to let you know -that it's active. From now on, any package that you install using pip will be +The name of the current virtual environment will now appear on the left of +the prompt (e.g. ``(venv)Your-Computer:your_project UserName$)`` to let you know +that it's active. From now on, any package that you install using pip will be placed in the ``venv`` folder, isolated from the global Python installation. Install packages as usual, for example: @@ -78,7 +85,7 @@ Install packages as usual, for example: This puts you back to the system's default Python interpreter with all its installed libraries. -To delete a virtual environment, just delete its folder. (In this case, +To delete a virtual environment, just delete its folder. (In this case, it would be ``rm -rf venv``.) After a while, though, you might end up with a lot of virtual environments @@ -102,8 +109,8 @@ the current state of the environment packages. To do this, run This will create a :file:`requirements.txt` file, which contains a simple list of all the packages in the current environment, and their respective -versions. You can see the list of installed packages without the requirements -format using "pip list". Later it will be easier for a different developer +versions. You can see the list of installed packages without the requirements +format using "pip list". Later it will be easier for a different developer (or you, if you need to re-create the environment) to install the same packages using the same versions: @@ -143,7 +150,7 @@ To install (make sure **virtualenv** is already installed): .. code-block:: console $ pip install virtualenvwrapper-win - + In Windows, the default path for WORKON_HOME is %USERPROFILE%\Envs Basic Usage diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index db029822b..549b8063f 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -3,6 +3,9 @@ Installing Python on Mac OS X ============================= +.. note:: + Check out our :ref:`guide for installing Python 3 on OS X`. + The latest version of Mac OS X, El Capitan, **comes with Python 2.7 out of the box**. You do not need to install or configure anything else to use Python. Having said diff --git a/docs/starting/install3/osx.rst b/docs/starting/install3/osx.rst new file mode 100644 index 000000000..d5a33291c --- /dev/null +++ b/docs/starting/install3/osx.rst @@ -0,0 +1,116 @@ +.. _install3-osx: + +Installing Python 3 on Mac OS X +================================ + +The latest version of Mac OS X, El Capitan, **comes with Python 2.7 out of the box**. + +You do not need to install or configure anything else to use Python 2. These +instructions document the installation of Python 3. + +The version of Python that ships with OS X is great for learning but it's not +good for development. The version shipped with OS X may be out of date from the +`official current Python release `_, +which is considered the stable production version. + +Doing it Right +-------------- + +Let's install a real version of Python. + +Before installing Python, you'll need to install GCC. GCC can be obtained +by downloading `XCode `_, the smaller +`Command Line Tools `_ (must have an +Apple account) or the even smaller `OSX-GCC-Installer `_ +package. + +.. note:: + If you already have XCode installed, do not install OSX-GCC-Installer. + In combination, the software can cause issues that are difficult to + diagnose. + +.. note:: + If you perform a fresh install of XCode, you will also need to add the + commandline tools by running ``xcode-select --install`` on the terminal. + +While OS X comes with a large number of UNIX utilities, those familiar with +Linux systems will notice one key component missing: a package manager. +`Homebrew `_ fills this void. + +To `install Homebrew `_, open :file:`Terminal` or +your favorite OSX terminal emulator and run + +.. code-block:: console + + $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" + +The script will explain what changes it will make and prompt you before the +installation begins. +Once you've installed Homebrew, insert the Homebrew directory at the top +of your :envvar:`PATH` environment variable. You can do this by adding the following +line at the bottom of your :file:`~/.profile` file + +.. code-block:: console + + export PATH=/usr/local/bin:/usr/local/sbin:$PATH + +Now, we can install Python 3: + +.. code-block:: console + + $ brew install python3 + +This will take a minute or two. + + +Pip +---------------- + +Homebrew installs ``pip3`` for you. + +``pip3`` is the alias for the Python 3 version of ``pip`` on systems with both +the Homebrew'd Python 2 and 3 installed. + +Working with Python3 +-------------------- + +At this point, you have the system Python 2.7 available, potentially the +:ref:`Homebrew version of Python 2 ` installed, and the Homebrew +version of Python 3 as well. + +.. code-block:: console + + $ python + +will launch the Python 2 interpreter. + +.. code-block:: console + + $ python3 + +will launch the Python 3 interpreter + +``pip3`` and ``pip`` will both be available. If the Homebrew version of Python +2 is not installed, they will be the same. If the Homebrew version of Python 2 +is installed then ``pip`` will point to Python 2 and ``pip3`` will point to +Python 3. + + +Virtual Environments +-------------------- + +A Virtual Environment (commonly referred to as a 'virtualenv') is a tool to keep +the dependencies required by different projects in separate places, by creating +virtual Python environments for them. It solves the "Project X depends on +version 1.x but, Project Y needs 4.x" dilemma, and keeps your global +site-packages directory clean and manageable. + +For example, you can work on a project which requires Django 1.10 while also +maintaining a project which requires Django 1.8. + +To start using this and see more information: :ref:`Virtual Environments ` docs. + +-------------------------------- + +This page is a remixed version of `another guide `_, +which is available under the same license. diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index c0118f68c..3c747bf03 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -13,9 +13,11 @@ other third-party Python libraries. Installation Guides ------------------- -These guides go over the proper installation of :ref:`Python 2.7 ` +These guides go over the proper installation of :ref:`Python ` for development purposes, as well as pip and virtualenv. -- :ref:`Mac OS X `. -- :ref:`Microsoft Windows `. -- :ref:`Ubuntu Linux `. +- :ref:`Python 3 on Mac OS X `. + +- :ref:`Python 2 on Mac OS X `. +- :ref:`Python 2 on Microsoft Windows `. +- :ref:`Python 2 on Ubuntu Linux `. From 53a249a58ec90c04e92247c1fc22a2b69135062b Mon Sep 17 00:00:00 2001 From: Adam Nelson Date: Tue, 15 Mar 2016 09:47:32 -0400 Subject: [PATCH 4/8] Bad tick marks in virtualenv doc --- docs/dev/virtualenvs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 90c7f19df..37841e214 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -12,7 +12,7 @@ For example, you can work on a project which requires Django 1.9 while also maintaining a project which requires Django 1.8. If you are using Python 3, make sure you run something like the following (or -have it in your env variables in `~/.bashrc`): +have it in your env variables in ``~/.bashrc``): .. code-block:: console From 9223381e4e695968931fa5f684cb5dafe2452593 Mon Sep 17 00:00:00 2001 From: Adam Nelson Date: Tue, 15 Mar 2016 10:00:26 -0400 Subject: [PATCH 5/8] Python3 stuff in virtualenv less prominent --- docs/dev/virtualenvs.rst | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 37841e214..ee05a1343 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -11,13 +11,6 @@ dilemma, and keeps your global site-packages directory clean and manageable. For example, you can work on a project which requires Django 1.9 while also maintaining a project which requires Django 1.8. -If you are using Python 3, make sure you run something like the following (or -have it in your env variables in ``~/.bashrc``): - -.. code-block:: console - - $ export VIRTUALENVWRAPPER_PYTHON=/usr/local/bin/python3 - virtualenv ---------- @@ -50,13 +43,18 @@ in the current directory instead. This creates a copy of Python in whichever directory you ran the command in, placing it in a folder named :file:`venv`. -You can also use the Python interpreter of your choice. +You can also use the Python interpreter of your choice (like +:file:`/usr/local/bin/python3`). .. code-block:: console $ virtualenv -p /usr/local/bin/python3 venv -This will use the Python interpreter in :file:`/usr/local/bin/python3` +or change the interpreter globally with an env variable in ``~/.bashrc``: + +.. code-block:: console + + $ export VIRTUALENVWRAPPER_PYTHON=/usr/local/bin/python3 2. To begin using the virtual environment, it needs to be activated: From 328a261c4fd30a9f66690d6c94bd9466a1abb66a Mon Sep 17 00:00:00 2001 From: Adam Nelson Date: Thu, 31 Mar 2016 09:37:57 -0400 Subject: [PATCH 6/8] Re-instated references to setuptools --- docs/dev/virtualenvs.rst | 6 +++--- docs/starting/install/osx.rst | 15 ++++++++++----- docs/starting/installation.rst | 5 ++--- 3 files changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index ee05a1343..fa0bbfc8c 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -44,17 +44,17 @@ This creates a copy of Python in whichever directory you ran the command in, placing it in a folder named :file:`venv`. You can also use the Python interpreter of your choice (like -:file:`/usr/local/bin/python3`). +:file:`/usr/bin/python2.7`). .. code-block:: console - $ virtualenv -p /usr/local/bin/python3 venv + $ virtualenv -p /usr/bin/python2.7 venv or change the interpreter globally with an env variable in ``~/.bashrc``: .. code-block:: console - $ export VIRTUALENVWRAPPER_PYTHON=/usr/local/bin/python3 + $ export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python2.7 2. To begin using the virtual environment, it needs to be activated: diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index ae3f10aea..4ffba8648 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -11,7 +11,7 @@ The latest version of Mac OS X, El Capitan, **comes with Python 2.7 out of the b You do not need to install or configure anything else to use Python. Having said that, I would strongly recommend that you install the tools and libraries described in the next section before you start building Python applications for -real-world use. In particular, you should always install ``pip``, as it makes +real-world use. In particular, you should always install Setuptools, as it makes it much easier for you to install and manage other third-party Python libraries. The version of Python that ships with OS X is great for learning but it's not @@ -40,7 +40,7 @@ package. commandline tools by running ``xcode-select --install`` on the terminal. While OS X comes with a large number of UNIX utilities, those familiar with -Linux systems will notice one key component missing: a package manager. +Linux systems will notice one key component missing: a decent package manager. `Homebrew `_ fills this void. To `install Homebrew `_, open :file:`Terminal` or @@ -69,13 +69,18 @@ Now, we can install Python 2.7: This will take a minute or two. -Pip +Setuptools and Pip ---------------- -Homebrew installs ``pip`` for you. +Homebrew installs Setuptools and ``pip`` for you. + +Setuptools enables you to download and install any compliant Python + -software over a network (usually the Internet) with a single command + -(``easy_install``). It also enables you to add this network installation + -capability to your own Python software with very little work. ``pip`` is a tool for easily installing and managing Python packages, that is -recommended over the deprecated ``easy_install``. It is superior to +recommended over ``easy_install``. It is superior to ``easy_install`` in `several ways `_, and is actively maintained. diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index 3c747bf03..46b9fe4eb 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -7,17 +7,16 @@ If so, you do not need to install or configure anything else to use Python. Having said that, I would strongly recommend that you install the tools and libraries described in the guides below before you start building Python applications for real-world use. In particular, you should always install -Pip, and Virtualenv — they make it much easier for you to use +Setuptools, Pip, and Virtualenv — they make it much easier for you to use other third-party Python libraries. Installation Guides ------------------- These guides go over the proper installation of :ref:`Python ` -for development purposes, as well as pip and virtualenv. +for development purposes, as well as setuptools, pip and virtualenv. - :ref:`Python 3 on Mac OS X `. - - :ref:`Python 2 on Mac OS X `. - :ref:`Python 2 on Microsoft Windows `. - :ref:`Python 2 on Ubuntu Linux `. From b832f669e682d5b4f97e2bb4e71e62f8834871c9 Mon Sep 17 00:00:00 2001 From: Adam Nelson Date: Mon, 14 Nov 2016 14:31:53 -0500 Subject: [PATCH 7/8] Previous merge didnt handle 2 conflicts properly --- docs/dev/virtualenvs.rst | 4 ---- docs/starting/install/osx.rst | 24 ++---------------------- 2 files changed, 2 insertions(+), 26 deletions(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index d8d746c7e..927d213fa 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -8,11 +8,7 @@ projects in separate places, by creating virtual Python environments for them. It solves the "Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps your global site-packages directory clean and manageable. -<<<<<<< HEAD -For example, you can work on a project which requires Django 1.9 while also -======= For example, you can work on a project which requires Django 1.10 while also ->>>>>>> upstream/master maintaining a project which requires Django 1.8. virtualenv diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index bc5e53928..fe081b3d8 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -74,9 +74,6 @@ Now, we can install Python 2.7: $ brew install python -<<<<<<< HEAD -This will take a minute or two. -======= or Python 3: .. code-block:: console @@ -84,7 +81,6 @@ or Python 3: $ brew install python3 This will take a minute or two. ->>>>>>> upstream/master Setuptools and Pip @@ -93,23 +89,13 @@ Setuptools and Pip Homebrew installs Setuptools and ``pip`` for you. Setuptools enables you to download and install any compliant Python -<<<<<<< HEAD - -software over a network (usually the Internet) with a single command - -(``easy_install``). It also enables you to add this network installation - -capability to your own Python software with very little work. - -``pip`` is a tool for easily installing and managing Python packages, that is -recommended over ``easy_install``. It is superior to -``easy_install`` in `several ways -`_, -======= software over a network (usually the Internet) with a single command (``easy_install``). It also enables you to add this network installation capability to your own Python software with very little work. ``pip`` is a tool for easily installing and managing Python packages, -that is recommended over ``easy_install``. It is superior to ``easy_install`` in `several ways `_, ->>>>>>> upstream/master +that is recommended over ``easy_install``. It is superior to ``easy_install`` +in `several ways `_, and is actively maintained. @@ -122,14 +108,8 @@ in separate places, by creating virtual Python environments for them. It solves your global site-packages directory clean and manageable. For example, you can work on a project which requires Django 1.10 while also -<<<<<<< HEAD -maintaining a project which requires Django 1.7. -======= maintaining a project which requires Django 1.8. -To start using this and see more information: :ref:`Virtual Environments ` docs. ->>>>>>> upstream/master - To start using this and see more information: :ref:`Virtual Environments ` docs. -------------------------------- From 0d3c9a131f566f56a6256e3e507fbef3733c93c1 Mon Sep 17 00:00:00 2001 From: Adam Nelson Date: Mon, 14 Nov 2016 14:47:23 -0500 Subject: [PATCH 8/8] Previous merge did not handle 1 more conflict properly :-( --- docs/starting/install/osx.rst | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index fe081b3d8..97baf03d8 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -33,7 +33,6 @@ minimal but unofficial package. .. note:: -<<<<<<< HEAD If you already have XCode installed, do not install OSX-GCC-Installer. In combination, the software can cause issues that are difficult to diagnose. @@ -41,11 +40,7 @@ package. .. note:: If you perform a fresh install of XCode, you will also need to add the commandline tools by running ``xcode-select --install`` on the terminal. -======= - If you already have Xcode installed or plan to use Homebrew, do not install - OSX-GCC-Installer. In combination, the software can cause issues that are - difficult to diagnose. ->>>>>>> upstream/master + While OS X comes with a large number of UNIX utilities, those familiar with Linux systems will notice one key component missing: a decent package manager.