PyAPI: temporary context override support

Support a way to temporarily override the context from Python.

- Added method `Context.temp_override` context manager.
- Special support for windowing variables "window", "area" and "region",
  other context members such as "active_object".
- Nesting context overrides is supported.
- Previous windowing members are restored when the context exists unless
  they have been removed.
- Overriding context members by passing a dictionary into operators in
  `bpy.ops` has been deprecated and warns when used.

This allows the window in a newly loaded file to be used, see: T92464

Reviewed by: mont29

Ref D13126

3 files changed, 50 insertions, 0 deletions

diff --git a/doc/python_api/examples/bpy.types.Context.temp_override.1.py b/doc/python_api/examples/bpy.types.Context.temp_override.1.py
new file mode 100644
index 00000000000..68f0eef93c3
--- /dev/null
+++ b/doc/python_api/examples/bpy.types.Context.temp_override.1.py
@@ -0,0 +1,19 @@
+"""
+Overriding the context can be used to temporarily activate another ``window`` / ``area`` & ``region``,
+as well as other members such as the ``active_object`` or ``bone``.
+
+Notes:
+
+- When overriding window, area and regions: the arguments must be consistent,
+  so any region argument that's passed in must be contained by the current area or the area passed in.
+  The same goes for the area needing to be contained in the current window.
+
+- Temporary context overrides may be nested, when this is done, members will be added to the existing overrides.
+
+- Context members are restored outside the scope of the context.
+  The only exception to this is when the data is no longer available.
+
+  In the event windowing data was removed (for example), the state of the context is left as-is.
+  While this isn't likely to happen, explicit window operation such as closing windows or loading a new file
+  remove the windowing data that was set before the temporary context was created.
+"""
diff --git a/doc/python_api/examples/bpy.types.Context.temp_override.2.py b/doc/python_api/examples/bpy.types.Context.temp_override.2.py
new file mode 100644
index 00000000000..ce3e1594baa
--- /dev/null
+++ b/doc/python_api/examples/bpy.types.Context.temp_override.2.py
@@ -0,0 +1,15 @@
+"""
+Overriding the context can be useful to set the context after loading files
+(which would otherwise by None). For example:
+"""
+
+import bpy
+from bpy import context
+
+# Reload the current file and select all.
+bpy.ops.wm.open_mainfile(filepath=bpy.data.filepath)
+window = context.window_manager.windows[0]
+with context.temp_override(window=window):
+    bpy.ops.mesh.primitive_uv_sphere_add()
+    # The context override is needed so it's possible to set edit-mode.
+    bpy.ops.object.mode_set(mode='EDIT')
diff --git a/doc/python_api/examples/bpy.types.Context.temp_override.3.py b/doc/python_api/examples/bpy.types.Context.temp_override.3.py
new file mode 100644
index 00000000000..e670bb7bafa
--- /dev/null
+++ b/doc/python_api/examples/bpy.types.Context.temp_override.3.py
@@ -0,0 +1,16 @@
+"""
+This example shows how it's possible to add an object to the scene in another window.
+"""
+import bpy
+from bpy import context
+
+win_active = context.window
+win_other = None
+for win_iter in context.window_manager.windows:
+    if win_iter != win_active:
+        win_other = win_iter
+        break
+
+# Add cube in the other window.
+with context.temp_override(window=win_other):
+    bpy.ops.mesh.primitive_cube_add()