object() sentinel sweep for #640: three sites left, each a judgement call rather than a mechanical pass

[JarryShaw]

Follow-up to the review comment on #640, which asked for a sweep: "do another sweep to see if we're
having other places in the library using an object() sentinel - update it to follow the actual
class/object convention."

The sweep is done. #640 fixed its own site (_MISSING = object() became _Absent, an instance of a
@final _AbsentType following NoValueType). What is left is three sites, and none of them is a
mechanical pass — each is a judgement call with a reason to leave it alone, so they are written up
here rather than changed unilaterally.

What the sweep covered

Over pcapkit/, for: = object(); type('...', (), {})(); module- and class-level names matching
MISSING/SENTINEL/UNSET/NOT_SET/NOT_FOUND/NO_VALUE/ABSENT/UNDEFINED/OMITTED; any
default= whose absence is signalled by an identity comparison; every is / is not against a
non-builtin name; and any class existing only to be a singleton marker.

type('...', (), {})() has zero hits package-wide. object() has exactly one hit left,
item 3 below. Nothing under pcapkit/const/ or pcapkit/vendor/ holds an identity sentinel at all.

The inventory

1. NoValue / NoValueType — pcapkit/corekit/fields/field.py:26-36

Already the convention: @final class, __bool__ returning False, one module-level instance.
Nothing to do — this is the thing the other sites are being compared against.

Worth recording how far it travels, because it is the reason #640 did not simply reuse it: it is
documented (docs/source/pcapkit/corekit/fields/field.rst:17-18), it is the declared default of 11
public field constructors, it is returned from SwitchField.pre_process/post_process
(pcapkit/corekit/fields/misc.py:444, :474), it is written into the packet context
(pcapkit/protocols/schema/schema.py:851), it is stored on a schema attribute
(pcapkit/protocols/schema/internet/hopopt.py:709, ipv6_opts.py:714) and translated back to None
before it reaches the data model (pcapkit/protocols/internet/hopopt.py:1053,
ipv6_opts.py:1056), and it is baked as the default of every generated Schema.__init__
(pcapkit/protocols/schema/schema.py:71). It means "no value was given", which is not the question
#640's site asks.

2. _missing / _Missing — pcapkit/corekit/multidict.py:78-86

class _Missing:
    def __repr__(self) -> 'str':
        return "no value"

    def __reduce__(self) -> 'str':
        return "_missing"


_missing = _Missing()

Guards "did the caller pass a default to pop(), or should a missing key raise?" — used at
multidict.py:373, :393, :592, :596. None is genuinely unavailable: pop(key, None) is the
canonical dict idiom for "give me None rather than raise", so if the marker were None that call
would raise MissingKeyError.

This already satisfies the convention in the sense the review comment asked for — it is an
instance of a purpose-built class, not a bare object(). What it lacks against NoValueType is
@final and __bool__.

Recommendation: leave it, or add only @final. Two things make it more than a style edit:

• It is the declared default of two public methods, so it is reachable without touching a
  private name (inspect.signature(MultiDict.pop).parameters['default'].default). The @overload
  stubs above each def spell it ..., so the type-checker-visible signature hides it while the
  runtime one does not.
• __reduce__ returning the bare string "_missing" is pickle-by-name, which only resolves
  while pcapkit.corekit.multidict._missing is importable under exactly that name. Cross-process
  escape is deliberately supported, and tests/corekit/test_multidict.py:34-35 asserts both
  repr(...) == 'no value' and __reduce__() == '_missing'. Adding __bool__ returning False
  would also be a live behaviour change rather than a cosmetic one, since this instance is reachable
  by callers.

3. _NOT_FOUND = object() — pcapkit/utilities/compat.py:73

The only bare object() left in the package. Guards "has this cached_property already computed
its value?", at compat.py:106, :107, :110, :111. Genuinely module-private: val is
unconditionally overwritten before return val, it is not a parameter default, and git grep
finds the name nowhere else in the repo — not in another module, not in tests/, not in docs/.
None would not work: a cached_property legitimately returning None would recompute forever.

Recommendation: leave it. Two reasons, both about what the file is rather than about the
sentinel:

• It is a verbatim backport of CPython's own functools.cached_property, which uses
  _NOT_FOUND = object() for exactly this. Renaming it to a house-convention singleton diverges the
  copy from the upstream it mirrors, which is the thing that makes a backport auditable.
• It sits inside if sys.version_info < (3, 8): (opened at compat.py:71, with
  from functools import cached_property in the else:), so it is unreachable on 3.8+ and
  therefore untested and unmeasurable. pyproject.toml:49 still declares
  requires-python = ">=3.6, <4", so it is not dead by declaration, only in practice.

If the preference is house convention over upstream fidelity, this is a two-line change and I am
happy to make it — it just should be a decision rather than a drive-by.

Adjacent, and out of scope by the letter of the sweep

