Skip to content
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

PEP 661: Fix citation references #2698

Merged
merged 4 commits into from
Jul 6, 2022
Merged

PEP 661: Fix citation references #2698

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8d366ec
PEP 661: Remove redundant emacs metadata
hugovk Jul 2, 2022
e9890e8
PEP 661: Convert orhpaned references to bullets
hugovk Jul 2, 2022
fcf8042
PEP 661: Inline the references
hugovk Jul 2, 2022
58e5911
PEP 661: Inline the references anonymously
hugovk Jul 6, 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
51 changes: 21 additions & 30 deletions pep-0661.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,8 @@ of each maintainer.
Motivation
==========

In May 2021, a question was brought up on the python-dev mailing list
[#python-dev-thread]_ about how to better implement a sentinel value for
In May 2021, a question was brought up on the `python-dev mailing list
<python-dev-thread_>`__ about how to better implement a sentinel value for
``traceback.print_exception``. The existing implementation used the
following common idiom::

Expand All @@ -60,7 +60,7 @@ in the discussion:
instance being created and thus comparisons using ``is`` failing

In the ensuing discussion, Victor Stinner supplied a list of currently used
sentinel values in the Python standard library [#list-of-sentinels-in-stdlib]_.
`sentinel values in the Python standard library <list-of-sentinels-in-stdlib_>`__.
This showed that the need for sentinels is fairly common, that there are
various implementation methods used even within the stdlib, and that many of
these suffer from at least one of the aforementioned drawbacks.
Expand All @@ -69,7 +69,7 @@ The discussion did not lead to any clear consensus on whether a standard
implementation method is needed or desirable, whether the drawbacks mentioned
are significant, nor which kind of implementation would be good.

A poll was created on discuss.python.org [#poll]_ to get a clearer sense of
A `poll was created on discuss.python.org <poll_>`__ to get a clearer sense of
the community's opinions. The poll's results were not conclusive, with 40%
voting for "The status-quo is fine / there’s no need for consistency in
this", but most voters voting for one or more standardized solutions.
Expand Down Expand Up @@ -146,8 +146,8 @@ For example::
Reference Implementation
========================

The reference implementation is found in a dedicated GitHub repo
[#reference-github-repo]_. A simplified version follows::
The reference implementation is found in a `dedicated GitHub repo
<reference-github-repo_>`__. A simplified version follows::

def sentinel(name, repr=None):
"""Create a unique sentinel object."""
Expand Down Expand Up @@ -203,7 +203,7 @@ with confidence without needing to consider potential edge-cases.
Additionally, it is useful to be able to provide a meaningful name and repr
for a sentinel value, specific to the context where it is used.

Finally, this was a very unpopular option in the poll [#poll]_, with only 12%
Finally, this was a very unpopular option in the `poll <poll_>`__, with only 12%
of the votes voting for it.


Expand Down Expand Up @@ -233,8 +233,8 @@ Besides the excessive repetition, the repr is overly long:
``<NotGivenType.NotGiven: 'NotGiven'>``. A shorter repr can be defined, at
the expense of a bit more code and yet more repetition.

Finally, this option was the least popular among the nine options in the poll
[#poll]_, being the only option to receive no votes.
Finally, this option was the least popular among the nine options in the `poll
<poll_>`__, being the only option to receive no votes.


A sentinel class decorator
Expand Down Expand Up @@ -293,16 +293,16 @@ Define a recommended "standard" idiom, without supplying an implementation
Most common exiting idioms have significant drawbacks. So far, no idiom
has been found that is clear and concise while avoiding these drawbacks.

Also, in the poll on this subject [#poll]_, the options for recommending an
Also, in the `poll on this subject <poll_>`__, the options for recommending an
idiom were unpopular, with the highest-voted option being voted for by only
25% of the voters.


Additional Notes
================

* This PEP and the initial implementation are drafted in a dedicated GitHub
repo [#reference-github-repo]_.
* This PEP and the initial implementation are drafted in a `dedicated GitHub
repo <reference-github-repo_>`__.

* The support for copying/unpickling works when defined in a module's scope or
a (possibly nested) class's scope. Note that in the latter case, the name
Expand All @@ -316,28 +316,19 @@ Additional Notes
References
==========

.. [#python-dev-thread] Python-Dev mailing list: `The repr of a sentinel <https://mail.python.org/archives/list/[email protected]/thread/ZLVPD2OISI7M4POMTR2FCQTE6TPMPTO3/>`_
.. [#list-of-sentinels-in-stdlib] Python-Dev mailing list: `"The stdlib contains tons of sentinels" <https://mail.python.org/archives/list/[email protected]/message/JBYXQH3NV3YBF7P2HLHB5CD6V3GVTY55/>`_
.. [#poll] discuss.python.org Poll: `Sentinel Values in the Stdlib <https://discuss.python.org/t/sentinel-values-in-the-stdlib/8810/>`_
.. [#reference-github-repo] `Reference implementation at the taleinat/python-stdlib-sentinels GitHub repo <https://github.com/taleinat/python-stdlib-sentinels>`_
.. [5] `bpo-44123: Make function parameter sentinel values true singletons <https://bugs.python.org/issue44123>`_
.. [6] `The "sentinels" package on PyPI <https://pypi.org/project/sentinels/>`_
.. [7] `The "sentinel" package on PyPI <https://pypi.org/project/sentinel/>`_
.. [8] `Discussion thread about type signatures for these sentinels on the typing-sig mailing list <https://mail.python.org/archives/list/[email protected]/thread/NDEJ7UCDPINP634GXWDARVMTGDVSNBKV/#LVCPTY26JQJW7NKGKGAZXHQKWVW7GOGL>`_
.. _python-dev-thread: https://mail.python.org/archives/list/[email protected]/thread/ZLVPD2OISI7M4POMTR2FCQTE6TPMPTO3/
.. _list-of-sentinels-in-stdlib: https://mail.python.org/archives/list/[email protected]/message/JBYXQH3NV3YBF7P2HLHB5CD6V3GVTY55/
.. _poll: https://discuss.python.org/t/sentinel-values-in-the-stdlib/8810/
.. _reference-github-repo: https://github.com/taleinat/python-stdlib-sentinels

* `bpo-44123: Make function parameter sentinel values true singletons <https://bugs.python.org/issue44123>`_
* `The "sentinels" package on PyPI <https://pypi.org/project/sentinels/>`_
* `The "sentinel" package on PyPI <https://pypi.org/project/sentinel/>`_
* `Discussion thread about type signatures for these sentinels on the typing-sig mailing list <https://mail.python.org/archives/list/[email protected]/thread/NDEJ7UCDPINP634GXWDARVMTGDVSNBKV/#LVCPTY26JQJW7NKGKGAZXHQKWVW7GOGL>`_


Copyright
=========

This document is placed in the public domain or under the
CC0-1.0-Universal license, whichever is more permissive.


..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
coding: utf-8
End: