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.

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

Move existing installing packages tutorial into a guide #385

Merged
merged 3 commits into from Oct 9, 2017

Conversation

Projects
None yet
3 participants
@theacodes
Member

theacodes commented Sep 29, 2017

This moves the current "Installing Packages" tutorial into a guide and updates some of the wording and recommendations.

Once this is merged, I will delete the current tutorial and replace it with the pipenv tutorial presently in new-tutorials.

@theacodes theacodes requested review from ncoghlan and pfmoore Sep 29, 2017

@theacodes

This comment has been minimized.

Member

theacodes commented Sep 29, 2017

@pfmoore if you have time I would appreciate your review on this.

@ncoghlan

I like the general direction this is going, but have some suggestions about high level framing, and some of the specifics on *nix systems.

Installing pip
--------------

:ref:`pip` is the the Python package manager. It's used to install and update

This comment has been minimized.

@ncoghlan

ncoghlan Oct 2, 2017

Member

doubled the. I'm tempted to suggest using the word reference in here, (i.e. "the reference Python package manager"), similar to the way we often describe CPython as "the reference Python implementation", even though PyPI's stats tell us that CPython is Python for the vast majority of Python users)

This comment has been minimized.

@theacodes

theacodes Oct 6, 2017

Member

Done and done.


.. code-block:: bash
pip install --upgrade pip

This comment has been minimized.

@ncoghlan

ncoghlan Oct 2, 2017

Member

This doesn't always work properly on Windows due to the way file access locking works when running scripts directly, so python -m pip install --upgrade pip is more reliable.

This comment has been minimized.

@theacodes
.. code-block:: bash
wget https://bootstrap.pypa.io/get-pip.py
sudo python get-pip.py

This comment has been minimized.

@ncoghlan

ncoghlan Oct 2, 2017

Member

sudo python will typically run Python 2.7, so sudo python3 get-pip.py would be more reliable here.

However, we really shouldn't recommend this approach at all, since it's a good way for people to break either their system (if pip is provided natively), or else 3rd party repos like EPEL (if it isn't provided natively, but there are third party pacakges available). Instead, the better way to go is to install the system pip, and then use that to bootstrap a user level install of a more recent version (if the system one isn't already sufficiently recent).

Doing that looks like this:

$ python3 -m pip --version
pip 9.0.1 from /usr/lib/python3.6/site-packages (python 3.6)
$ python3 -m pip install --user --upgrade pip
Requirement already up-to-date: pip in ./.local/lib/python3.6/site-packages

Once the next version of pip is released, then the second command would actually install the newer version as a user install.

This comment has been minimized.

@theacodes

theacodes Oct 6, 2017

Member

Done, I've also switched to the python -m form for virtualenv commands throughout to avoid PATH issues. I left the post-virtualenv pip commands alone because activating a virtualenv will put everything on path.

This guide discusses how to install packages using :ref:`pip` and
:ref:`virtualenv`. These tools are recommended if :ref:`pipenv` does not suit
your project's needs.

This comment has been minimized.

@ncoghlan

ncoghlan Oct 2, 2017

Member

This isn't quite right, as I'd actually recommend folks look at pip-tools and pew before dropping all the way down to the lowest level building blocks.

Essentially, the layering we have is:

  • Comprehensive, but opinionated (the Django and Plone equivalents for Python package management):

    • pipenv: integrated Python-specific environment management & dependency management (default recommendation)
    • hatch: integrates version release management tooling as well (even more opinionated than pipenv)
  • More narrowly focused packages with independent management of concerns (the Flask, SQL Alchemy, and Jinja2 equivalents for Python package management):

    • pip-tools: dependency management
    • pew: virtual environment management
    • flit: build and release management
  • The lowest level building blocks (the wsgiref equivalents for Python package management)

    • pip: package installation management
    • virtualenv/venv: virtual environment creation

This comment has been minimized.

@theacodes

theacodes Oct 6, 2017

Member

Gotcha, do you mind if I defer this for #367 and use the phrase "These are the lowest-level tools for managing Python packages and are recommended if higher-level tools do not suit your needs."?

Doing so will unblock us for now and give a good link point once #367 is ready.

+++++++

The Python installers for Windows include pip. If you setup Python to be in
your ``PATH`` you should have access to pip already:

This comment has been minimized.

@pfmoore

pfmoore Oct 2, 2017

Member

Do we want to presume users have Python on PATH? It's not the default as the py launcher is the recommended approach for accessing Python, and I'd prefer we stick with that as it's "what works out of the box" for all users.

On a default install, pip is available via py -m pip, and the upgrade command below would be py -m pip install --upgrade pip.

This comment has been minimized.

@theacodes

theacodes Oct 6, 2017

Member

Great point. Done.

@theacodes

This comment has been minimized.

Member

theacodes commented Oct 3, 2017

Thanks for reviewing @pfmoore and @ncoghlan - I'm at a team offsite this week but will try to address all of these comments on Friday. :)

@theacodes

This comment has been minimized.

Member

theacodes commented Oct 6, 2017

I think I addressed all comments, please take another look @pfmoore and @ncoghlan? (Thanks!)

@pfmoore

This comment has been minimized.

Member

pfmoore commented Oct 6, 2017

Looks good to me. I have some reservations about the whole section on activating a virtualenv (I've seen a lot of people get confused about what "activation" means and give it a greater significance than is needed) but I don't see a good way of addressing that in a document like this. Longer term, if we move towards recommending higher level tools like pew, this should solve itself, so I don't think it's a problem for now.

@pfmoore

pfmoore approved these changes Oct 6, 2017

@theacodes

This comment has been minimized.

Member

theacodes commented Oct 6, 2017

@pfmoore agreed, I tried to make it a bit more clear by saying that it puts the environment-specific stuff in PATH even though that isn't the whole story.

Thank you for reviewing, I'm gonna give @ncoghlan another chance to take a look before merging.

@ncoghlan

Looks good to me!

@theacodes theacodes merged commit 69cdf5e into pypa:master Oct 9, 2017

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

@theacodes theacodes deleted the theacodes:move-installing-tutorial branch Oct 9, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment