pypa / packaging.python.org

Python Packaging User Guide
http://packaging.python.org
1.42k stars 903 forks source link

Explain clearly that python / pip / other commands are not Python code #745

Open merwok opened 4 years ago

merwok commented 4 years ago

https://github.com/pypa/packaging-problems/issues/369 is the latest instance of a person trying to type python setup.py sdist or pip install something in the Python shell rather than in a system console, which is not obvious to everyone.

None of https://packaging.python.org/tutorials/packaging-projects and https://packaging.python.org/guides/distributing-packages-using-setuptools/#wheels say a word about that.

pfmoore commented 4 years ago

+1 on helping people to better understand this distinction - it's common (maybe more so on Windows?) to see people who don't understand the idea of a shell trying to work with the packaging guides, and this is foundational knowledge that we assume in a lot of places.

I'd prefer it if we provided a brief summary plus pointers to resources that people could use to understand the concepts of shell, REPL, and interactive command line program better. Going into too much depth in the packaging documentation feels like a digression (no matter how necessary) to me.

merwok commented 4 years ago

I think the ideal thing then would be to link to a section of Python Setup and Usage in the official docs.