default: 'int' = -1 on the get() of 113 generated const enums. Same "absent versus supplied"
question, in the same semantic slot, but compared with == rather than is, so it is not an
identity sentinel. Representative: pcapkit/const/arp/hardware.py:150, :165. It is generated,
from the {NAME} template at pcapkit/vendor/default.py:75-92, plus nine vendor modules carrying
their own copy of the same template (pcapkit/vendor/ftp/return_code.py:145,
http/status_code.py:78, ipv6/extension_header.py:55, mh/binding_ack_flag.py:54,
mh/binding_update_flag.py:53, mh/handover_ack_flag.py:54, mh/handover_initiate_flag.py:54,
tcp/flags.py:70) — so any change belongs in the templates, never in pcapkit/const/, since
make vendor strips a hand edit.

Two reasons it is not a cleanup: -1 collides with a real code in any registry that has one, and it
is dispatched on across module boundaries — pcapkit/protocols/link/l2tpv2.py:237 and
pcapkit/protocols/link/ospf.py:191 both say in a comment that they dispatch on "the -1 sentinel, as
ARP does". Changing it is a behaviour change to 113 public get() signatures. Two enums already use
None for the same slot instead (pcapkit/const/ftp/command.py:288,
pcapkit/const/http/method.py:166), so the inconsistency is real; it is just much bigger than this
issue. Worth its own issue if it is wanted.

Checked and excluded, so nobody re-treads them

multidict.py:72/:74 (linked-list node identity); infoclass.py:82/:89 (class-object identity);
foundation/reassembly/data/data.py:60-90 (Completion, a three-valued StrEnum with a real
__bool__, not an absent-marker); corekit/context.py:244 (ordinary container truthiness);
corekit/fields/field.py:168-171 (ContextVar defaulting to None, no sentinel object);
protocols/schema/schema.py:956 (__missing__, a defaultdict hook, the #555 fix); every = ...
in an @overload or if TYPE_CHECKING: stub; and foundation/extraction.py:860-861, where the
'null'/'none' strings are the normalised form and None is already the absent marker
(pcapkit/__main__.py:90-93 records that inversion deliberately).

Suggested disposition

1. _NOT_FOUND — decide upstream-fidelity versus house convention. Two lines either way.
2. _missing — @final only, if anything; not __bool__, which callers can observe.
3. The -1 const default — separate issue if wanted, since it is 113 generated files and a
   cross-module behaviour change.

[JarryShaw]

Site 3 — _NOT_FOUND = object() at pcapkit/utilities/compat.py:73: leave it, and consider deleting the block it lives in

Site 2 is done in #667 (@final + __bool__ on _Missing, with the override of this issue's
@final-only recommendation argued there). Site 1 needed nothing. This comment is the decision
write-up for site 3, which stays a decision rather than a change — it is the owner's call, which is
why #667 says Refs #661 and not Fixes.

Recommendation: do not convert it. Both halves of the argument in the issue body hold up, but the
second half is stronger than stated there, and it points somewhere different from "leave it alone".

Half 1 — it is verbatim upstream, and this is now measured rather than asserted

Fetched https://raw.githubusercontent.com/python/cpython/v3.8.0/Lib/functools.py (37 376 bytes) and
diffed it against compat.py:73-121, de-indented by the four spaces the if guard adds:

$ sed -n '73,121p' pcapkit/utilities/compat.py | sed 's/^    //' > /tmp/local.txt
$ sed -n '927,975p' /tmp/functools_380.py > /tmp/upstream.txt
$ diff -u /tmp/upstream.txt /tmp/local.txt

_NOT_FOUND = object() is byte-identical, and it is upstream Lib/functools.py:927 at tag
v3.8.0, sitting immediately above class cached_property: at :930. The full diff over those 49
lines comes to ten differences and not one of them is logic:

upstream	local	what it is
two blank lines before the class	one	cosmetic
class cached_property:	class cached_property(Generic[_T]):	static typing
def __init__(self, func):	annotated	static typing
self.func = func	+ # type: Callable[[Any], _T]	static typing
self.attrname = None	+ # type: Optional[str]	static typing
def __set_name__(self, owner, name):	annotated	static typing
def __get__(self, instance, owner=None):	annotated, split over two lines	static typing
if self.attrname is None:	+ # pragma: no cover	coverage
inner if val is _NOT_FOUND:	+ # pragma: no branch	coverage
except TypeError:	+ # pragma: no cover	coverage

Every executable expression is identical: self.lock = RLock(), the double-checked-locking
with self.lock: block, the # check if another thread filled cache while we awaited lock comment
verbatim, both TypeError message strings verbatim, and return val at upstream's indentation.

Worth recording which upstream it tracks, because it is not the current one. Modern CPython
removed the per-property lock; the 3.14.7 stdlib on this machine reads:

$ python -c "import functools, inspect; print(inspect.getsource(functools.cached_property))"

