Refactoring, Stdlib, everything!

std/sentinels.py

@@ -0,0 +1,121 @@
+import sys as _sys
+from threading import Lock as _Lock
+
+
+__all__ = ['Sentinel']
+
+
+# Design and implementation decisions:
+#
+# The first implementations created a dedicated class for each instance.
+# However, once it was decided to use Sentinel for type signatures, there
+# was no longer a need for a dedicated class for each sentinel value on order
+# to enable strict type signatures.  Since class objects consume a relatively
+# large amount of memory, the implementation was changed to avoid this.
+#
+# With this change, the mechanism used for unpickling/copying objects needed
+# to be changed too, since we could no longer count on each dedicated class
+# simply returning its singleton instance as before.  __reduce__ can return
+# a string, upon which an attribute with that name is looked up in the module
+# and returned.  However, that would have meant that pickling/copying support
+# would depend on the "name" argument being exactly the name of the variable
+# used in the module, and simply wouldn't work for sentinels created in
+# functions/methods.  Instead, a registry for sentinels was added, where all
+# sentinel objects are stored keyed by their name + module name.  This is used
+# to look up existing sentinels both during normal object creation and during
+# copying/unpickling.
+
+
+class Sentinel:
+    """Create a unique sentinel object.
+
+    *name* should be the fully-qualified name of the variable to which the
+    return value shall be assigned.
+
+    *repr*, if supplied, will be used for the repr of the sentinel object.
+    If not provided, "<name>" will be used (with any leading class names
+    removed).
+
+    *module_name*, if supplied, will be used instead of inspecting the call
+    stack to find the name of the module from which
+    """
+    _name: str
+    _repr: str
+    _module_name: str
+
+    def __new__(
+        cls,
+        name: str,
+        repr: str | None = None,
+        module_name: str | None = None,
+    ):
+        name = str(name)
+        repr = str(repr) if repr else f'<{name.split(".")[-1]}>'
+        if not module_name:
+            parent_frame = _get_parent_frame()
+            module_name = (
+                parent_frame.f_globals.get('__name__', '__main__')
+                if parent_frame is not None
+                else __name__
+            )
+
+        # Include the class's module and fully qualified name in the
+        # registry key to support sub-classing.
+        registry_key = _sys.intern(
+            f'{cls.__module__}-{cls.__qualname__}-{module_name}-{name}'
+        )
+        sentinel = _registry.get(registry_key, None)
+        if sentinel is not None:
+            return sentinel
+        sentinel = super().__new__(cls)
+        sentinel._name = name
+        sentinel._repr = repr
+        sentinel._module_name = module_name
+        with _lock:
+            return _registry.setdefault(registry_key, sentinel)
+
+    def __repr__(self):
+        return self._repr
+
+    def __reduce__(self):
+        return (
+            self.__class__,
+            (
+                self._name,
+                self._repr,
+                self._module_name,
+            ),
+        )
+
+
+_lock = _Lock()
+_registry: dict[str, Sentinel] = {}
+
+
+# The following implementation attempts to support Python
+# implementations which don't support sys._getframe(2), such as
+# Jython and IronPython.
+#
+# For reference, see the implementation of namedtuple:
+# https://github.com/python/cpython/blob/67444902a0f10419a557d0a2d3b8675c31b075a9/Lib/collections/__init__.py#L503
+def _get_parent_frame():
+    """Return the frame object for the caller's parent stack frame."""
+    try:
+        # Two frames up = the parent of the function which called this.
+        return _sys._getframe(2)
+    except (AttributeError, ValueError):
+        global _get_parent_frame
+        def _get_parent_frame():
+            """Return the frame object for the caller's parent stack frame."""
+            try:
+                raise Exception
+            except Exception:
+                try:
+                    return _sys.exc_info()[2].tb_frame.f_back.f_back
+                except Exception:
+                    global _get_parent_frame
+                    def _get_parent_frame():
+                        """Return the frame object for the caller's parent stack frame."""
+                        return None
+                    return _get_parent_frame()
+        return _get_parent_frame()