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

Add documentation on pip's role as an installer #12503

Merged
merged 7 commits into from
Feb 20, 2024
Merged

Add documentation on pip's role as an installer #12503

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b884587
Add documentation on pip's role as an installer
pfmoore Feb 1, 2024
c7c3c43
Update docs/html/topics/workflow.md
pfmoore Feb 1, 2024
9d19637
Update docs/html/topics/workflow.md
pfmoore Feb 3, 2024
2233c5f
Purpose is package management, not just installation
pfmoore Feb 5, 2024
32aec4d
Merge branch 'workflow_tool' of https://github.com/pfmoore/pip into w…
pfmoore Feb 5, 2024
26514b2
Merge branch 'main' into workflow_tool
pfmoore Feb 5, 2024
d904811
Merge branch 'main' into workflow_tool
pfmoore Feb 13, 2024
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
1 change: 1 addition & 0 deletions docs/html/topics/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,5 @@ repeatable-installs
secure-installs
vcs-support
python-option
workflow
```
21 changes: 21 additions & 0 deletions docs/html/topics/workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Pip is not a workflow management tool

The core purpose of pip is to *install packages*. Whilst installing packages is
an important part of most Python development workflows, it is only one part.
Managing a development workflow is, in itself, a complex task and one where
there are many views on the "correct approach".

Pip has a number of features which make it useful in development workflows - for
example, the ability to install the current project via `pip install .`,
editable installs, and requirements files. However, there is no intention that
pip will manage the workflow as a whole.

## The role of `ensurepip`

Pip is available in a standard Python installation, via the `ensurepip` stdlib
module. This provides users with an "out of the box" installer, which can be
used to gain access to all of the various tools and libraries available on PyPI.
In particular, this includes a number of workflow tools.
Copy link
Contributor

@chrysle chrysle Feb 3, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In particular, this includes a number of workflow tools.
In particular, this includes a number of [workflow management tools](https://packaging.python.org/en/latest/tutorials/managing-dependencies/).

I'd find this worth mentioning. Feel free to discard.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the suggestion, but I don't personally think "managing dependencies" is the whole story here - there's environment management, project templates, running tests and other project-specific actions, and a bunch of other stuff that "workflow tools" do which complicate the whole issue. Also, I thought the PUG was being updated at the moment, so I'm reluctant to try to link to specific sections while that's going on. If pressed, I'd be willing to link to the top level of the PUG at the end of the first paragraph:

... one where there are many views on the "correct approach". The Packaging User Guide covers this in more detail.

but I honestly think that distracts from the core message here.

I'm going to stick with my instinct that pip shouldn't get involved in all this, and keep it simple and descriptive.

Having said that, I'd still like to hear from the other @pypa/pip-committers before merging. I think we should at least have rough consensus before making statements about pip's "core purpose" in the official documentation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't personally think "managing dependencies" is the whole story here

Yes, I agree. Only this was the most fitting source I could find (at the moment). Linking to the tool recommendations would be better.

If pressed,

Surely not ;-). I'm just a passer-by.

I'd be willing to link to the top level of the PUG at the end of the first paragraph:

A PUG link would definitely be helpful, IMHO.


This "bootstrapping" mechanism was proposed (and accepted) in [PEP
453](https://www.python.org/dev/peps/pep-0453/).
pfmoore marked this conversation as resolved.
Show resolved Hide resolved
Loading