— no RLock, no self.lock, no "awaited lock" comment, plus two things the local copy does not have
(self.__module__ = func.__module__ in __init__, and __class_getitem__ = classmethod(GenericAlias)).
So the backport tracks pre-3.12 CPython, matched exactly to 3.8.0. _NOT_FOUND = object() itself
has not changed across any of it — it is still there in 3.14's functools.

That is the whole case for leaving the sentinel: the line's value is that it is diffable against a
named upstream tag, and a house-convention singleton would cost that for no behavioural gain in a
block that never runs.

Half 2 — the block is dead code on every Python this project tests, and three stated floors disagree

Read from the tree rather than taken on trust:

• Declared floor: 3.6. pyproject.toml:49 — requires-python = ">=3.6, <4"; classifiers at
  :65-73 list 3.6 through 3.14; README.md:19 — "The whole project supports Python 3.6 or
  later"; vermin.ini:31 — targets = 3.6; setup.py:43,55 gate the bpc-f2format / bpc-walrus
  conversions on < (3, 6) and < (3, 8).
• Real floor, per the project's own build tooling: 3.11. Makefile:155-157, in the comment
  explaining why vermin-ci exists at all: "targets = 3.6 in vermin.ini is for: vermin exits
  non-zero when the target is not met, and the code's real floor is 3.11."
• Tested floor: 3.10. Every matrix in .github/workflows/ is 3.10, 3.11, 3.12, 3.13, 3.14 plus
  3.15 as experimental: true — unit-tests.yml:58-68 and :100-110,
  python-compatibility.yml:37-47, and the same list in create-release.yml and cron-conda.yml.
  Nothing anywhere runs 3.6, 3.7, 3.8 or 3.9.

pyproject.toml already says both of the latter two in its own comment, at :44-48:

Until it lands, sub-3.8 support is intent rather than something that works.

Independently: CI covers 3.10 through 3.14 (3.15 runs allowed-to-fail), so 3.8 and 3.9 are
best-effort (both are end-of-life), and the PCAP_CT extra needs 3.10 regardless.

So: if sys.version_info < (3, 8): is unreachable on every interpreter this project tests, and the
lowest version given any attention at all is 3.8 — which is already >= (3, 8). The issue body put
this as "unreachable on 3.8+ and therefore untested and unmeasurable, but not dead by declaration,
only in practice". Measured, it is a little worse than that: even under the declared 3.6 floor, the
same pyproject.toml comment (:31-45) documents the live bpc-poseur 0.4.3.post1 bug that breaks
the conversion needed to make the package importable below 3.8 at all. There is currently no
interpreter, tested or declared, on which this branch both runs and works.

Where that actually points

The dead-code finding is the stronger argument, and it does not argue for "leave it alone" — it argues
that converting the sentinel and keeping the block are both the wrong move, and deleting the block is
the right follow-up. A backport whose value is upstream fidelity, guarding a version nothing runs, is
carrying the maintenance cost of both properties and paying for neither.

That is a bigger change than two lines and not mine to make unilaterally, because it is not one block:
compat.py carries < (3, 4), < (3, 6), < (3, 8) and < (3, 9) guards, setup.py:43,55 gate the
bpc-* conversions, vermin.ini:31 targets 3.6, and README.md:19 and the pyproject.toml
classifiers all state 3.6 — so dropping the floor is one coherent decision across six files, not a
drive-by. Concretely, if the floor is to move, that is its own issue and its own PR; if the floor
stays declared at 3.6 as aspiration, then leave _NOT_FOUND exactly as it is, since fidelity to
v3.8.0 is the only thing making the aspiration auditable.

Either way, do not house-convention this one line. It is the only bare object() left in the
package, and that is the correct number for it to be.

[JarryShaw]

Owner decision on site 3: leave it as is

In the owner's words:

leave it as is since it's a compat code from direct copy from stdlib

So _NOT_FOUND = object() at pcapkit/utilities/compat.py:73 stays unchanged, and the "consider deleting the dead block" suggestion above is declined — the provenance is the point, not the reachability.

That matches what the measurement established: fetched CPython v3.8.0 Lib/functools.py (37,376 bytes) and diffed compat.py:73-121 against upstream :927-975 de-indented by the guard's four spaces. _NOT_FOUND = object() is byte-identical to upstream Lib/functools.py:927, and of the ten differences across those 49 lines not one is logic — two blank lines versus one, Generic[_T], and annotations.

All three sites are now settled:

• Site 1, NoValue / NoValueType at pcapkit/corekit/fields/field.py:26-36 — already the convention, nothing to do.
• Site 2, _missing / _Missing at pcapkit/corekit/multidict.py:78-86 — @final and __bool__ added in fix(corekit): give the MultiDict _missing sentinel @final and __bool__ #667.
• Site 3, _NOT_FOUND — left as verbatim stdlib compat code, by the decision above.

Closing. #667 carries Refs #661 rather than Fixes, so it does not close this on merge; closing by hand instead.