pypa / pypa/packaging.python.org

Create a new guide for setting up a baseline Python environment

Ouverte
#396 18 commentaires 2 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

component: tutorials help wanted type: enhancement
Langage dominant
Python
Étoiles
1.7k
Forks
1.7k
Merge moyen
3 j 12 h
PR mergées (30 j)
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:

Guide de contribution

Aucun guide de contribution indexé pour ce dépôt

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Commencez par lire le guide utilisateur existant sur le packaging, la discussion sur virtualenv dans le tutoriel d’installation des paquets, ainsi que les guides d’installation liés pour Linux et CPython. Définissez les hypothèses de base prises en charge et les indications de configuration multiplateforme, puis documentez une checklist qui explicite ces hypothèses pour les contributeurs et les utilisateurs de PyPI.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
python
Domaine
documentation
Type d'issue
Documentation
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
À l'abandon
Clarté
Plutôt claire
Accessibilité débutants
35/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.