pypa / pypa/packaging.python.org

Create a new guide for setting up a baseline Python environment

Abierto
#396 18 comentarios 2 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

component: tutorials help wanted type: enhancement
Lenguaje dominante
Python
Estrellas
1.7k
Forks
1.7k
Merge medio
3 d 12 h
PR fusionados (30 d)
4

Descripción

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:

Guía de contribución

No hay ninguna guía de contribución indexada para este repositorio

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Línea de trabajo

Comienza leyendo la guía de usuario existente sobre empaquetado, la discusión sobre virtualenv en el tutorial de instalación de paquetes y las guías de instalación enlazadas de Linux y CPython. Define las suposiciones de referencia compatibles y las indicaciones de configuración multiplataforma; después, documenta una lista de comprobación que haga explícitas esas suposiciones para los contribuidores y los usuarios de PyPI.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
python
Área
documentation
Tipo de issue
Documentación
Dificultad
5/5
Tiempo estimado
Más de una semana
Estado de actividad
Estancado
Claridad
Bastante claro
Aptitud para principiantes
35/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.