oc_diagnostics.id_instrumentation Namespace Reference

Functions
	is_structural_id (cid)
bool	_is_dash_component (component)
	instrument_ids (component, int _depth=0)

Variables
tuple	STRUCTURAL_ID_PREFIXES
dict	STRUCTURAL_ID_EXACT
int	MAX_INSTRUMENT_DEPTH = 500

Detailed Description

ID Instrumentation Helper
=========================

This module rewrites Dash component IDs so that every interactive component
receives a pattern-matching ID of the form:

    id = {"event": "<original-id>"}

This enables the UI event logger to capture all user interactions.

Instrumentation behavior is controlled by:
- Global toggle: INSTRUMENTATION_ENABLED
- Debug level:   DEBUG_LEVELS["INSTRUMENTATION"] (0–9)

Instrumentation is recursive and safe:
- Structural IDs are never rewritten
- Dict IDs are never rewritten
- Components without IDs are skipped
- Custom components may be included depending on debug level
- Logging verbosity depends on instrumentation debug level

Responsibilities
----------------
- Recursively walk Dash component trees via the ``.children`` attribute.
- Rewrite string IDs to ``{"event": "<original-id>"}`` when instrumentation
  is active.
- Skip structural IDs (defined in ``STRUCTURAL_ID_PREFIXES`` and
  ``STRUCTURAL_ID_EXACT``).
- Skip dict IDs and components without an ``id`` attribute.
- Delegate verbosity decisions to ``unified_debug`` helpers
  (``instrumentation_verbose()``, ``instrumentation_allow_custom_components()``).

Diagnostics
-----------
Domain: INSTRUMENTATION
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing

Contracts
---------
- Structural IDs (``root-group-*``, ``tab-group-*``, etc.) must never be
  rewritten.
- Dict IDs must never be rewritten.
- Must return the component unchanged when ``instrumentation_active()`` is
  ``False``.
- Must not raise; errors during ID rewriting are silently swallowed.
- Must not recurse beyond ``MAX_INSTRUMENT_DEPTH`` (500) levels; a L1
  diagnostic is emitted and the subtree is returned unchanged.
- Standard Dash base-class components are always instrumented when active.
- Custom (non-Dash-base-class) components are only instrumented when
  ``instrumentation_allow_custom_components()`` returns ``True``
  (``INSTRUMENTATION`` level ≥ 5).  This prevents accidental ID rewriting
  of plain Python objects that happen to have a ``.id`` attribute.

Function Documentation

_is_dash_component()

bool oc_diagnostics.id_instrumentation._is_dash_component ( component )

protected

Return True if *component* inherits from the Dash base Component class.

Dash is an optional dependency.  When it is not installed this function
always returns False, which causes all components to be treated as custom
and therefore subject to the ``instrumentation_allow_custom_components()``
level gate.

Definition at line 121 of file id_instrumentation.py.

Here is the caller graph for this function:

instrument_ids()

oc_diagnostics.id_instrumentation.instrument_ids	(		component,
		int	_depth = 0 )

Recursively instrument Dash component IDs.

Behavior is controlled by unified_debug:

- instrumentation_active():
    False → return component unchanged

- instrumentation_verbose():
    True  → log detailed recursion info
    False → log only high-level events

- instrumentation_allow_custom_components():
    True  → include custom (non-Dash-base-class) components
    False → only standard Dash base-class components are instrumented

Rules:
- Instrument ANY component that has an ID stored in `.id`,
  or in Dash internals (`_props`, `_prop_ids`).
- Only rewrite string IDs (ignore dict IDs, None, etc.).
- Skip structural IDs.
- Recurse into children (list, tuple, or single child).
- Stop recursion if depth exceeds MAX_INSTRUMENT_DEPTH.

Definition at line 154 of file id_instrumentation.py.

Here is the call graph for this function:

Here is the caller graph for this function:

is_structural_id()

oc_diagnostics.id_instrumentation.is_structural_id

(

cid

)

Return True if this ID should NOT be instrumented.

Checks both the built-in structural-ID lists and any project-defined
extensions loaded from ``global_settings.structural_id_prefixes`` /
``global_settings.structural_id_exact`` in ``debug_config.json``
(FS-02 / OI-17).

Definition at line 101 of file id_instrumentation.py.

Here is the caller graph for this function:

Variable Documentation

MAX_INSTRUMENT_DEPTH

int oc_diagnostics.id_instrumentation.MAX_INSTRUMENT_DEPTH = 500

Definition at line 140 of file id_instrumentation.py.

STRUCTURAL_ID_EXACT

dict oc_diagnostics.id_instrumentation.STRUCTURAL_ID_EXACT

Initial value:

=  {
    "theme-root",
    "theme-style-injector",
    "ui-theme-store",
    "system-settings-store",
    "data-settings-store",
    "plot-settings-store",
    "settings-data-store",
    "debug-settings-data-store",
    "debug-plot-settings-store",
    "init-once",
    "system-auto-load-interval",
    "plot-figure",          # Plot callback outputs to this
    "plot-status",          # Plot callback outputs to this
    "plot-size-indicator",  # Plot callback outputs to this
}

Definition at line 83 of file id_instrumentation.py.

STRUCTURAL_ID_PREFIXES

tuple oc_diagnostics.id_instrumentation.STRUCTURAL_ID_PREFIXES

Initial value:

=  (
    "root-group-",
    "tab-group-",
    "tab-content-",
    "pane-group-",
)

Definition at line 76 of file id_instrumentation.py.