classification
Title: Add a `recommended-packages.txt` file
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: eric.araujo, nanjekyejoannah, ncoghlan, p-ganssle, xtreak
Priority: normal Keywords:

Created on 2017-10-30 05:17 by ncoghlan, last changed 2020-07-05 00:08 by nanjekyejoannah.

Messages (7)
msg305210 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-10-30 05:17
As per the python-ideas thread starting at https://mail.python.org/pipermail/python-ideas/2017-October/047508.html, this is proposal to add a `pip -r` compatible `recommended-packages.txt` file to the `venv` documentation that summarises replacement module recommendations in other parts of the standard library documentation.

Suggested entries are:

requests    # Recommendation in urllib.request docs
regex       # Recommendation in re docs
cffi        # More typesafe alternative to ctypes
six         # Python 2/3 compatibility library
setuptools  # Alternative to distutils that supports modern packaging standards

I'm also tempted to suggest pytz as the preferred source of up-to-date named timezones, but I'm not sure how often that's really needed in situations where you can't just depend on it explicitly instead.
msg305212 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-10-30 05:24
https://bugs.python.org/issue31899 is a follow-up issue to discuss whether or not it would make sense to expand these recommendations to cover explicit compatibility testing against these libraries for CPython updates
msg305285 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-10-31 10:58
As part of this, a new subsection would be added to https://docs.python.org/devguide/stdlibchanges.html to document the process for adding new packages to the recommended packages list: propose them for standard library inclusion, and while "No" is still the most likely outcome, being added to the recommended packages list would be a potential middle ground for "Approved in principle, but the actual logistics of doing so probably don't work".
msg305288 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-10-31 11:31
Thinking about it further, this list is actually going to be version independent, suggest it may actually belong somewhere outside the main documentation.

The Developer's Guide may be a reasonable stopgap measure until there's a better option available (e.g. if I ever get around to turning https://github.com/python/redistributor-guide/ into something more than a nearly empty repo)
msg305534 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-11-04 03:24
In https://mail.python.org/pipermail/python-ideas/2017-October/047599.html, Guido suggested managing this as an occasionally updated Informational PEP (somewhat akin to PEP 394), and I think that will actually work fairly well:

* it clearly gives the information PEP level status (which merely being in the developer guide wouldn't)
* it means the guidance can be mostly version independent (which would be a source of irritation if the list was in the reference documentation)
* it means we can use the same process for amendments as we do for other informational PEPs (a combination of python-dev discussions, bugs.python.org issues, and specific PR reviews)

My current thoughts on structuring that:

Title: Recommended Independently Updated Python Packages

Tone/Audience: I'll aim the PEP primarily at answering the "Why isn't <X> in the standard library?" question, as that helps us keep the list focused on python-dev specific concerns and avoid turning it into a general categorised list of Python library recommendations like https://github.com/vinta/awesome-python

The key criterion for something being mentioned will be when the standard library *already* contains comparable functionality, but there's a language version independent third party alternative that even core developers will often use instead. That list is currently:

urllib.requests -> requests (pace of change in web standards)
re -> regex (technical challenges with backend migration)
datetime.timezone -> pytz.timezone (updates driven by IANA timezone database)
ctypes -> cffi (build tools should be version independent)
distutils -> setuptools (build tools should be version independent)

I'll likely also include a list of libraries where version independence is a key feature, so they've never even been proposed for stdlib inclusion, despite their broad popularity:

- the six compatibility module
- various backport libraries (e.g. importlib2, contextlib2, unittest2)
- third party libraries like lxml

I'm not sure if or how I'll cover the scientific Python stack (especially NumPy.ndarray being the reference implementation for multi-dimensional arrays), but Nathaniel Smith has some interesting thoughts on that in https://mail.python.org/pipermail/python-ideas/2017-November/047636.html
msg321107 - (view) Author: Paul Ganssle (p-ganssle) * (Python committer) Date: 2018-07-05 15:40
> datetime.timezone -> pytz.timezone (updates driven by IANA timezone database)

I will note that `pytz.timezone` and `datetime.timezone` are not really comparable (they do two very different things), and as of Python 3.6, `dateutil.tz` is the recommended source for IANA time zones, not `pytz`, per https://docs.python.org/3/library/datetime.html
msg372501 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2020-06-28 07:17
Removing the issue assignment, as I'm not actively working on this (although I still think it's a reasonable idea).
History
Date User Action Args
2020-07-05 00:08:25nanjekyejoannahsetnosy: + nanjekyejoannah
2020-06-28 07:17:16ncoghlansetassignee: ncoghlan ->
messages: + msg372501
2018-09-20 13:24:43xtreaksetnosy: + xtreak
2018-07-05 15:40:41p-gansslesetnosy: + p-ganssle
messages: + msg321107
2017-11-04 03:24:12ncoghlansetmessages: + msg305534
2017-11-03 18:26:21eric.araujosetnosy: + eric.araujo
2017-10-31 11:31:37ncoghlansetmessages: + msg305288
title: Add `recommended-packages.txt` to `venv` documentation -> Add a `recommended-packages.txt` file
2017-10-31 10:58:05ncoghlansetmessages: + msg305285
2017-10-30 05:24:26ncoghlansetmessages: + msg305212
2017-10-30 05:19:09ncoghlansettype: enhancement
stage: needs patch
2017-10-30 05:17:27ncoghlancreate