PEP 302 should be superseded/withdrawn

[Yhg1s]

PEP 302 (New Import Hooks) has as its status Final, but it is in fact outdated, and the very first paragraph says:

Warning

The language reference for import and importlib documentation now supersede this PEP.
This document is no longer updated and provided for historical purposes only.

We may need a new status, next to Superseded, to indicate something is out of date, and a standard way to refer to something other than PEPs (which is done with Superseded-By)

[JelleZijlstra]

PEPs are historical documents. I don't think we need a new status just because an area of the language has evolved since the original PEP.

[Yhg1s]

There are unfortunately plenty of PEPs that are not just historical documents, and are seen as standards. I do not believe having a status 'Final' when the PEP is in fact outdated is a good idea.

[encukou]

Are you suggesting to rename Final to something else?
See https://peps.python.org/pep-0001/#pep-maintenance for the current meaning: the PEP accurately describes the implementation at the point where it is marked Final.

[encukou]

FWIW, the term “Python Enhancement Proposal” also doesn't quite fit “living standard” documents.

[hugovk]

Neither does "Request for Comments" for internet standards, but the IETF has ditched that original meaning:

RFCs started as informal technical notes and the name originally stood for “Request For Comments” but now they are simply known as RFCs.

[Rosuav]

Maybe we need a new status for "Living Standard"?

[encukou]

We do have the Active status.

[warsaw]

I think the PEP 302 warning banner is fine, and that we don't need much else. I'm not sure what standard thing you could add since each "hey this is out of date and historical" banner will need to have different links, say to the appropriate language reference page or whatever.

That said, maybe a status of "Historical" would be appropriate to add. I'm not in favor of bulk updating PEPs though, so I'd say only for those that are egregiously out of date.

"Active" is fine for living documents.

[CAM-Gerlach]

There are unfortunately plenty of PEPs that are not just historical documents, and are seen as standards.

@Yhg1s Process and Informational PEPs are Active when they are considered living standards/guidelines and are kept up to date accordingly; they are marked Final to designate them as historical only, and are categorized accordingly on PEP 0. Once Standards Track PEPs are Final, they are considered historical and their canonical documentation should be hosted elsewhere, as PEP 1 states:

In general, PEPs are no longer substantially modified after they have reached the Accepted, Final, Rejected or Superseded state. Once resolution is reached, a PEP is considered a historical document rather than a living specification. Formal documentation of the expected behavior should be maintained elsewhere, such as the Language Reference for core features, the Library Reference for standard library modules or the PyPA Specifications for packaging.

There are some exceptions, but the great majority are on either the Packaging or Typing Topic, for which the living standard role of both are in the process of being migrated to more appropriate locations so the PEPs can just focus on being change proposals—many of the packaging standards have already been migrated, and @pradyunsg and I are actively working on the rest, while as I understand the Typing community intends to do the same and is in the process of hashing out the details. There are a handful of special cases, like the DB-API and WSGI, but these can be handled on a case by case basis and are gradually fading in importance over time (e.g. WSGI is partially superseded by ASGI, hosted elsewhere, as I understand).

I think the PEP 302 warning banner is fine, and that we don't need much else. I'm not sure what standard thing you could add since each "hey this is out of date and historical" banner will need to have different links, say to the appropriate language reference page or whatever.

@warsaw In fact, this is exactly what we will have with #2702 ; a standardized (but optional) warning banner for Final PEPs where we can just specify the desired link (and any custom text) which gets inserted into an informative message. It can be easily subclassed to handle various common cases (e.g. Packaging PEPs), and there's been talk of making the banner sticky if more visibility is needed.

[warsaw]

this is exactly what we will have with #2702 ; a standardized (but optional) warning banner for Final PEPs where we can just specify the desired link (and any custom text) which gets inserted into an informative message.

That's quite nice! Thanks for all the amazing work on improving the PEP documentation!

[CAM-Gerlach]

Somewhat related: I just finished pypa/packaging.python.org#1111 , which finally does the whole-hog long awaited migration of PEP 517/518/660 to the PyPA specs page on packaging.python.org

[brettcannon]

Since PEP 302 isn't going to be withdrawn, I am going to close this issue.

@Yhg1s can chat with me at the core dev sprints about what documentation he wishes he had in importlib that triggered all of this. 😉