Add a new tutorial on installing packages #369

theacodes · 2017-08-29T03:51:39Z

Towards #301

Note this is written in the new tutorial format - it is intended to be short, concise, minimal, and opinionated. More guides and tutorials will be added to cover the topics presently covered by the existing installing tutorials.

Also note: this is in the new tutorials directory, so it isn't intended to be immediately consumed. Once the supplemental materials (guides, etc.) are available we can replace the current installing tutorial with this one.

theacodes · 2017-08-29T03:54:55Z

source/new-tutorials/installing/installing-packaging-tools.rst

+    pip 9.0.1 from /usr/local/lib/python2.7/dist-packages (python 2.7)
+
+
+Installing virtualenv


@ncoghlan @dstufft I'm curious if I even need this section - should we just tell them to use venv since this tutorial is Python 3 focused (we can add a note that for Python 2 they need to install and use virtualenv instead). WDYT?

I like the idea of moving Python 2 content to a separate "Setting up Python 2 environments" guide, and then referencing that from relevant locations.

However, for this tutorial, I think this is a place where #118 and #367 apply, so we probably want to start recommending pip install --user pipenv, rather than recommending that folks manage their virtual environments by hand.

(I initially suggested pipsi install pew, but that introduces a bootstrapping problem, where you first need to do pip install --user pipsi in order to get access to the pipsi command. We may still want to suggest that at some point, but it's orthogonal to the question of recommending an environment manager, and currently still has enough bootstrapping problems that it led to @kennethreitz describing the following optional pipsi-based bootstrapping approach for pipenv: http://docs.pipenv.org/en/latest/advanced.html#fancy-installation-of-pipenv)

Everyone I know uses virtualenv on Python 3, not venv.

@kennethreitz Same here, but I'm not sure I actually know anyone that didn't either learn Python 2 first, or else works professionally on maintaining Python 2 software :)

Either way, if we recommend pipenv as the default dependency & environment manager, then whether it's using venv or virtualenv underneath becomes a hidden implementation detail.

@ncoghlan yeah, and pipsi requires users to modify their $PATH, which is just asking too much for a general guide, i think.

ncoghlan

I like the general structure, but I think it would make sense to use these new tutorials to start recommending the more opinionated higher level tools as the default starting point.

ncoghlan · 2017-08-29T04:43:55Z

source/new-tutorials/installing/installing-packaging-tools.rst

+.. Note:: If you're on Linux or macOS, you may need to run this with ``sudo``.
+    In general, you should avoid invoking pip with ``sudo`` as this installs
+    packages globally. However, virtualenv and pip are core utilities that
+    make sense to be installed globally.


Nope, never ever recommend sudo pip, not even for virtualenv and pip. What folks can do is pip install --upgrade --user virtualenv, since their personally upgraded copy will shadow the system one for them, without being at risk of being overwritten by reinstallation of the system level package.

ncoghlan · 2017-08-29T04:46:08Z

source/new-tutorials/installing/installing-packaging-tools.rst

+    pip 9.0.1 from /usr/local/lib/python2.7/dist-packages (python 2.7)
+
+
+Installing virtualenv


I like the idea of moving Python 2 content to a separate "Setting up Python 2 environments" guide, and then referencing that from relevant locations.

However, for this tutorial, I think this is a place where #118 and #367 apply, so we probably want to start recommending pip install --user pipenv, rather than recommending that folks manage their virtual environments by hand.

ncoghlan · 2017-08-29T04:48:29Z

source/new-tutorials/installing/installing-packaging-tools.rst

+    pip 9.0.1 from /usr/local/lib/python2.7/dist-packages (python 2.7)
+
+
+Installing virtualenv


