From 898b0a958fe5a44b07a575b3c53e72cdb484f5eb Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 9 May 2026 19:15:33 -0500 Subject: [PATCH] docs(constants[default-scope]) Document DEFAULT_OPTION_SCOPE sentinel MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit why: `DEFAULT_OPTION_SCOPE` is the sentinel default for the `scope=` parameter on every option-related helper (Pane._show_option, Server.show_options, Window._set_options_raw, …). Without a docstring on the assignment Sphinx's autodoc skips it under `automodule :members: undoc-members:`, so the docs site has no `#libtmux.constants.DEFAULT_OPTION_SCOPE` anchor — and any default- value cross-reference in those signatures has no target to link to. Adding the attribute docstring (PEP 258 — module-attribute docstring picked up by `ModuleAnalyzer.attr_docs`) gives the sentinel a docs entry and lets the gp-sphinx default-value xref transform render `scope=DEFAULT_OPTION_SCOPE` as a clickable link to the documented constant on `api/libtmux.constants/`. Also promote `_DefaultOptionScope`'s `# Sentinel value for default scope` comment to a proper docstring; the class already shows up as a documented entry on the constants page (per the autodoc default options) and a real docstring describes the sentinel pattern more clearly than the stub comment. what: - Add an attribute docstring to `DEFAULT_OPTION_SCOPE` describing the sentinel semantics and the per-receiver scope inference rule. - Replace `_DefaultOptionScope`'s stub comment with a class docstring describing the sentinel-type role and pointing at the lone documented instance. --- src/libtmux/constants.py | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/src/libtmux/constants.py b/src/libtmux/constants.py index 43ad3f519..eca06f849 100644 --- a/src/libtmux/constants.py +++ b/src/libtmux/constants.py @@ -54,11 +54,25 @@ class PaneDirection(enum.Enum): class _DefaultOptionScope: - # Sentinel value for default scope - ... + """Sentinel type for the ``scope=`` parameter's default value. + + The lone instance :data:`DEFAULT_OPTION_SCOPE` is used as the + default for option-related helpers; receiving methods use ``is`` + comparison against the sentinel to detect "no explicit scope was + passed" and infer the right scope from the bound object type. + """ DEFAULT_OPTION_SCOPE: _DefaultOptionScope = _DefaultOptionScope() +"""Sentinel default for ``scope=`` parameters on option / hook helpers. + +When ``scope is DEFAULT_OPTION_SCOPE`` the caller hasn't selected an +explicit :class:`OptionScope`; the receiving method +(:meth:`Pane._show_option`, :meth:`Server.show_options`, etc.) +infers the appropriate scope from the bound object type +(``Pane`` → ``OptionScope.Pane``, ``Server`` → ``OptionScope.Server``, +…). +""" class OptionScope(enum.Enum):