Move existing installing packages tutorial into a guide #385
Conversation
|
@pfmoore if you have time I would appreciate your review on this. |
| Installing pip | ||
| -------------- | ||
|
|
||
| :ref:`pip` is the the Python package manager. It's used to install and update |
There was a problem hiding this comment.
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)
|
|
||
| .. code-block:: bash | ||
|
|
||
| pip install --upgrade pip |
There was a problem hiding this comment.
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.
| .. code-block:: bash | ||
|
|
||
| wget https://bootstrap.pypa.io/get-pip.py | ||
| sudo python get-pip.py |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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. | ||
|
|
There was a problem hiding this comment.
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 thanpipenv)
-
More narrowly focused packages with independent management of concerns (the Flask, SQL Alchemy, and Jinja2 equivalents for Python package management):
pip-tools: dependency managementpew: virtual environment managementflit: build and release management
-
The lowest level building blocks (the
wsgirefequivalents for Python package management)pip: package installation managementvirtualenv/venv: virtual environment creation
There was a problem hiding this comment.
| +++++++ | ||
|
|
||
| The Python installers for Windows include pip. If you setup Python to be in | ||
| your ``PATH`` you should have access to pip already: |
There was a problem hiding this comment.
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.
|
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. |
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
pipenvtutorial presently innew-tutorials.