pypa / pypa/packaging.python.org

Create a new guide for setting up a baseline Python environment

Offen
#396 18 Kommentare 2 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

component: tutorials help wanted type: enhancement
Vorherrschende Sprache
Python
Sterne
1.7k
Forks
1.7k
Ø Merge
3 T. 12 Std.
Gemergte PRs (30 T.)
4

Beschreibung

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:

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginne damit, den bestehenden Benutzerleitfaden zur Paketierung, die Diskussion über virtualenv im Tutorial zur Paketinstallation sowie die verlinkten Installationsleitfäden für Linux und CPython zu lesen. Lege die unterstützten Basisannahmen und plattformübergreifenden Einrichtungsrichtlinien fest und dokumentiere anschließend eine Checkliste, die diese Annahmen für Contributors und PyPI-Benutzer explizit macht.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.