pypa / pypa/packaging.python.org

Create a new guide for setting up a baseline Python environment

Open
#396 18 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

component: tutorials help wanted type: enhancement
Dominant language
Python
Stars
1.7k
Forks
1.7k
Avg merge
3d 12h
Merged PRs (30d)
4

Description

A couple of things I've realised we need to clearly establish for the packaging user guide are:

  • Which commands can folks contributing to the packaging guide or working on the PyPI user experience assume will "just work" on an end user's machine?
  • How much guidance should the packaging tutorials provide on ensuring a system is in that state, given the wide variety of potential starting states?

Right now, we don't clearly document those environmental assumptions anywhere, which then makes it hard to provide a checklist for people to work through and ensure their environment is set up correctly.

The closest we currently get to this is to include a fairly cursory introduction to virtualenv in the package installation tutorial, and then implicitly assuming that the following is true in the rest of the guide:

  • the user is working at a command prompt (whether inside their IDE, or in an actual system shell)
  • the command python will run the desired version of Python
  • the commands pip install and python -m pip install will be essentially equivalent (aside from the differences when upgrading pip itself on Windows) and install packages into the desired version of Python
  • any executables installed that way will be executable from that command prompt
  • any Python import packages installed that way will be importable from a Python shell started in that environment

Those assumptions are true once you're inside an activated virtual environment, but they're not true in the general case due to the differences between per-user Python installations and system-wide ones, and the differences in cross-platform conventions when it comes to learning how to start Python.

(Issue prompted by https://mail.python.org/pipermail/python-ideas/2017-November/047708.html, #394, and https://github.com/pypa/pip/issues/3164)

Additional related documentation:

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the existing packaging user guide, the virtualenv discussion in the package installation tutorial, and the linked Linux and CPython installation guides. Define the supported baseline assumptions and cross-platform setup guidance, then document a checklist that makes those assumptions explicit for contributors and PyPI users.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.