(I initially suggested pipsi install pew, but that introduces a bootstrapping problem, where you first need to do pip install --user pipsi in order to get access to the pipsi command. We may still want to suggest that at some point, but it's orthogonal to the question of recommending an environment manager, and currently still has enough bootstrapping problems that it led to @kennethreitz describing the following optional pipsi-based bootstrapping approach for pipenv: http://docs.pipenv.org/en/latest/advanced.html#fancy-installation-of-pipenv)

ncoghlan · 2017-08-29T04:49:40Z

source/new-tutorials/installing/index.rst

+
+This tutorial walks you through installing and using Python packages. It will
+show you how to install and use the necessary tools and make strong
+recommendations on best practices. Keep in mind that the Python packging


Typo: packging

ncoghlan · 2017-08-29T04:50:13Z

source/new-tutorials/installing/index.rst

+This tutorial walks you through installing and using Python packages. It will
+show you how to install and use the necessary tools and make strong
+recommendations on best practices. Keep in mind that the Python packging
+ecosystem is a varied one so this isn't the only way to install and use


Slight wording tweak: ...a broad and varied one...

ncoghlan · 2017-08-29T04:50:45Z

source/new-tutorials/installing/index.rst

+show you how to install and use the necessary tools and make strong
+recommendations on best practices. Keep in mind that the Python packging
+ecosystem is a varied one so this isn't the only way to install and use
+Python packages, however, it does cover the most common use cases.


Tweak: most common tools and use cases

ncoghlan · 2017-08-29T04:57:45Z

source/new-tutorials/installing/installing-and-using-packages.rst

+you read this tutorial make sure you have all the packaging tools by reading
+:doc:`installing-packaging-tools`.
+
+Creating a virtualenv


As per #367, let's lead with pipenv for the new tutorials. So this section would introduce pipenv --three (initialisation), pipenv shell (activation) and pipenv install (installing components)

kennethreitz · 2017-08-29T05:04:11Z

Thanks for using Requests as the example! ✨🍰✨

theacodes · 2017-08-29T05:13:13Z

Thanks for reviewing @kennethreitz and @ncoghlan. I agree on pipenv - let me throw together a draft on that (hopefully tomorrow) and we'll go from there. That'll likely reduce this tutorial to just one page. :)

Two questions:

Does --user require additional setup? Doesn't the user need to put site.USER_BASE in their PATH? (According to pip install --user should check that the user's $PATH is correct pip#3813 it looks like that's true).
Is pipenv well tested on Windows? I didn't see anything in the documentation about Windows (e.g. how does pipenv shell work?).

We can add separate guides for using pip/virtualenv for those who want to know.

kennethreitz · 2017-08-29T05:15:37Z

@jonparrott yep, we have a full Windows test suite (down at the moment, but it's historically been running and everything is kept up to date) and put an exhaustive amount of work to support Windows. Pew provides Windows support for pew shell, thankfully.

Windows isn't mentioned in the documentation, because it shouldn't need to be specially mentioned — it should just work.

theacodes · 2017-08-29T05:18:51Z

Good to hear. How much of a pain is it to bootstrap pipenv?

…

On Mon, Aug 28, 2017, 10:15 PM Kenneth Reitz ***@***.***> wrote: @jonparrott <https://github.com/jonparrott> yep, we have a full windows test suite (down at the moment, but it's historically been running and everything is kept up to date) and put an exhaustive amount of work to support windows. Pew provides windows support, thankfully. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#369 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAPUc16YpPyDyhEmdLKhhXVHIwuBplpeks5sc555gaJpZM4PFWSW> .

kennethreitz · 2017-08-29T05:19:57Z

I have a get-pipenv Python script (lifted from get-pip) that will install pip and then pipenv for you.

theacodes · 2017-08-29T05:25:31Z

Awesome. Thank you.

…

On Mon, Aug 28, 2017, 10:19 PM Kenneth Reitz ***@***.***> wrote: I have a get-pipenv <https://github.com/kennethreitz/pipenv/blob/master/get-pipenv.py> executable (lifted from get-pip) that will install pip and then pipenv for you. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#369 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAPUc-DxBQCrM1xJZuKNGLCgTvlR6uLHks5sc599gaJpZM4PFWSW> .

ncoghlan · 2017-08-29T07:15:05Z

Good point re PATH - I'm used to pip install --user Just Working, since Fedora's defaults are set up that way :)

