diff --git a/pep-0661.rst b/pep-0661.rst index 24237c3d7c4..3cc1d24760b 100644 --- a/pep-0661.rst +++ b/pep-0661.rst @@ -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 +`__ about how to better implement a sentinel value for ``traceback.print_exception``. The existing implementation used the following common idiom:: @@ -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 `__. 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. @@ -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 `__ 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. @@ -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 +`__. A simplified version follows:: def sentinel(name, repr=None): """Create a unique sentinel object.""" @@ -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 `__, with only 12% of the votes voting for it. @@ -233,8 +233,8 @@ Besides the excessive repetition, the repr is overly long: ````. 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 +`__, being the only option to receive no votes. A sentinel class decorator @@ -293,7 +293,7 @@ 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 `__, the options for recommending an idiom were unpopular, with the highest-voted option being voted for by only 25% of the voters. @@ -301,8 +301,8 @@ idiom were unpopular, with the highest-voted option being voted for by only 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 `__. * 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 @@ -316,14 +316,15 @@ Additional Notes References ========== -.. [#python-dev-thread] Python-Dev mailing list: `The repr of a sentinel `_ -.. [#list-of-sentinels-in-stdlib] Python-Dev mailing list: `"The stdlib contains tons of sentinels" `_ -.. [#poll] discuss.python.org Poll: `Sentinel Values in the Stdlib `_ -.. [#reference-github-repo] `Reference implementation at the taleinat/python-stdlib-sentinels GitHub repo `_ -.. [5] `bpo-44123: Make function parameter sentinel values true singletons `_ -.. [6] `The "sentinels" package on PyPI `_ -.. [7] `The "sentinel" package on PyPI `_ -.. [8] `Discussion thread about type signatures for these sentinels on the typing-sig mailing list `_ +.. _python-dev-thread: https://mail.python.org/archives/list/python-dev@python.org/thread/ZLVPD2OISI7M4POMTR2FCQTE6TPMPTO3/ +.. _list-of-sentinels-in-stdlib: https://mail.python.org/archives/list/python-dev@python.org/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 `_ +* `The "sentinels" package on PyPI `_ +* `The "sentinel" package on PyPI `_ +* `Discussion thread about type signatures for these sentinels on the typing-sig mailing list `_ Copyright @@ -331,13 +332,3 @@ 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: