PEP 669: Add an enum and namespace to the interface. (#2186)

pep-0669.rst

@@ -20,6 +20,10 @@ on CPython that will enable monitoring at low cost.
 Although this PEP does not specify an implementation, it is expected that
 it will be implemented using the quickening step of PEP 659 [1]_.
 
+A ``sys.monitoring`` namespace will be added, which will contain
+the relevant functions and enum.
+
+
 Motivation
 ==========
 
@@ -80,18 +84,23 @@ For 3.11, CPython will support the following events:
 
 More events may be added in the future.
 
-All event codes are integer powers of two and can be bitwise or-ed together to
+All events will be attributes of the ``Event`` enum in ``sys.monitoring``::
-activate multiple events.
+
+  class Event(enum.IntFlag):
+      PY_CALL = ...
+
+Note that ``Event`` is an ``IntFlag`` which means that the events can be or-ed
+together to form a set of events.
 
 Setting events globally
 -----------------------
 
 Events can be controlled globally by modifying the set of events being monitored:
 
-* ``sys.get_monitoring_events()->int``
+* ``sys.monitoring.get_events()->Event``
-  Returns the ``int`` resulting from bitwise-oring all the active events.
+  Returns the ``Event`` set for all the active events.
 
-* ``sys.set_monitoring_events(event_set: int)``
+* ``sys.monitoring.set_events(event_set: Event)``
   Activates all events which are set in ``event_set``.
 
 No events are active by default.
@@ -101,11 +110,11 @@ Per code object events
 
 Events can also be controlled on a per code object basis:
 
-* ``sys.get_local_monitoring_events(code: CodeType)->int``
+* ``sys.monitoring.get_local_events(code: CodeType)->Event``
-  Returns the ``int`` resulting from bitwise-oring all the local events for ``code``
+  Returns the ``Event`` set for all the local events for ``code``
 
-* ``sys.set_local_monitoring_events(code: CodeType, event_set: int)``
+* ``sys.monitoring.set_local_events(code: CodeType, event_set: Event)``
-  Returns the ``int`` resulting from bitwise-oring all the local events for ``code``
+  Activates all the local events for ``code``  which are set in ``event_set``.
 
 Local events add to global events, but do not mask them.
 In other words, all global events will trigger for a code object, regardless of the local events.
@@ -116,10 +125,10 @@ Register callback functions
 
 To register a callable for events call::
 
-  sys.register_monitoring_callback(event, func)
+  sys.monitoring.register_callback(event, func)
 
 Functions can be unregistered by calling
-``sys.register_monitoring_callback(event, None)``.
+``sys.monitoring.register_callback(event, None)``.
 
 Callback functions can be registered and unregistered at any time.
 
@@ -168,23 +177,24 @@ Inserting and removing markers
 
 Two new functions are added to the ``sys`` module to support markers.
 
-* ``sys.insert_marker(code: CodeType, offset: int, marker_id=0: range(256))``
+* ``sys.monitoring.insert_marker(code: CodeType, offset: int, marker_id=0: range(256))``
-* ``sys.remove_marker(code: CodeType, offset: int)``
+* ``sys.monitoring.remove_marker(code: CodeType, offset: int)``
 
 The ``marker_id`` has no meaning to the VM,
 and is used only as an argument to the callback function.
 The ``marker_id`` must in the range 0 to 255 (inclusive).
 
-List of new functions
+Attributes of the ``sys.monitoring`` namespace
-'''''''''''''''''''''
+''''''''''''''''''''''''''''''''''''''''''''''
 
-* ``sys.get_monitoring_events()->int``
+* ``class Event(enum.IntFlag)``
-* ``sys.set_monitoring_events(event_set: int)``
+* ``def get_events()->Event``
-* ``sys.get_local_monitoring_events(code: CodeType)->int``
+* ``def set_events(event_set: Event)->None``
-* ``sys.set_local_monitoring_events(code: CodeType, event_set: int)``
+* ``def get_local_events(code: CodeType)->Event``
-* ``sys.register_monitoring_callback(event: int, func: Callable)``
+* ``def set_local_events(code: CodeType, event_set: Event)->None``
-* ``sys.insert_marker(code: CodeType, offset: int, marker_id=0: range(256))``
+* ``def register_callback(event: Event, func: Callable)->None``
-* ``sys.remove_marker(code: CodeType, offset: int)``
+* ``def insert_marker(code: CodeType, offset: Event, marker_id=0: range(256))->None``
+* ``def remove_marker(code: CodeType, offset: Event)->None``
 
 Backwards Compatibility
 =======================
@@ -196,11 +206,11 @@ However, if it is used it will effectively disable ``sys.settrace``,
 ``sys.setprofile`` and PEP 523 frame evaluation.
 
 If PEP 523 is in use, or ``sys.settrace`` or ``sys.setprofile`` has been
-set, then calling ``sys.set_monitoring_events()`` or 
+set, then calling ``sys.monitoring.set_events()`` or
-``sys.set_local_monitoring_events()`` will raise an exception.
+``sys.monitoring.set_local_events()`` will raise an exception.
 
-Likewise, if ``sys.set_monitoring_events()`` or 
+Likewise, if ``sys.monitoring.set_events()`` or
-``sys.set_local_monitoring_events()`` has been called, then using PEP 523
+``sys.monitoring.set_local_events()`` has been called, then using PEP 523
 or calling ``sys.settrace`` or ``sys.setprofile`` will raise an exception.
 
 This PEP is incompatible with ``sys.settrace`` and ``sys.setprofile``