theacodes · 2017-08-30T02:48:05Z

Alright - re-wrote this to use Pipenv. :) Please take another look.

kennethreitz · 2017-08-30T02:48:25Z

\o/

kennethreitz

✨🍰✨

kennethreitz · 2017-08-30T02:49:28Z

source/new-tutorials/installing-and-using-packages.rst

+
+    python --version
+
+You should get some output like ``3.6.1``. If you do not have Python, please


Why not 3.6.2?

It's just example output (my mac has 3.6.1)

I'd just document it as 3.6.2, personally, even if I had 3.6.1 installed.

kennethreitz · 2017-08-30T02:50:28Z

source/new-tutorials/installing-and-using-packages.rst

+
+.. code-block:: python
+
+    pip install --user pipenv


.. code-block:: bash $ pip install --user pipenv

kennethreitz · 2017-08-30T02:51:39Z

source/new-tutorials/installing-and-using-packages.rst

+    you'll need to add the `user base`_'s ``bin`` directory to your ``PATH``.
+    You can find the user base by running ``import site; print(site.USER_BASE)``
+    in Python. For example, on Linux this will return ``~/.local`` so you'll
+    need to add ``~/.local/bin`` to your ``PATH``.


Maybe add a note that this is typically done in ~/.profile?

python -m site is a straightforward command to run that prints the value of USER_BASE (amongst other things)

TIL! I switched to using that and added links to documentation on how to update your path.

kennethreitz · 2017-08-30T02:52:08Z

source/new-tutorials/installing-and-using-packages.rst

+
+.. code-block:: bash
+
+    cd myproject


I really like having $ preceding shell commands

But I can understand why you'd want to not have that, if you don't want Windows users to feel alienated. I don't think it harms them, though.

Based on user research from cloud.google.com we determined that users indeed do get tripped up on this (as they tend to copy/paste). There's a css trick to add the $ in the margin so that it's not picked up on copy, but that would need to be done separately from this PR. The blocks are all annotated as bash, so if we do decide to do it at a later date it'll be easy.

kennethreitz · 2017-08-30T02:53:17Z

source/new-tutorials/installing-and-using-packages.rst

+
+    Creating a Pipfile for this project...
+    Creating a virtualenv for this project...
+    Using base prefix '/usr/local/Cellar/python3/3.6.1/Frameworks/Python.framework/Versions/3.6'


I def think 3.6.2 should be used for the docs, as best practice :)

Again, just example output. It'll be difficult to keep this up-to-date with the latest patch version, but we can likely try to bump for every minor version.

I'd just patch it by hand :)

kennethreitz · 2017-08-30T02:54:01Z

source/new-tutorials/installing-and-using-packages.rst

+
+    response = requests.get('https://httpbin.org/ip')
+
+    print('Your IP is {}'.format(response.json['origin']))


needs to be {0} to work w/ Python 2.6. Not sure if that's a target or not.

kennethreitz

Love it!

kennethreitz · 2017-08-30T03:10:01Z

source/new-tutorials/installing-and-using-packages.rst

+Next steps
+----------
+
+Congratulations, you now know how to install and use Python packages! ✨ 🍰 ✨


ncoghlan

I really like the direction this is going - just some comments on specifics inline.

ncoghlan · 2017-08-30T04:22:28Z

source/key_projects.rst

+
+`Source <https://github.com/pypa/pipfile>`__
+
+``Pipfile`` and its sister ``Pipfile.lock`` are a replacement for the existing


Rather than "... a replacement for the existing standard :ref:pip's ...", I'd word this as "... a higher level application-centric alternative to :ref:pip's lower level ...".

I think that's important, as Pipfile deliberately isn't a complete replacement for requirements.txt, and if you're doing things that don't quite fit the "develop and publish an integrated Python application" usage model, you're quite likely to end up wanting to drop back down to the less opinionated lower level interface.

