Formalize naming conventions for "bpy.app.handlers" / BKE_callbacks #88696

New Issue

Campbell Barton · 2021-05-31T06:52:10+02:00

Campbell Barton commented

2021-05-31 06:52:10 +02:00

This proposal is to formalize names used for handlers.

The only new name being proposed is {action}_post_fail
so script authors can handle both the success and failure state
of an operation.

Motivated by D11422: Python: Add init/cancel app handlers for save/load.

One Off Operations

{action} use in cases multiple handlers are not required, version_update and render_stats for example.

NOTE: in general avoid these if there is some chance the pre/post states would be useful to differentiate.

Regular Operations

{action}_init when the handler can manipulate the context used to run the action.

Examples where `init` functions may be useful are:

When rendering, an render_init function may change the camera or render settings, things which a render_pre function can't support as this information has already been used.
When saving, a save_init could temporarily change preferences related to saving, the same for loading.
{action}_pre
{action}_post
{action}_post_fail if the action can fail.

NOTE: most events only require pre/post handlers.

Background/Modal Operations

{action}_init
{action}_complete when a background job has finished.
{action}_cancel When a background job his canceled partway through.

While cancellation may be caused by any number of reasons, common causes include:

Explicit cancellation by the user.
Exiting Blender
Failure to complete the operation (such as disk-full).

  This could be split into it's own category `{action}_cancel_fail` - however I don't think this is necessary. In that case we might be better off passing the reason for failure to the handler.

This follows render_init, render_cancel & render_complete. This convention could be used in the future for baking or other background tasks.

NOTE: pre/post handlers may be used along side modal-handlers as is the case for rendering, where rendering an animation uses modal handlers, rendering a single frame has pre/post handlers.

This will not incur any breaking changes, it would simply be documented in BKE_callbacks.h and apply to any newly added handlers.

This proposal is to formalize names used for handlers. The only new name being proposed is `{action}_post_fail` so script authors can handle both the success and failure state of an operation. Motivated by [D11422: Python: Add init/cancel app handlers for save/load](https://archive.blender.org/developer/D11422). **One Off Operations** - `{action}` *use in cases multiple handlers are not required, `version_update` and `render_stats` for example.* NOTE: in general avoid these if there is some chance the pre/post states would be useful to differentiate. **Regular Operations** - `{action}_init` *when the handler can manipulate the context used to run the action.* ``` Examples where `init` functions may be useful are: ``` - When rendering, an `render_init` function may change the camera or render settings, things which a `render_pre` function can't support as this information has already been used. - When saving, a `save_init` could temporarily change preferences related to saving, the same for loading. - `{action}_pre` - `{action}_post` - `{action}_post_fail` *if the action can fail.* NOTE: most events only require pre/post handlers. **Background/Modal Operations** - `{action}_init` - `{action}_complete` *when a background job has finished.* - `{action}_cancel` *When a background job his canceled partway through.* ``` While cancellation may be caused by any number of reasons, common causes include: ``` - Explicit cancellation by the user. - Exiting Blender - Failure to complete the operation (such as disk-full). ``` This could be split into it's own category `{action}_cancel_fail` - however I don't think this is necessary. In that case we might be better off passing the reason for failure to the handler. ``` This follows `render_init`, `render_cancel` & `render_complete`. This convention could be used in the future for baking or other background tasks. NOTE: pre/post handlers may be used along side modal-handlers as is the case for rendering, where rendering an animation uses modal handlers, rendering a single frame has pre/post handlers. ---- This will not incur any breaking changes, it would simply be documented in `BKE_callbacks.h` and apply to any newly added handlers.

Campbell Barton commented

2021-05-31 06:52:10 +02:00

Added subscriber: @ideasman42

Campbell Barton changed title from ~~Formalize naming for "bpy.app.handlers" / BKE_callbacks~~ to Formalize naming conventions for "bpy.app.handlers" / BKE_callbacks

2021-05-31 06:58:00 +02:00

Sybren A. Stüvel commented

2021-05-31 10:19:00 +02:00

Added subscriber: @dr.sybren