pypa / pypa/packaging.python.org

Create a new guide for setting up a baseline Python environment

Aperta
#396 18 commenti 2 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

component: tutorials help wanted type: enhancement
Lingua principale
Python
Stelle
1.7k
Fork
1.7k
Merge medio
3g 12h
PR unite (30g)
4

Descrizione

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:

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Direzione di ricerca

Inizia leggendo la guida utente esistente sul packaging, la discussione su virtualenv nel tutorial sull'installazione dei pacchetti e le guide di installazione collegate per Linux e CPython. Definisci le ipotesi di base supportate e le indicazioni per la configurazione multipiattaforma, quindi documenta una checklist che renda esplicite queste ipotesi per i contributori e gli utenti di PyPI.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
python
Ambito
documentation
Tipo di issue
Documentazione
Difficoltà
5/5
Tempo stimato
Più di una settimana
Stato di attività
Ferma
Chiarezza
Abbastanza chiara
Idoneità per principianti
35/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.