I just lifted this directly from PIpfile's repo, but changed it to match your wording.

ncoghlan · 2017-08-30T04:35:19Z

source/new-tutorials/installing-and-using-packages.rst

+recommendations on best practices. Keep in mind that the Python packaging
+ecosystem is a broad and varied one so this isn't the only way to install and
+use Python packages, however, it does cover the most common tools and use
+cases.


I think we may be able to provide better guidance on applicability here. Perhaps replace the second sentence with something like:

Keep in mind that Python is used for a great many different purposes, and precisely how you want to manage your dependencies may change based on how you decide to publish your software. The guidance 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.

And then once we have a guide or discussion to link to, we can add a pointer to that with text like "If you find this approach isn't working well for you or your use case, you may want to explore these [other options](<link>)"

ncoghlan · 2017-08-30T04:36:03Z

source/new-tutorials/installing-and-using-packages.rst

+cases.
+
+.. Note:: This guide is written for Python 3, however, these instructions
+    should work fine on Python 2.


I'd qualify this as Python 2.7 (so we can ignore 2.6 compatibility)

ncoghlan · 2017-08-30T04:39:03Z

source/new-tutorials/installing-and-using-packages.rst

+
+    python --version
+
+You should get some output like ``3.6.2``. If you do not have Python, please


Given your discussion with @kennethreitz , perhaps we could abuse the |release| notation to make it easy to update the Python version that we use for examples in one central place?

Alternatively, we could set rst_prolog to define a custom substitution field: https://stackoverflow.com/questions/36320992/sphinx-documentation-variables/36331678#36331678

This is probably a good place to mention the following error with a caveat like "If you're new to programming and the command line in general, you may see an error like this":

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

and explain that all of the code blocks in the tutorial are intended to be run at an operating system prompt, rather than at the interactive Python prompt.

https://opentechschool.github.io/python-beginners/en/getting_started.html#what-is-python-exactly was the best tutorial I could find on the exact details of how to open one.

I tried the substitution but it doesn't work in code blocks or inline code markup, so it doesn't help here. :(

Great suggestion about the error. Added. :)

ncoghlan · 2017-08-30T04:43:15Z

source/new-tutorials/installing-and-using-packages.rst

+Pipenv will install the excellent `Requests`_ library and create a ``Pipfile``
+for you in your project's directory. The :ref:`Pipfile` is used to track which
+dependencies your project needs in case you need to re-install them, such as
+when you share your project with others. You should get output similar to this:


I'd add in parentheses (although the exact paths shown will vary based on your operating system and how you installed Python)

ncoghlan · 2017-08-30T04:45:43Z

source/new-tutorials/installing-and-using-packages.rst

+    you'll need to add the `user base`_'s ``bin`` directory to your ``PATH``.
+    You can find the user base by running ``import site; print(site.USER_BASE)``
+    in Python. For example, on Linux this will return ``~/.local`` so you'll
+    need to add ``~/.local/bin`` to your ``PATH``.


python -m site is a straightforward command to run that prints the value of USER_BASE (amongst other things)

theacodes · 2017-08-30T05:05:04Z

Thanks for the thorough review, @ncoghlan. I'll try to address all of these tomorrow before I leave for vacation. :)

…

