Skip to content

PEP 1: Make text/x-rst officially the default and update accordingly #2355

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 24, 2022
Merged

PEP 1: Make text/x-rst officially the default and update accordingly #2355

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
64de899
Switch default Content-Type to text/x-rst, since all PEPs are now RST
CAM-Gerlach Feb 22, 2022
51cf8cb
PEP 1: Clarify that reST is the default & no plaintext PEPs remain
CAM-Gerlach Feb 22, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 6 additions & 8 deletions pep-0001.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -205,8 +205,8 @@ The standard PEP workflow is:
* The title accurately describes the content.
* The PEP's language (spelling, grammar, sentence structure, etc.)
and code style (examples should match :pep:`7` & :pep:`8`) should be
correct and conformant. The PEP text will be automatically checked for
correct reStructuredText formatting when the pull request is submitted.
correct and conformant. The PEP text will be automatically checked for
correct reStructuredText formatting when the pull request is submitted.
PEPs with invalid reST markup will not be approved.

Editors are generally quite lenient about this initial review,
Expand Down Expand Up @@ -547,7 +547,7 @@ optional and are described below. All other headers are required.
Status: <Draft | Active | Accepted | Provisional | Deferred | Rejected |
Withdrawn | Final | Superseded>
Type: <Standards Track | Informational | Process>
* Content-Type: <text/x-rst | text/plain>
* Content-Type: text/x-rst
* Requires: <pep numbers>
Created: <date created on, in dd-mmm-yyyy format>
* Python-Version: <version number>
Expand Down Expand Up @@ -603,11 +603,9 @@ The Type header specifies the type of PEP: Standards Track,
Informational, or Process.

The format of a PEP is specified with a Content-Type header.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Explicitly only support text/x-rst

Suggested change
The format of a PEP is specified with a Content-Type header.
The format of a PEP is specified with a Content-Type header.
The only valid value is ``text/x-rst``.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I ended up using the "must" verbiage suggested by @warsaw

Valid values are ``text/plain`` for plaintext PEPs (see :pep:`9`)
and ``text/x-rst`` for reStructuredText PEPs (see :pep:`12`).
All new and active PEPs must use reStructuredText, but for backwards
compatibility, plain text is currently still the default if no
Content-Type header is present.
All PEPs must use reStructuredText (see :pep:`12`),
and have a value of ``text/x-rst``, the default.
Previously, plaintext PEPs used ``text/plain`` (see :pep:`9`).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should clearly explain whether text/plain will be accepted or not going forward.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd remove this line, PEP-0009 itself has a notice stating that it is withdrawn.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If people think this should simply be removed, I can remove it. Otherwise, I could revise the above to say "All PEPs must use reStructuredText"...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I think the must language is worth adding.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added above, thanks


The Created header records the date that the PEP was assigned a
number, while Post-History is used to record the dates of when new
Expand Down
1 change: 1 addition & 0 deletions pep-0012/pep-NNNN.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ PEP-Delegate: <PEP delegate's real name>
Discussions-To: <email address or URL>
Status: <REQUIRED: Draft | Active | Accepted | Provisional | Deferred | Rejected | Withdrawn | Final | Superseded>
Type: <REQUIRED: Standards Track | Informational | Process>
Content-Type: text/x-rst
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Content Type is required, but as there's only one valid value it feels odd to use the <REQUIRED: spam> verbiage. Maybe it is better as is?

Suggested change
Content-Type: text/x-rst
Content-Type: <REQUIRED: text/x-rst>

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is Content-Type still required?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had the same thought. One possible reason is forward compatibility: maybe in the future we'll allow PEPs in markdown or something. Then again, even in that case we can just reintroduce the header later.

And another reason is just to avoid making a change without a strong reason. There is little cost to having PEP authors copy this field from the template.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm inclined to keep it, for clarity. Lots of things have their MIME types designated in headers. And as Jelle says, maybe in the future there will be others, so it'd mean we don't need to say "Optional - if omitted, defaults to text/x-rst".

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's no techincal reason the header couldn't simply be removed from the template (and even all PEPs), since they all use text/x-rst, the default, and likely will for the immediate future, and the only place this was actually used is by the old docutils-based rendering script to determine the rendering mode, if not the default (it isn't anywhere in the output, and it isn't needed or used at all by the PEP 676 based system).

If we did add support for a new format, it presumably would be handled via file extension, like any common format these days (e.g. MyST with .md) and a Content-Type would not really serve no technical purpose, since it is only (and could even be out of sync with the actual file type, unless we run a linter or custom build-time check to validate it). That would allow us to not have to mention it at all (optional or otherwise), lint it, or copy it as boilerplate.

That being said, while it is redundant, there isn't too much cost to keeping it around (at least on existing PEPs), so I don't feel too strongly about it.

Requires: <pep numbers>
Created: <date created on, in dd-mmm-yyyy format>
Python-Version: <version number>
Expand Down
8 changes: 4 additions & 4 deletions pep2html.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -260,7 +260,7 @@ def fixfile(inpath, input_lines, outfile):
v = date
elif k.lower() in ('content-type',):
url = PEPURL % 9
pep_type = v or 'text/plain'
pep_type = v or 'text/x-rst'
v = '<a href="%s">%s</a> ' % (url, escape(pep_type))
elif k.lower() == 'version':
if v.startswith('$' 'Revision: ') and v.endswith(' $'):
Expand Down Expand Up @@ -569,7 +569,7 @@ def fix_rst_pep(inpath, input_lines, outfile):

def get_pep_type(input_lines):
"""
Return the Content-Type of the input. "text/plain" is the default.
Return the Content-Type of the input. "text/x-rst" is the default.
Return ``None`` if the input is not a PEP.
"""
pep_type = None
Expand All @@ -579,11 +579,11 @@ def get_pep_type(input_lines):
# End of the RFC 2822 header (first blank line).
break
elif line.startswith('content-type: '):
pep_type = line.split()[1] or 'text/plain'
pep_type = line.split()[1] or 'text/x-rst'
break
elif line.startswith('pep: '):
# Default PEP type, used if no explicit content-type specified:
pep_type = 'text/plain'
pep_type = 'text/x-rst'
return pep_type


Expand Down