Context#

Module: plupy · obtained from plupy.context

plupy.context: the scene, selection and area an operation works in. Each run starts empty; use(...) sets them for a block without changing the editor.

class Context

Usage and examples

Members: use · area · scene · graph · selected · active · select

use#

use(area=None, *, scene=_UNSET, selected=_UNSET, active=_UNSET)

Temporarily choose operation context; never change the visible editor state.

Returns a context manager that yields plupy.context. ... denotes an omitted argument here, not an Ellipsis value to pass. Exit restores the enclosing context, including after exceptions. Scopes can nest and may appear inside or outside plupy.edit.

Parameter	Accepted values	Default / effect
`area`	`"scene"`, `"hierarchy"`, `"data"`, `"library"`, `"nodes"`, `None`	`None` inherits current scope; a name starts from that area's Run-time snapshot
`scene`	`Scene` or `None`	Omitted inherits; supplying it clears inherited selection/active/graph, even for the same scene
`selected`	Iterable of uses/scene collections in this scene	Omitted inherits unless `scene=` cleared it; deduplicated in order
`active`	Selected member or `None`	Omitted uses last member; explicit member moves to end; `None` requires an empty selection

Explicit scene/selection overrides work with no area or scene/hierarchy scopes. Supplying only selected keeps the enclosing scene. Explicit targets work headlessly and the scene need not be displayed. Borrowing an editor area requires Code execution in the editor.

Entering/exiting creates no data edit, Undo entry, view change or UI selection change. Deleted selected targets are pruned on reads; active falls back to the last survivor. Wrong areas/types, mixed scenes, stale targets and invalid active membership raise PlupyError before entering.

Explicit context#

Requires scene/use Main / Crate:

import plupy

scene = plupy.data.scenes["Main"]
with plupy.context.use(scene=scene, selected=[scene.objects["Crate"]]):
    plupy.ops.object.move((2, 0, 0))

Captured editor context#

with plupy.context.use("scene"):
    print(plupy.context.active)

Snapshots are captured at Run. Scene and hierarchy share a selection; data, Library and Nodes have independent selections. Data/Library have no scene; Nodes supplies its graph owner rather than a scene. Selected shared-definition nodes are DataBlock handles; edit their values through props.

area#

area -> str | None   # read-only

scene, hierarchy, data, library, nodes.

scene#

scene -> Scene | None   # read-only

Current resolving scene.

graph#

graph -> DataBlock | None   # read-only

Captured Nodes owner.

selected#

selected -> tuple[Handle, ...]   # read-only

Ordered selected targets.

active#

active -> Handle | None   # read-only

Last surviving selected target.

select#

select(items=(), *, active=None) -> None

Replace the displayed scene's UI selection and inspect its active use. items is an iterable of scene uses, deduplicated in order. Default active is the last member; explicit active must belong to items (ValueError otherwise). Empty items clear selection.

Requires editor execution, a context scene that is currently displayed, and no open edit group. It never opens another scene. Wrong context or unavailable UI raises PlupyError. Creates no Undo entry. UI selection remains changed after the scope exits; later scopes in this invocation see this explicit change. An already-open enclosing scope still restores its own saved targets.

Data · DataBlock · Handle · Library · PlupyError · Scene · edit

Source#

_live.py:2015