On Tue, Aug 29, 2017, 9:59 PM Nick Coghlan ***@***.***> wrote: ***@***.**** commented on this pull request. I really like the direction this is going - just some comments on specifics inline. ------------------------------ In source/key_projects.rst <#369 (comment)> : > @@ -76,6 +76,16 @@ Dev irc:#pypa-dev A tool for installing Python packages. +.. _Pipfile: + +Pipfile +======= + +`Source <https://github.com/pypa/pipfile>`__ + +``Pipfile`` and its sister ``Pipfile.lock`` are a replacement for the existing Rather than "... a replacement for the existing standard :ref:pip's ...", I'd word this as "... a higher level application-centric alternative to :ref:pip's lower level ...". I think that's important, as Pipfile deliberately *isn't* a complete replacement for requirements.txt, and if you're doing things that don't quite fit the "develop and publish an integrated Python application" usage model, you're quite likely to end up wanting to drop back down to the less opinionated lower level interface. ------------------------------ In source/new-tutorials/installing-and-using-packages.rst <#369 (comment)> : > @@ -0,0 +1,166 @@ +Installing and using packages +============================= + +This tutorial walks you through installing and using Python packages. It will +show you how to install and use the necessary tools and make strong +recommendations on best practices. Keep in mind that the Python packaging +ecosystem is a broad and varied one so this isn't the only way to install and +use Python packages, however, it does cover the most common tools and use +cases. I think we may be able to provide better guidance on applicability here. Perhaps replace the second sentence with something like: Keep in mind that Python is used for a great many different purposes, and precisely how you want to manage your dependencies may change based on how you decide to publish your software. The guidance 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. And then once we have a guide or discussion to link to, we can add a pointer to that with text like "If you find this approach isn't working well for you or your use case, you may want to explore these [other options](<link>)" ------------------------------ In source/new-tutorials/installing-and-using-packages.rst <#369 (comment)> : > @@ -0,0 +1,166 @@ +Installing and using packages +============================= + +This tutorial walks you through installing and using Python packages. It will +show you how to install and use the necessary tools and make strong +recommendations on best practices. Keep in mind that the Python packaging +ecosystem is a broad and varied one so this isn't the only way to install and +use Python packages, however, it does cover the most common tools and use +cases. + +.. Note:: This guide is written for Python 3, however, these instructions + should work fine on Python 2. I'd qualify this as Python 2.7 (so we can ignore 2.6 compatibility) ------------------------------ In source/new-tutorials/installing-and-using-packages.rst <#369 (comment)> : > + +.. Note:: This guide is written for Python 3, however, these instructions + should work fine on Python 2. + + +Make sure you've got Python & pip +----------------------------- ---- + +Before you go any further, make sure you have Python and that it's avalable +from your command line. You can check this by simply running: + +.. code-block:: bash + + python --version + +You should get some output like ``3.6.2``. If you do not have Python, please Given your discussion with @kennethreitz <https://github.com/kennethreitz> , perhaps we could abuse the |release| notation to make it easy to update the Python version that we use for examples in one central place? Alternatively, we could set rst_prolog to define a custom substitution field: https://stackoverflow.com/questions/36320992/sphinx-documentation-variables/36331678#36331678 ------------------------------ In source/new-tutorials/installing-and-using-packages.rst <#369 (comment)> : > +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 +tutorial) and run: + +.. code-block:: bash + + cd myproject + pipenv install requests + +Pipenv will install the excellent `Requests`_ library and create a ``Pipfile`` +for you in your project's directory. The :ref:`Pipfile` is used to track which +dependencies your project needs in case you need to re-install them, such as +when you share your project with others. You should get output similar to this: I'd add in parentheses (although the exact paths shown will vary based on your operating system and how you installed Python) ------------------------------ In source/new-tutorials/installing-and-using-packages.rst <#369 (comment)> : > +it's a higher-level tool that simplifies dependency management for common use +cases. + +Use ``pip`` to install Pipenv: + +.. code-block:: python + + pip install --user pipenv + + +.. 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 ``bin`` directory to your ``PATH``. + You can find the user base by running ``import site; print(site.USER_BASE)`` + in Python. For example, on Linux this will return ``~/.local`` so you'll + need to add ``~/.local/bin`` to your ``PATH``. python -m site is a straightforward command to run that prints the value of USER_BASE (amongst other things) ------------------------------ In source/new-tutorials/installing-and-using-packages.rst <#369 (comment)> : > + +.. Note:: This guide is written for Python 3, however, these instructions + should work fine on Python 2. + + +Make sure you've got Python & pip +----------------------------- ---- + +Before you go any further, make sure you have Python and that it's avalable +from your command line. You can check this by simply running: + +.. code-block:: bash + + python --version + +You should get some output like ``3.6.2``. If you do not have Python, please This is probably a good place to mention the following error with a caveat like "If you're new to programming and the command line in general, you may see an error like this": >>> python Traceback (most recent call last): File "<stdin>", line 1, in <module> NameError: name 'python' is not defined and explain that all of the code blocks in the tutorial are intended to be run at an *operating system* prompt, rather than at the interactive Python prompt. https://opentechschool.github.io/python-beginners/en/getting_started.html#what-is-python-exactly was the best tutorial I could find on the exact details of how to open one. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#369 (review)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAPUcwPZztGgeAt2g_fWvo6Mt9auU4Abks5sdOxMgaJpZM4PFWSW> .

