From b884587311184da336419e500cad071ea9950c40 Mon Sep 17 00:00:00 2001 From: Paul Moore Date: Thu, 1 Feb 2024 10:43:42 +0000 Subject: [PATCH 1/4] Add documentation on pip's role as an installer --- docs/html/topics/index.md | 1 + docs/html/topics/workflow.md | 21 +++++++++++++++++++++ 2 files changed, 22 insertions(+) create mode 100644 docs/html/topics/workflow.md diff --git a/docs/html/topics/index.md b/docs/html/topics/index.md index ad467615090..40fd1527944 100644 --- a/docs/html/topics/index.md +++ b/docs/html/topics/index.md @@ -21,4 +21,5 @@ repeatable-installs secure-installs vcs-support python-option +workflow ``` diff --git a/docs/html/topics/workflow.md b/docs/html/topics/workflow.md new file mode 100644 index 00000000000..14ad064ffb2 --- /dev/null +++ b/docs/html/topics/workflow.md @@ -0,0 +1,21 @@ +# Pip is not a workflow 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. + +This "bootstrapping" mechanism was proposed (and accepted) in [PEP +453](https://www.python.org/dev/peps/pep-0453/). From c7c3c4390961f9d7d40e20d0101b4100d1925bf7 Mon Sep 17 00:00:00 2001 From: Paul Moore Date: Thu, 1 Feb 2024 12:59:14 +0000 Subject: [PATCH 2/4] Update docs/html/topics/workflow.md Co-authored-by: chrysle --- docs/html/topics/workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/html/topics/workflow.md b/docs/html/topics/workflow.md index 14ad064ffb2..b9d369571b2 100644 --- a/docs/html/topics/workflow.md +++ b/docs/html/topics/workflow.md @@ -1,4 +1,4 @@ -# Pip is not a workflow tool +# 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. From 9d196373e1b9d50ac653f0bcd381f0967576af52 Mon Sep 17 00:00:00 2001 From: Paul Moore Date: Sat, 3 Feb 2024 19:39:21 +0000 Subject: [PATCH 3/4] Update docs/html/topics/workflow.md Co-authored-by: Ofek Lev --- docs/html/topics/workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/html/topics/workflow.md b/docs/html/topics/workflow.md index b9d369571b2..a2b3aefe7d0 100644 --- a/docs/html/topics/workflow.md +++ b/docs/html/topics/workflow.md @@ -18,4 +18,4 @@ used to gain access to all of the various tools and libraries available on PyPI. In particular, this includes a number of workflow tools. This "bootstrapping" mechanism was proposed (and accepted) in [PEP -453](https://www.python.org/dev/peps/pep-0453/). +453](https://peps.python.org/pep-0453/). From 2233c5fa8fba3b3b6179977436ba263078d9caea Mon Sep 17 00:00:00 2001 From: Paul Moore Date: Mon, 5 Feb 2024 14:11:04 +0000 Subject: [PATCH 4/4] Purpose is package management, not just installation --- docs/html/topics/workflow.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/docs/html/topics/workflow.md b/docs/html/topics/workflow.md index b9d369571b2..895a1232f6a 100644 --- a/docs/html/topics/workflow.md +++ b/docs/html/topics/workflow.md @@ -1,21 +1,40 @@ # 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". +The core purpose of pip is to *manage the packages installed in your +environment*. Whilst package management is an important part of most Python +development workflows, it is only one part. Tasks like creating and managing +environments, configuring and running development tasks, managing the Python +interpreter itself, and managing the overall "project", are not part of pip's +scope. Managing a development workflow as a whole is 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. +As an example, pip provides the `pip wheel` command, which can be used to build +a wheel for your project. However, there is no corresponding command to build a +source distribution. This is because building a wheel is a fundamental step in +installing a package (if that package is only available as source code), whereas +building a source distribution is never needed when installing. Users who need a +tool to build their project should use a dedicated tool like `build`, which +provides commands to build wheels and source distributions. + + ## 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. +In particular, this enables the installation of a number of workflow tools. This "bootstrapping" mechanism was proposed (and accepted) in [PEP 453](https://www.python.org/dev/peps/pep-0453/). + + +## Further information + +The [Packaging User Guide](https://packaging.python.org) discusses Python +project development, and includes tool recommendations for people looking for +further information on how to manage their development workflow. \ No newline at end of file