Dangling hyphens in many PEPs

[JelleZijlstra]

All of these probably lead to badly rendered text:

peps % git grep -- '[a-z]-$'
pep-0008.txt:You should use two spaces after a sentence-ending period in multi-
pep-0201.txt:already be accomplished in Python through the use of the map() built-
pep-0205.txt:reference containers that must be cleared for each weakly-
pep-0209.txt:This PEP proposes a redesign and re-implementation of the multi-
pep-0209.txt:        class or a special array type, depending on your point-of-
pep-0209.txt:    arguments are lists of CFuncObjects for those arrays needing pre-
pep-0235.txt:#B is the same rule as is used on Unix, so this will improve cross-
pep-0249.txt:    Return ``True`` if the connection is operating in autocommit (non-
pep-0333.txt:                       requested by the application, or it may pre-
pep-0333.txt:Some operating environments provide special high-performance file-
pep-0344.txt:Several attribute names for chained exceptions have been suggested on Python-
pep-0367.txt:name may simplify implementation, however some are against the actual keyword-
pep-0367.txt:names, in cases where that is needed. One use case this fails is where a base-
pep-0367.txt:both of which needing to properly make super calls to the one in the base-
pep-0374.txt:support setting this information on a per-user basis, and on a per-
pep-0439.txt:issue tracker [2]_. Most notably, the addition of --bootstrap and --bootstrap-
pep-0451.txt:A module's spec will not be kept in sync with the corresponding import-
pep-0451.txt:added in Python 3.3.  However, the extra complexity and a less-than-
pep-0465.txt:package on PyPI).  Starred lines indicate packages which export array-
pep-0471.txt:on POSIX systems**. So we're not talking about micro-
pep-0479.txt:limitation, but notes that "use cases for these [are] rare to non-
pep-0492.txt:The function applies ``CO_ITERABLE_COROUTINE`` flag to generator-
pep-0492.txt:   and having ``__call__`` and no ``__cocall__`` for coroutine-
pep-0492.txt:   associated protocol with ``__aiter__``, ``__aexit__`` and new built-
pep-0512.txt:repository [#cpython-repo]_. Because of its importance and high-
pep-0520.txt:namespace be ordered (e.g. ``OrderedDict``) by default.  The long-
pep-0520.txt:properly set.  That could certainly be handled through specific class-
pep-0554.rst:   own subinterpreter may prove quite interesting to reconcile multi-
pep-0554.rst:one of the key objectives of this PEP is to provide a more human-
pep-0560.rst:* Creation of user defined generic classes is up to 4x faster (on a micro-
pep-0615.rst:    http://cldr.unicode.org/#TOC-How-to-Use-
pep-0633.rst:- ``version`` (string): a :pep:`440` version specifier, which is a comma-
pep-3001.txt:with information on possible substitutes or alternatives.  This infor-
pep-3101.txt:    'x' - Hex format. Outputs the number in base 16, using lower-
pep-3101.txt:    'X' - Hex format. Outputs the number in base 16, using upper-
pep-3115.txt:assignment algorithm. (Note also that *metaclass* is a keyword-
pep-3124.txt:which the overload is adding support.  Thus, overloads are highly-
pep-3135.txt:names, in cases where that is needed. One use case this fails is where a base-
pep-3135.txt:both of which needing to properly make super calls to the one in the base-
pep-3145.txt:       http://stackoverflow.com/questions/636561/how-can-i-run-an-external-
pep-3333.txt:                       requested by the application, or it may pre-
pep-3333.txt:Some operating environments provide special high-performance file-

Opened sphinx-contrib/sphinx-lint#54 to have sphinx-lint catch this.

[shailshouryya]

Reading through this issue, the linked issue in sphinx-lint, and sphinx-contrib/sphinx-lint#56, I think the pull request (56) partially fixed this issue.

I manually verified

• https://peps.python.org/pep-0008/ is properly formatted
• https://peps.python.org/pep-0201/ is partially properly formatted
  • built-in does not have the space after (5 occurrences)
  • built- in has the space after (1 occurrence)
    • this one is a bit strange, since there are 5 occurrences of built-in being properly formatted but 1 occurrence decides to be unique 😂
• https://peps.python.org/pep-0205/ is partially properly formatted
  • weakly-referenced does not have space after (3 occurrences)
  • weakly- referencable has the space after (1 occurrence)
  • no -real- pointers has 1 space before and after real
  • and -not- the has 1 space before and after not
• https://peps.python.org/pep-0209/ is properly formatted
  • there is a space in pre- or post-processing - but I think this is expected
• https://peps.python.org/pep-0235/ is not properly formatted
  • cross- platform has the space after (1 occurrence)
• https://peps.python.org/pep-0520/ is not properly formatted
  • long- lived has the space after (1 occurrence)
  • class- creation has the space after (1 occurrence)

I didn't go through the rest of the PEPs listed in your original post here, but I expect there is probably some inconsistencies with those as well.

I'm still investigating and I'll try going through the raw text (the "source code" for these examples) and see what I can find there when I get the chance, but I'm adding what I've found so far in case this might help someone else identify the problem sooner than I can.

[shailshouryya]

Ah, I think the problem of the remaining extra space being added sometimes is because the pull request does not fix the formatting for the hyphen at the end of the line based on a quick look at https://github.com/python/peps/blob/main/pep-0205.txt

Looking at https://github.com/sphinx-contrib/sphinx-lint/pull/56/files#diff-6001213f99f3fd6caff3790df503e4c40a7ff69166cbdc3d6551ae9e5bdb8d45R452, I think this is the specific usecase the PR was trying to address - so it sometimes works? (Will continue to investigate.)

[hugovk]

We're still using sphinx-lint 0.6.7 in https://github.com/python/peps/blob/main/.pre-commit-config.yaml, would you like to make a PR to update it so we're using sphinx-contrib/sphinx-lint#56?

python -m pip install pre-commit
pre-commit autoupdate
pre-commit run --all-files

[hugovk]

Thanks for updating to 0.6.8 in #3291. Sphinx-lint doesn't report any errors.

Looking again:

❯ git grep -- '[a-z]-$'
pep-0201.txt:already be accomplished in Python through the use of the map() built-
pep-0205.txt:reference containers that must be cleared for each weakly-
pep-0209.txt:This PEP proposes a redesign and re-implementation of the multi-
pep-0209.txt:        class or a special array type, depending on your point-of-
pep-0209.txt:    arguments are lists of CFuncObjects for those arrays needing pre-
pep-0235.txt:#B is the same rule as is used on Unix, so this will improve cross-
pep-0249.txt:    Return ``True`` if the connection is operating in autocommit (non-
pep-0333.txt:                       requested by the application, or it may pre-
pep-0333.txt:Some operating environments provide special high-performance file-
pep-0344.txt:Several attribute names for chained exceptions have been suggested on Python-
pep-0367.txt:name may simplify implementation, however some are against the actual keyword-
pep-0367.txt:names, in cases where that is needed. One use case this fails is where a base-
pep-0367.txt:both of which needing to properly make super calls to the one in the base-
pep-0374.txt:support setting this information on a per-user basis, and on a per-
pep-0439.txt:issue tracker [2]_. Most notably, the addition of --bootstrap and --bootstrap-
pep-0451.txt:A module's spec will not be kept in sync with the corresponding import-
pep-0451.txt:added in Python 3.3.  However, the extra complexity and a less-than-
pep-0465.txt:package on PyPI).  Starred lines indicate packages which export array-
pep-0471.txt:on POSIX systems**. So we're not talking about micro-
pep-0479.txt:limitation, but notes that "use cases for these [are] rare to non-
pep-0492.txt:The function applies ``CO_ITERABLE_COROUTINE`` flag to generator-
pep-0492.txt:   and having ``__call__`` and no ``__cocall__`` for coroutine-
pep-0492.txt:   associated protocol with ``__aiter__``, ``__aexit__`` and new built-
pep-0512.txt:repository [#cpython-repo]_. Because of its importance and high-
pep-0520.txt:namespace be ordered (e.g. ``OrderedDict``) by default.  The long-
pep-0520.txt:properly set.  That could certainly be handled through specific class-
pep-0554.rst:   own subinterpreter may prove quite interesting to reconcile multi-
pep-0615.rst:    http://cldr.unicode.org/#TOC-How-to-Use-
pep-3001.txt:with information on possible substitutes or alternatives.  This infor-
pep-3101.txt:    'x' - Hex format. Outputs the number in base 16, using lower-
pep-3101.txt:    'X' - Hex format. Outputs the number in base 16, using upper-
pep-3115.txt:assignment algorithm. (Note also that *metaclass* is a keyword-
pep-3124.txt:which the overload is adding support.  Thus, overloads are highly-
pep-3135.txt:names, in cases where that is needed. One use case this fails is where a base-
pep-3135.txt:both of which needing to properly make super calls to the one in the base-
pep-3333.txt:                       requested by the application, or it may pre-
pep-3333.txt:Some operating environments provide special high-performance file-

Why doesn't sphinx-lint pick these up? Because they all have .txt not .rst extensions. The older PEPs still have .txt even though they're reStructuredText (we have a plan to rename them someday: #10) and sphinx-lint doesn't check .txt files.

We can temporarily make sphinx-lint check .txt as well:

diff --git a/sphinxlint/checkers.py b/sphinxlint/checkers.py
index 5354606..3039ebe 100644
--- a/sphinxlint/checkers.py
+++ b/sphinxlint/checkers.py
@@ -461,7 +461,7 @@ def check_bad_dedent(file, lines, options=None):
     yield from errors
 
 
-@checker(".rst", rst_only=True)
+@checker(".rst", ".txt", rst_only=True)
 def check_dangling_hyphen(file, lines, options):
     """Check for lines ending in a hyphen."""
     for lno, line in enumerate(lines):

Which gives these results to check and potentially fix:

❯ sphinx-lint pep-*.txt | sort
pep-0201.txt:49: Line ends with dangling hyphen (dangling-hyphen)
pep-0205.txt:188: Line ends with dangling hyphen (dangling-hyphen)
pep-0209.txt:131: Line ends with dangling hyphen (dangling-hyphen)
pep-0209.txt:15: Line ends with dangling hyphen (dangling-hyphen)
pep-0209.txt:268: Line ends with dangling hyphen (dangling-hyphen)
pep-0235.txt:128: Line ends with dangling hyphen (dangling-hyphen)
pep-0249.txt:941: Line ends with dangling hyphen (dangling-hyphen)
pep-0333.txt:1344: Line ends with dangling hyphen (dangling-hyphen)
pep-0333.txt:599: Line ends with dangling hyphen (dangling-hyphen)
pep-0344.txt:88: Line ends with dangling hyphen (dangling-hyphen)
pep-0367.txt:125: Line ends with dangling hyphen (dangling-hyphen)
pep-0367.txt:516: Line ends with dangling hyphen (dangling-hyphen)
pep-0367.txt:518: Line ends with dangling hyphen (dangling-hyphen)
pep-0374.txt:277: Line ends with dangling hyphen (dangling-hyphen)
pep-0439.txt:192: Line ends with dangling hyphen (dangling-hyphen)
pep-0451.txt:681: Line ends with dangling hyphen (dangling-hyphen)
pep-0451.txt:719: Line ends with dangling hyphen (dangling-hyphen)
pep-0465.txt:391: Line ends with dangling hyphen (dangling-hyphen)
pep-0471.txt:49: Line ends with dangling hyphen (dangling-hyphen)
pep-0479.txt:60: Line ends with dangling hyphen (dangling-hyphen)
pep-0492.txt:1319: Line ends with dangling hyphen (dangling-hyphen)
pep-0492.txt:176: Line ends with dangling hyphen (dangling-hyphen)
pep-0492.txt:999: Line ends with dangling hyphen (dangling-hyphen)
pep-0512.txt:265: Line ends with dangling hyphen (dangling-hyphen)
pep-0520.txt:188: Line ends with dangling hyphen (dangling-hyphen)
pep-0520.txt:40: Line ends with dangling hyphen (dangling-hyphen)
pep-3001.txt:32: Line ends with dangling hyphen (dangling-hyphen)
pep-3115.txt:140: Line ends with dangling hyphen (dangling-hyphen)
pep-3124.txt:962: Line ends with dangling hyphen (dangling-hyphen)
pep-3135.txt:168: Line ends with dangling hyphen (dangling-hyphen)
pep-3135.txt:170: Line ends with dangling hyphen (dangling-hyphen)
pep-3333.txt:1460: Line ends with dangling hyphen (dangling-hyphen)
pep-3333.txt:679: Line ends with dangling hyphen (dangling-hyphen)

[merwok]

Just checked one PR at random: #3362

The fix there would have been to delete the hyphen, it is not needed between an adverb and an adjective.

[AA-Turner]

I tried to take the approach of maintaining the author's original wording, though I agree some cases were questionable over simply deleting the hypen alltogether.

A