theacodes

All comments addressed. @ncoghlan please take another look? :)

theacodes · 2017-08-30T16:43:26Z

source/key_projects.rst

+
+`Source <https://github.com/pypa/pipfile>`__
+
+``Pipfile`` and its sister ``Pipfile.lock`` are a replacement for the existing


I just lifted this directly from PIpfile's repo, but changed it to match your wording.

theacodes · 2017-08-30T16:44:32Z

source/new-tutorials/installing-and-using-packages.rst

+recommendations on best practices. Keep in mind that the Python packaging
+ecosystem is a broad and varied one so this isn't the only way to install and
+use Python packages, however, it does cover the most common tools and use
+cases.


theacodes · 2017-08-30T16:45:29Z

source/new-tutorials/installing-and-using-packages.rst

+cases.
+
+.. Note:: This guide is written for Python 3, however, these instructions
+    should work fine on Python 2.


theacodes · 2017-08-30T17:04:40Z

source/new-tutorials/installing-and-using-packages.rst

+
+    python --version
+
+You should get some output like ``3.6.2``. If you do not have Python, please


I tried the substitution but it doesn't work in code blocks or inline code markup, so it doesn't help here. :(

Great suggestion about the error. Added. :)

theacodes · 2017-08-30T17:30:47Z

source/new-tutorials/installing-and-using-packages.rst

+    you'll need to add the `user base`_'s ``bin`` directory to your ``PATH``.
+    You can find the user base by running ``import site; print(site.USER_BASE)``
+    in Python. For example, on Linux this will return ``~/.local`` so you'll
+    need to add ``~/.local/bin`` to your ``PATH``.


TIL! I switched to using that and added links to documentation on how to update your path.

theacodes · 2017-08-30T17:31:55Z

source/new-tutorials/installing-and-using-packages.rst

+Pipenv will install the excellent `Requests`_ library and create a ``Pipfile``
+for you in your project's directory. The :ref:`Pipfile` is used to track which
+dependencies your project needs in case you need to re-install them, such as
+when you share your project with others. You should get output similar to this:


…ott/python-packaging-user-guide into new-tutorial-installing-packages

kennethreitz · 2017-08-30T17:38:30Z

source/new-tutorials/installing-and-using-packages.rst

+    It's because this command is intended to be run in a *shell* (also called
+    a *terminal* or *console*). See the Python for Beginners
+    `getting started tutorial`_ for an introduction to using your operating
+    system's shell and interacting with Python.


kennethreitz · 2017-08-30T17:39:14Z

source/new-tutorials/installing-and-using-packages.rst

+    site information including the user base. For example, on Linux this will
+    return ``USER_BASE: '~/.local'`` so you'll need to add ``~/.local/bin`` to
+    your ``PATH``. On Linux and macOS you can set your ``PATH`` permanently
+    by `modifying ~/.profile`_. On Windows you can set the user


`` around ~/.profile ?

rst doesn't like it. :)

Ah, the annoyances or ReST. It's also impossible to have both bold and italics at the same time!

It's the worst option except for all of the other options.

duggelz · 2017-08-30T18:11:46Z

source/new-tutorials/installing-and-using-packages.rst

+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


This renders as two lines of unformatted text in the preview, is that a quirk of the preview or a bug (or intentional)? It looks like this:

Note This guide is written for Python 3, however, these instructions should work fine on Python 2.7.

yeah github's preview is garbage

kennethreitz · 2017-08-30T22:18:09Z

Really excited about this! If I can help accelerate this landing, let me know what needs done.

ncoghlan

This looks good to me - I'd actually be fine with merging it as is, and then following up with additional PRs.

ncoghlan · 2017-08-31T01:00:11Z

source/new-tutorials/installing-and-using-packages.rst

+install the latest 3.x version from `python.org`_ or refer to the
+`Installing Python`_ section of the Hitchhiker's Guide to Python.
+
+.. Note:: If you're newcomer and you get an error like this:


Typo: Missing "a" before newcomer

Good catch, done.

ncoghlan · 2017-08-31T01:03:24Z

source/new-tutorials/installing-and-using-packages.rst

+          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


Might it be worth emphasising that this note also applies to all the other commands in the tutorial? For example:

It's because this command, and the other suggested commands in this tutorial, are intended ...

ncoghlan · 2017-08-31T01:05:21Z

source/new-tutorials/installing-and-using-packages.rst

+There's more resources you can look at to learn about installing and using
+Python packages:
+
+.. TODO Link to additional guides and resources.


Maybe make these TODOs visible in the rendered version so there aren't just blank spaces while the link targets are being worked on?

ncoghlan · 2017-08-31T01:28:59Z

source/new-tutorials/installing-and-using-packages.rst

+If you find this approach isn't working well for you or your use case, you may
+want to explore these other approaches:
+
+.. TODO Link to alternatives


Suggested initial set of links:

briefcase: briefcase is a tool that focuses on defining applications as Python packages, and then using that package definition to generate native application installers for popular client operating systems

pex: PEX is a single-file distribution format for executable Python virtual environments as zip archives containing a __main__.py file. Their main runtime requirement is that a suitable Python interpreter be available on the system running the application.

pipsi: Similar to pex, pipsi aims to run applications in self-contained virtual environments. Unlike pex, it generates these virtual environments dynamically inside the user's home directory for applications available as Python packages.

pew: the underlying virtual environment manager used by pipenv (this is a lower level tool that offers more flexibility in where, when, and how virtual environments are created and updated)

pip-tools: automated requirements.txt file management that distinguishes between abstract dependency combinations that are expected to work, and the specific pinned versions that will be tested and/or deployed (this is a lower level tool that offers more flexibility in when and how dependencies are installed and updated)

conda: conda is a "cross-platform platform" that manages the Python interpreter and external binary dependencies in addition to managing Python modules. It is most useful in situations where it is easier to ensure that the conda package manager is preinstalled than it is to ensure that a suitable Python version is available.

And then make a note that the above list only covers cross-platform tools, and there are also other platform specific options available if users are only interested in a limited set of platforms.

I don't want to put all of this in this doc, but it does make sense for a general overview guide. Moved these to #367 (comment) for tracking. :)

kennethreitz · 2017-08-31T01:46:47Z

💫✨🍰✨💫

kennethreitz · 2017-08-31T01:47:14Z

Does this get auto-deployed?

theacodes · 2017-08-31T01:49:32Z

Yes - the Fastly config makes it take a second but it's now published here:

https://packaging.python.org/new-tutorials/installing-and-using-packages/

Feel free to share this link (we need feedback!), but keep in mind the URL is temporary. We'll eventually move this into /tutorials/installing-and-using-packages once I can ensure no content in the existing tutorial will be lost. :)

Thanks for reviewing @ncoghlan and @kennethreitz. :D

kennethreitz · 2017-08-31T01:59:11Z

Replicated on Python-Guide.org and Pipenv.org (with permission from @jonparrott):

Will link to this guide as the canonical source of truth, once the final URL has landed.

qwcode · 2017-11-27T19:44:36Z

what's the plan to make this the [alternative] official tutorial? as it is, still sitting under a unlinked "new-tutorials" segment?

