From 8ffa0a99e7eee576a8803b29fc49375ff2f156c8 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Sun, 25 Oct 2026 23:40:35 -0400 Subject: [PATCH] docs: state current behaviour where text pins held change-relative wording (#2228) Problem: four tests pinned sentences that narrate a change ("#808 dropped TransportProtocol's IntFlag base", "value were both the bytes object", the compat.cached_property "backport", "passed before the change too"), so the prose could not be made timeless without the pin. Fix: reword each to state current behaviour -- TransportProtocol is an IntEnum, not an IntFlag; no Method member has a bytes name or value; compat.cached_property re-exports functools.cached_property; the unknown-role guard names only :ref: -- mirroring vendor templates into the const modules by hand, and move each pin onto the new wording. Test: the updated pins fail on origin/main and pass here; reverting either role to a literal fails ConvertedReferenceTests. --- .../contributing/conventions/sentinel-convention.rst | 7 ++++--- pcapkit/const/http/method.py | 5 ++--- pcapkit/const/reg/apptype/apptype.py | 8 ++++---- pcapkit/vendor/http/method.py | 5 ++--- pcapkit/vendor/reg/apptype/apptype.py | 8 ++++---- tests/const/test_const_method_value_lookup_908_unit.py | 4 ++-- tests/project/test_changelog_md.py | 6 +++--- tests/project/test_docs_internal_refs_1940_unit.py | 2 +- tests/project/test_docs_internal_refs_1947_unit.py | 8 ++++---- tests/project/test_issue_refs_in_comments.py | 2 +- 10 files changed, 27 insertions(+), 28 deletions(-) diff --git a/docs/source/contributing/conventions/sentinel-convention.rst b/docs/source/contributing/conventions/sentinel-convention.rst index f373c86a30..c0298dc275 100644 --- a/docs/source/contributing/conventions/sentinel-convention.rst +++ b/docs/source/contributing/conventions/sentinel-convention.rst @@ -105,9 +105,10 @@ appears in a signature, in :func:`help` output and in a traceback. Compare what as written: the value of a vendored copy is that it can still be diffed against upstream, and a house-style rewrite destroys that in exchange for a sentinel nobody outside the port ever sees. The rule above is for sentinels this package writes -itself. The case that settled it, ``_NOT_FOUND = object()`` in the -:class:`~pcapkit.utilities.compat.cached_property` backport for interpreters below -3.8, went with that backport when 1.5.0 raised the floor to 3.8 (:issue:`2051`). +itself. The ruling was made for ``_NOT_FOUND = object()`` in the backport of +:func:`functools.cached_property` that served interpreters below 3.8. With the floor +at 3.8, :class:`~pcapkit.utilities.compat.cached_property` is a re-export of +:func:`functools.cached_property` itself (:issue:`2051`). Per-Sentinel Dunder Methods ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/pcapkit/const/http/method.py b/pcapkit/const/http/method.py index 3ea2bd3f74..b7a18c9a31 100644 --- a/pcapkit/const/http/method.py +++ b/pcapkit/const/http/method.py @@ -267,9 +267,8 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> 'Method': reach ``_missing_``, and is **not** caught by the miss fallback described under *Returns* -- only a failed lookup is. Raising is the intended behaviour for - ``get(b'GET')`` as well: a member whose name and - value were both the :class:`bytes` object is not a thing - this registry should hand back. + ``get(b'GET')`` as well, since no member of this registry + has a :class:`bytes` name or value. """ try: diff --git a/pcapkit/const/reg/apptype/apptype.py b/pcapkit/const/reg/apptype/apptype.py index 5069ee268c..2b7efdf48d 100644 --- a/pcapkit/const/reg/apptype/apptype.py +++ b/pcapkit/const/reg/apptype/apptype.py @@ -2513,10 +2513,10 @@ def _dispatch(cls, key: 'int', proto: 'TransportProtocol | str | int') -> 'Type[ key: Port number the caller is looking up, validated here so that every entry point rejects a non-port identically. proto: Transport protocol, as a member, its name, or a bare - :class:`int`. That last shape is not merely defensive: GitHub - issue :issue:`808` dropped - :class:`~pcapkit.const.reg.apptype.apptype.TransportProtocol`'s - ``IntFlag`` base, so + :class:`int`. That last shape is not merely defensive: + :class:`~pcapkit.const.reg.apptype.apptype.TransportProtocol` + is an ``IntEnum``, not an ``IntFlag`` (GitHub issue + :issue:`808`), so ``TransportProtocol.a | TransportProtocol.b`` -- built by hand, the same as any caller passing a literal port-transport bitmask -- falls through to ``int.__or__`` and returns a bare diff --git a/pcapkit/vendor/http/method.py b/pcapkit/vendor/http/method.py index 5262213224..151d8ec5e6 100644 --- a/pcapkit/vendor/http/method.py +++ b/pcapkit/vendor/http/method.py @@ -172,9 +172,8 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> '{NAME}': reach ``_missing_``, and is **not** caught by the miss fallback described under *Returns* -- only a failed lookup is. Raising is the intended behaviour for - ``get(b'GET')`` as well: a member whose name and - value were both the :class:`bytes` object is not a thing - this registry should hand back. + ``get(b'GET')`` as well, since no member of this registry + has a :class:`bytes` name or value. """ try: diff --git a/pcapkit/vendor/reg/apptype/apptype.py b/pcapkit/vendor/reg/apptype/apptype.py index 193be0cdf8..99b69345d1 100644 --- a/pcapkit/vendor/reg/apptype/apptype.py +++ b/pcapkit/vendor/reg/apptype/apptype.py @@ -467,10 +467,10 @@ def _dispatch(cls, key: 'int', proto: 'TransportProtocol | str | int') -> 'Type[ key: Port number the caller is looking up, validated here so that every entry point rejects a non-port identically. proto: Transport protocol, as a member, its name, or a bare - :class:`int`. That last shape is not merely defensive: GitHub - issue :issue:`808` dropped - :class:`~pcapkit.const.reg.apptype.apptype.TransportProtocol`'s - ``IntFlag`` base, so + :class:`int`. That last shape is not merely defensive: + :class:`~pcapkit.const.reg.apptype.apptype.TransportProtocol` + is an ``IntEnum``, not an ``IntFlag`` (GitHub issue + :issue:`808`), so ``TransportProtocol.a | TransportProtocol.b`` -- built by hand, the same as any caller passing a literal port-transport bitmask -- falls through to ``int.__or__`` and returns a bare diff --git a/tests/const/test_const_method_value_lookup_908_unit.py b/tests/const/test_const_method_value_lookup_908_unit.py index dc04092b84..46ae210095 100644 --- a/tests/const/test_const_method_value_lookup_908_unit.py +++ b/tests/const/test_const_method_value_lookup_908_unit.py @@ -302,8 +302,8 @@ def test_the_docstring_documents_the_value_error(self) -> None: # NOTE: a distinctive sentence rather than the bare word # ``ValueError``, which occurs incidentally elsewhere in 4kB of # docstring and would make this assertion near-vacuous. - self.assertIn('value were both the :class:`bytes` object', source) - self.assertIn('value were both the :class:`bytes` object', rendered) + self.assertIn('has a :class:`bytes` name or value', source) + self.assertIn('has a :class:`bytes` name or value', rendered) class VendorTemplateParityTests(unittest.TestCase): diff --git a/tests/project/test_changelog_md.py b/tests/project/test_changelog_md.py index 64e2b2deeb..5e98c543ee 100644 --- a/tests/project/test_changelog_md.py +++ b/tests/project/test_changelog_md.py @@ -419,9 +419,9 @@ def test_markdown_metacharacters_are_escaped_in_text_and_target(self) -> None: self.assertIn(r'[a \[b\]](https://en.wikipedia.org/wiki/Foo_%28bar%29%20baz)', markdown) def test_an_unknown_role_is_still_fatal(self) -> None: - # Shows the guard was not loosened; it is not evidence of new behaviour. The - # ``:ref:`` half passed before the change too -- only the ``:issue:`` half - # failed without it, by being left unconverted. + # The guard refuses a role it does not know: the ``:ref:`` half is left + # unconverted and raises, and the ``:issue:`` half converts, so only + # ``:ref:`` is named in the error. index = self.make_tree( entry=ENTRY + '\nSee :issue:`29` and :ref:`changelog` for more.\n') diff --git a/tests/project/test_docs_internal_refs_1940_unit.py b/tests/project/test_docs_internal_refs_1940_unit.py index 6dfccaa34c..5f2ba82ec3 100644 --- a/tests/project/test_docs_internal_refs_1940_unit.py +++ b/tests/project/test_docs_internal_refs_1940_unit.py @@ -101,7 +101,7 @@ ':class:`~pcapkit.const.ftp.command.CommandType`'), ('docs/source/contributing/conventions/sentinel-convention.rst', '``NoDefaultType``', ':class:`~pcapkit.corekit.sentinels.NoDefaultType`'), - # On this page with the backport it names (#2051). + # On this page as the re-export of functools.cached_property (#2051). ('docs/source/contributing/conventions/sentinel-convention.rst', '``cached_property``', ':class:`~pcapkit.utilities.compat.cached_property`'), ('docs/source/contributing/releasing.rst', '``pcapkit.__version__``', diff --git a/tests/project/test_docs_internal_refs_1947_unit.py b/tests/project/test_docs_internal_refs_1947_unit.py index f8c9b89397..0d44f679ab 100644 --- a/tests/project/test_docs_internal_refs_1947_unit.py +++ b/tests/project/test_docs_internal_refs_1947_unit.py @@ -37,10 +37,10 @@ #: ``(source, literal in context, the same context with the role)``. CONVERTED = ( - ('pcapkit/vendor/reg/apptype/apptype.py', "dropped ``TransportProtocol``'s", - f"dropped\n {TRANSPORT_PROTOCOL}'s"), - ('pcapkit/const/reg/apptype/apptype.py', "dropped ``TransportProtocol``'s", - f"dropped\n {TRANSPORT_PROTOCOL}'s"), + ('pcapkit/vendor/reg/apptype/apptype.py', '``TransportProtocol`` is an ``IntEnum``', + f'{TRANSPORT_PROTOCOL}\n is an ``IntEnum``'), + ('pcapkit/const/reg/apptype/apptype.py', '``TransportProtocol`` is an ``IntEnum``', + f'{TRANSPORT_PROTOCOL}\n is an ``IntEnum``'), ('pcapkit/vendor/reg/apptype/apptype.py', 'as a ``TransportProtocol`` expression', f'as a\n {TRANSPORT_PROTOCOL} expression'), ) + tuple( diff --git a/tests/project/test_issue_refs_in_comments.py b/tests/project/test_issue_refs_in_comments.py index 1d7ad23a4a..a720eae419 100644 --- a/tests/project/test_issue_refs_in_comments.py +++ b/tests/project/test_issue_refs_in_comments.py @@ -42,7 +42,7 @@ '# ``:issue:`` would link to a page that does not exist.'), # Describes the changelog converter's test input, which uses the role. ('tests/project/test_changelog_md.py', - '# ``:ref:`` half passed before the change too -- only the ``:issue:`` half'), + '# unconverted and raises, and the ``:issue:`` half converts, so only'), })