Add sys.set_object_tags() and sys.get_object_tags() APIs for debugging and experimental Use

Background

CPython currently exposes several internal implementation details via APIs such as:

• sys._defer_refcount
• sys._is_immortal
• sys._is_interned

These APIs leak implementation-specific details and create implicit expectations of cross-version(e.g 3.13, 3.14, 3.15...) and cross-implementation compatibility(e.g CPython, PyPy, RustPython), even though they are not part of any formal public API contract.

For example, other Python implementations may not support or emulate these features, and yet their presence in CPython can create unintentional backward compatibility burdens when new releases are made.

Proposal

To address this, I would like to propose introducing two weak introspection APIs in the sys module:

sys.set_tags(obj, ["defer_refcount", "tag2"]) -> None
sys.get_tags(obj) -> tuple

sys.set_tags(obj, tags: Iterable[str]) -> None

• Sets optional "tags" on an object.
• Tags are hints for the Python implementation and are not guaranteed to be applied or have any effect.
• The implementation may accept or ignore any or all provided tags.
• These tags are advisory only, intended primarily for debugging, experimentation, and tooling used by Python implementation developers.

sys.get_tags(obj) -> tuple[str, ...]

• Returns the tags currently associated with the object.
• These reflect only the tags actually recognized and retained by the interpreter.
• For example:

  sys.set_tags(o, ["defer_refcount", "tag2"])
  print(sys.get_tags(o))  # May return: ('defer_refcount',)
  

• If the object is already immortal due to previous operations, you might see:

  sys.get_tags(o)  # May return: ('defer_refcount', 'immortal')
  

Goals and Non-Goals

Goals:

• Provide a mechanism to annotate or mark objects for introspection/debugging.
• Allow developers of Python implementations or advanced tools to experiment with internal object states in a controlled manner.

Non-Goals:

• These APIs are not intended to be stable or relied upon for program behavior.
• No tag is guaranteed to have any effect or to be preserved between runs, interpreter versions, or across implementations.

Documentation and Guarantees

We will clearly document that:

• These APIs are for Python implementation developers only.
• The presence or absence of any particular tag does not imply any behavioral guarantees.
• Tags may be implementation-specific, and unsupported tags will be silently ignored.
• Maybe possible to provide Python-specific tags in somewhere but should note that it will not be guarantee according to versions

cc @ZeroIntensity @vstinner @Fidget-Spinner @colesbury

Linked PRs

• gh-135073