diff options
Diffstat (limited to 'doc')
18 files changed, 103 insertions, 29 deletions
diff --git a/doc/blender_file_format/BlendFileDnaExporter_25.py b/doc/blender_file_format/BlendFileDnaExporter_25.py index f85d496b9b5..91a313b789f 100755 --- a/doc/blender_file_format/BlendFileDnaExporter_25.py +++ b/doc/blender_file_format/BlendFileDnaExporter_25.py @@ -378,7 +378,8 @@ def usage(): def main(): - import os, os.path + import os + import os.path try: bpy = __import__('bpy') diff --git a/doc/manpage/blender.1.py b/doc/manpage/blender.1.py index 640b00b0c00..6cf2f54b26f 100755 --- a/doc/manpage/blender.1.py +++ b/doc/manpage/blender.1.py @@ -103,10 +103,10 @@ blender \- a full-featured 3D application''') .PP .B blender is a full-featured 3D application. It supports the entirety of the 3D pipeline - ''' -'''modeling, rigging, animation, simulation, rendering, compositing, motion tracking, and video editing. + '''modeling, rigging, animation, simulation, rendering, compositing, motion tracking, and video editing. Use Blender to create 3D images and animations, films and commercials, content for games, ''' -r'''architectural and industrial visualizations, and scientific visualizations. + r'''architectural and industrial visualizations, and scientific visualizations. https://www.blender.org''') diff --git a/doc/python_api/examples/bpy.app.timers.5.py b/doc/python_api/examples/bpy.app.timers.5.py index ddda0576f05..9770c84d4be 100644 --- a/doc/python_api/examples/bpy.app.timers.5.py +++ b/doc/python_api/examples/bpy.app.timers.5.py @@ -11,6 +11,7 @@ import queue execution_queue = queue.Queue() + # This function can safely be called in another thread. # The function will be executed when the timer runs the next time. def run_in_main_thread(function): diff --git a/doc/python_api/examples/bpy.ops.1.py b/doc/python_api/examples/bpy.ops.1.py index efc9f00b0ae..9b690823a18 100644 --- a/doc/python_api/examples/bpy.ops.1.py +++ b/doc/python_api/examples/bpy.ops.1.py @@ -9,7 +9,7 @@ operator in the different part of the user interface. The context overrides are passed as a dictionary, with keys matching the context member names in bpy.context. For example to override ``bpy.context.active_object``, -you would pass ``{'active_object': object}``. +you would pass ``{'active_object': object}`` to :class:`bpy.types.Context.temp_override`. .. note:: @@ -17,8 +17,10 @@ you would pass ``{'active_object': object}``. (otherwise, you'll have to find and gather all needed data yourself). """ -# remove all objects in scene rather than the selected ones +# Remove all objects in scene rather than the selected ones. import bpy -override = bpy.context.copy() -override['selected_objects'] = list(bpy.context.scene.objects) -bpy.ops.object.delete(override) +from bpy import context +override = context.copy() +override["selected_objects"] = list(context.scene.objects) +with context.temp_override(**override): + bpy.ops.object.delete() diff --git a/doc/python_api/examples/bpy.ops.3.py b/doc/python_api/examples/bpy.ops.3.py index 7dec69cf566..e068ab0c0cf 100644 --- a/doc/python_api/examples/bpy.ops.3.py +++ b/doc/python_api/examples/bpy.ops.3.py @@ -1,17 +1,16 @@ """ It is also possible to run an operator in a particular part of the user -interface. For this we need to pass the window, screen, area and sometimes -a region. +interface. For this we need to pass the window, area and sometimes a region. """ -# maximize 3d view in all windows +# Maximize 3d view in all windows. import bpy +from bpy import context -for window in bpy.context.window_manager.windows: +for window in context.window_manager.windows: screen = window.screen - for area in screen.areas: if area.type == 'VIEW_3D': - override = {'window': window, 'screen': screen, 'area': area} - bpy.ops.screen.screen_full_area(override) + with context.temp_override(window=window, area=area): + bpy.ops.screen.screen_full_area() break diff --git a/doc/python_api/examples/bpy.ops.py b/doc/python_api/examples/bpy.ops.py index 76c494ad4f5..e8d545fc855 100644 --- a/doc/python_api/examples/bpy.ops.py +++ b/doc/python_api/examples/bpy.ops.py @@ -33,6 +33,11 @@ There are 3 optional positional arguments (documented in detail below). bpy.ops.test.operator(override_context, execution_context, undo) - override_context - ``dict`` type. + + .. deprecated:: 3.2 + + :class:`bpy.types.Context.temp_override` should be used instead of this argument. + - execution_context - ``str`` (enum). - undo - ``bool`` type. diff --git a/doc/python_api/examples/bpy.types.Bone.convert_local_to_pose.py b/doc/python_api/examples/bpy.types.Bone.convert_local_to_pose.py index 4a88096cf6f..36b161640c2 100644 --- a/doc/python_api/examples/bpy.types.Bone.convert_local_to_pose.py +++ b/doc/python_api/examples/bpy.types.Bone.convert_local_to_pose.py @@ -4,6 +4,7 @@ the middle of updating the armature without having to update dependencies after each change, by manually carrying updated matrices in a recursive walk. """ + def set_pose_matrices(obj, matrix_map): "Assign pose space matrices of all bones at once, ignoring constraints." @@ -11,7 +12,7 @@ def set_pose_matrices(obj, matrix_map): if pbone.name in matrix_map: matrix = matrix_map[pbone.name] - ## Instead of: + # # Instead of: # pbone.matrix = matrix # bpy.context.view_layer.update() 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() diff --git a/doc/python_api/examples/bpy.types.Operator.1.py b/doc/python_api/examples/bpy.types.Operator.1.py index 84397574856..a28db7e84bb 100644 --- a/doc/python_api/examples/bpy.types.Operator.1.py +++ b/doc/python_api/examples/bpy.types.Operator.1.py @@ -42,10 +42,12 @@ class SimpleMouseOperator(bpy.types.Operator): self.y = event.mouse_y return self.execute(context) -# Only needed if you want to add into a dynamic menu + +# Only needed if you want to add into a dynamic menu. def menu_func(self, context): self.layout.operator(SimpleMouseOperator.bl_idname, text="Simple Mouse Operator") + # Register and add to the view menu (required to also use F3 search "Simple Mouse Operator" for quick access) bpy.utils.register_class(SimpleMouseOperator) bpy.types.VIEW3D_MT_view.append(menu_func) diff --git a/doc/python_api/examples/bpy.types.Operator.2.py b/doc/python_api/examples/bpy.types.Operator.2.py index 7ab0143b925..2a14d6b00f5 100644 --- a/doc/python_api/examples/bpy.types.Operator.2.py +++ b/doc/python_api/examples/bpy.types.Operator.2.py @@ -37,7 +37,7 @@ class ExportSomeData(bpy.types.Operator): return {'RUNNING_MODAL'} -# Only needed if you want to add into a dynamic menu +# Only needed if you want to add into a dynamic menu. def menu_func(self, context): self.layout.operator_context = 'INVOKE_DEFAULT' self.layout.operator(ExportSomeData.bl_idname, text="Text Export Operator") diff --git a/doc/python_api/examples/bpy.types.Operator.3.py b/doc/python_api/examples/bpy.types.Operator.3.py index 9a12a7e3615..fb40616d15d 100644 --- a/doc/python_api/examples/bpy.types.Operator.3.py +++ b/doc/python_api/examples/bpy.types.Operator.3.py @@ -27,7 +27,8 @@ class DialogOperator(bpy.types.Operator): wm = context.window_manager return wm.invoke_props_dialog(self) -# Only needed if you want to add into a dynamic menu + +# Only needed if you want to add into a dynamic menu. def menu_func(self, context): self.layout.operator(DialogOperator.bl_idname, text="Dialog Operator") diff --git a/doc/python_api/examples/bpy.types.Operator.4.py b/doc/python_api/examples/bpy.types.Operator.4.py index 00c9cd250b1..d33f6a6113d 100644 --- a/doc/python_api/examples/bpy.types.Operator.4.py +++ b/doc/python_api/examples/bpy.types.Operator.4.py @@ -41,11 +41,13 @@ class CustomDrawOperator(bpy.types.Operator): col.prop(self, "my_string") -# Only needed if you want to add into a dynamic menu + +# Only needed if you want to add into a dynamic menu. def menu_func(self, context): self.layout.operator(CustomDrawOperator.bl_idname, text="Custom Draw Operator") -# Register and add to the object menu (required to also use F3 search "Custom Draw Operator" for quick access) + +# Register and add to the object menu (required to also use F3 search "Custom Draw Operator" for quick access). bpy.utils.register_class(CustomDrawOperator) bpy.types.VIEW3D_MT_object.append(menu_func) diff --git a/doc/python_api/examples/bpy.types.Operator.5.py b/doc/python_api/examples/bpy.types.Operator.5.py index a0b4a6d6841..90c899f222e 100644 --- a/doc/python_api/examples/bpy.types.Operator.5.py +++ b/doc/python_api/examples/bpy.types.Operator.5.py @@ -55,11 +55,13 @@ class ModalOperator(bpy.types.Operator): context.window_manager.modal_handler_add(self) return {'RUNNING_MODAL'} -# Only needed if you want to add into a dynamic menu + +# Only needed if you want to add into a dynamic menu. def menu_func(self, context): self.layout.operator(ModalOperator.bl_idname, text="Modal Operator") -# Register and add to the object menu (required to also use F3 search "Modal Operator" for quick access) + +# Register and add to the object menu (required to also use F3 search "Modal Operator" for quick access). bpy.utils.register_class(ModalOperator) bpy.types.VIEW3D_MT_object.append(menu_func) diff --git a/doc/python_api/examples/bpy.types.Operator.6.py b/doc/python_api/examples/bpy.types.Operator.6.py index 20ee4c21446..cf556c63ab8 100644 --- a/doc/python_api/examples/bpy.types.Operator.6.py +++ b/doc/python_api/examples/bpy.types.Operator.6.py @@ -31,10 +31,12 @@ class SearchEnumOperator(bpy.types.Operator): context.window_manager.invoke_search_popup(self) return {'RUNNING_MODAL'} -# Only needed if you want to add into a dynamic menu + +# Only needed if you want to add into a dynamic menu. def menu_func(self, context): self.layout.operator(SearchEnumOperator.bl_idname, text="Search Enum Operator") + # Register and add to the object menu (required to also use F3 search "Search Enum Operator" for quick access) bpy.utils.register_class(SearchEnumOperator) bpy.types.VIEW3D_MT_object.append(menu_func) diff --git a/doc/python_api/examples/bpy.types.Operator.py b/doc/python_api/examples/bpy.types.Operator.py index 5299b198774..41b96ac402f 100644 --- a/doc/python_api/examples/bpy.types.Operator.py +++ b/doc/python_api/examples/bpy.types.Operator.py @@ -22,13 +22,15 @@ class HelloWorldOperator(bpy.types.Operator): print("Hello World") return {'FINISHED'} -# Only needed if you want to add into a dynamic menu + +# Only needed if you want to add into a dynamic menu. def menu_func(self, context): self.layout.operator(HelloWorldOperator.bl_idname, text="Hello World Operator") -# Register and add to the view menu (required to also use F3 search "Hello World Operator" for quick access) + +# Register and add to the view menu (required to also use F3 search "Hello World Operator" for quick access). bpy.utils.register_class(HelloWorldOperator) bpy.types.VIEW3D_MT_view.append(menu_func) -# test call to the newly defined operator +# Test call to the newly defined operator. bpy.ops.wm.hello_world() diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index 477d2196666..eba12b75b63 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -409,7 +409,9 @@ BLENDER_VERSION_DOTS = "%d.%d" % (bpy.app.version[0], bpy.app.version[1]) if BLENDER_REVISION != "Unknown": # SHA1 Git hash BLENDER_VERSION_HASH = BLENDER_REVISION - BLENDER_VERSION_HASH_HTML_LINK = "<a href=https://developer.blender.org/rB%s>%s</a>" % (BLENDER_VERSION_HASH, BLENDER_VERSION_HASH) + BLENDER_VERSION_HASH_HTML_LINK = "<a href=https://developer.blender.org/rB%s>%s</a>" % ( + BLENDER_VERSION_HASH, BLENDER_VERSION_HASH, + ) BLENDER_VERSION_DATE = time.strftime("%d/%m/%Y", time.localtime(BLENDER_REVISION_TIMESTAMP)) else: # Fallback: Should not be used @@ -1241,7 +1243,9 @@ def pycontext2sphinx(basepath): try: member_type, is_seq = context_type_map[member] except KeyError: - raise SystemExit("Error: context key %r not found in context_type_map; update %s" % (member, __file__)) from None + raise SystemExit( + "Error: context key %r not found in context_type_map; update %s" % + (member, __file__)) from None fw(" :type: %s :class:`bpy.types.%s`\n\n" % ("sequence of " if is_seq else "", member_type)) i += 1 |