@ncoghlan @jonparrott

theacodes · 2017-11-27T20:01:36Z

We had some contention on this, but the path forward is detailed in #394 (comment). I just have to find some time to work on it.

ncoghlan · 2017-11-27T21:47:41Z

@jonparrott If you're currently busy, perhaps it would be easier if I put a PR together, so you only needed to review it, rather than write it?

theacodes · 2017-11-27T21:48:44Z

Go for it. :) I'm always happy to review.

ncoghlan · 2017-11-29T11:20:01Z

New PR: #402

add a new tutorial on installing packages

f461ba7

theacodes requested review from ddbeck and ncoghlan August 29, 2017 03:51

theacodes commented Aug 29, 2017

View reviewed changes

ncoghlan reviewed Aug 29, 2017

View reviewed changes

Re-write tutorial to use pipenv

e0f6ae6

theacodes force-pushed the new-tutorial-installing-packages branch from 85a6ad5 to e0f6ae6 Compare August 30, 2017 02:47

kennethreitz suggested changes Aug 30, 2017

View reviewed changes

Jon Wayne Parrott added 2 commits August 29, 2017 20:05

Use Python 2.6 compatible format string

9532e32

3.6.2

31ce3d5

kennethreitz approved these changes Aug 30, 2017

View reviewed changes

kennethreitz reviewed Aug 30, 2017

View reviewed changes

ncoghlan reviewed Aug 30, 2017

View reviewed changes

Address review comments

8e4d638

theacodes commented Aug 30, 2017

View reviewed changes

Merge branch 'new-tutorial-installing-packages' of github.com:jonparr…

b102d60

…ott/python-packaging-user-guide into new-tutorial-installing-packages

kennethreitz reviewed Aug 30, 2017

View reviewed changes

duggelz reviewed Aug 30, 2017

View reviewed changes

ncoghlan approved these changes Aug 31, 2017

View reviewed changes

Address review comments

0bf3803

theacodes merged commit f3691de into pypa:master Aug 31, 2017

theacodes deleted the new-tutorial-installing-packages branch August 31, 2017 01:46

ncoghlan mentioned this pull request Sep 28, 2017

Recommend a default cross platform virtual environment management tool #118

Closed

		pip 9.0.1 from /usr/local/lib/python2.7/dist-packages (python 2.7)


		Installing virtualenv


		python --version

		You should get some output like ``3.6.1``. If you do not have Python, please


		response = requests.get('https://httpbin.org/ip')

		print('Your IP is {}'.format(response.json['origin']))


		`Source <https://github.com/pypa/pipfile>`__

		``Pipfile`` and its sister ``Pipfile.lock`` are a replacement for the existing


		python --version

		You should get some output like ``3.6.2``. If you do not have Python, please

Add a new tutorial on installing packages #369

Add a new tutorial on installing packages #369

Conversation

theacodes commented Aug 29, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kennethreitz Aug 29, 2017 • edited Loading

Choose a reason for hiding this comment

ncoghlan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kennethreitz commented Aug 29, 2017

theacodes commented Aug 29, 2017

kennethreitz commented Aug 29, 2017 • edited Loading

theacodes commented Aug 29, 2017 via email

kennethreitz commented Aug 29, 2017 • edited Loading

theacodes commented Aug 29, 2017 via email

ncoghlan commented Aug 29, 2017

theacodes commented Aug 30, 2017

kennethreitz commented Aug 30, 2017

kennethreitz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kennethreitz Aug 30, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kennethreitz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ncoghlan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

theacodes commented Aug 30, 2017 via email

theacodes left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kennethreitz Aug 30, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kennethreitz Aug 29, 2017 •

edited

Loading

kennethreitz commented Aug 29, 2017 •

edited

Loading

kennethreitz commented Aug 29, 2017 •

edited

Loading

kennethreitz Aug 30, 2017 •

edited

Loading

kennethreitz Aug 30, 2017 •

edited

Loading