'settings' argument for operators is undocumented in the API #77860

New Issue

Ray Mairlot · 2020-06-14T18:44:27+02:00

Ray Mairlot commented

2020-06-14 18:44:27 +02:00

System Information
Operating system: Windows-10-10.0.18362-SP0 64 Bits
Graphics card: GeForce RTX 2070 SUPER/PCIe/SSE2 NVIDIA Corporation 4.5.0 NVIDIA 442.59

Blender Version
Broken: version: 2.90.0 Alpha, branch: master, commit date: 2020-06-12 13:44, hash: blender/blender@326db1b7cd
Worked: n/a

Short description of error

There doesn't seem to be any API documentation (as far as I am aware) for the settings argument that some operators can be provided with.

For example, the node.add_node operator lists its arguments (in the Python Console) as type="", use_transform=False and settings=- [ ] however, it is never explained (either in Blender or online) how the settings argument works and what it expects.

Through my own digging in the source code I was able to find that it expects a list dictionaries containing a name and value keys e.g.:

  settings=[{"name": "operation", "value": "'SQRT'"}]

This adds the node and changes its operation to 'Square Root' when adding a math node (though again, I had to guess that the SQRT needed an extra set of quotes to get the eval to work correctly).

**System Information** Operating system: Windows-10-10.0.18362-SP0 64 Bits Graphics card: GeForce RTX 2070 SUPER/PCIe/SSE2 NVIDIA Corporation 4.5.0 NVIDIA 442.59 **Blender Version** Broken: version: 2.90.0 Alpha, branch: master, commit date: 2020-06-12 13:44, hash: `blender/blender@326db1b7cd` Worked: n/a **Short description of error** There doesn't seem to be any API documentation (as far as I am aware) for the `settings` argument that some operators can be provided with. For example, the `node.add_node` operator lists its arguments (in the Python Console) as `type=""`, `use_transform=False` and `settings=- [ ]` however, it is never explained (either in Blender or online) how the `settings` argument works and what it expects. Through my own digging in the [source code ](https://developer.blender.org/diffusion/B/browse/master/release/scripts/startup/bl_operators/node.py) I was able to find that it expects a list dictionaries containing a `name` and `value` keys e.g.: ``` settings=[{"name": "operation", "value": "'SQRT'"}] ``` This adds the node and changes its operation to 'Square Root' when adding a math node (though again, I had to guess that the `SQRT` needed an extra set of quotes to get the `eval` to work correctly).

Ray Mairlot commented

2020-06-14 18:44:27 +02:00

Added subscriber: @RayMairlot

Aaron Carlisle commented

2020-06-14 23:12:55 +02:00

Changed status from 'Needs Triage' to: 'Confirmed'

Robert Guetzkow commented

2020-06-14 23:18:59 +02:00

Added subscribers: @Blendify, @rjg

Robert Guetzkow commented

2020-06-14 23:18:59 +02:00

The [Blender API docs ]] aren't ideal in this case. It merely states that it expects a bpy_prop_collection of NodeSettings and has a link that points to the node.py file. The NodeSettings should be documented, but currently aren't, to explain the key value format. The options cannot be documented for add_node directly, because they vary depending on the type argument. Therefore you need to look at the type of node you want to create, in order to find the name of the properties and the allowed values. For instance [ https:*docs.blender.org/api/current/bpy.types.ShaderNodeMath.html | bpy.types.ShaderNodeMath with "operation" and "SQRT". This should also be explained in the description of NodeSettings.

cc @Blendify
Edit: I was too slow ;)

The [Blender API docs ]] aren't ideal in this case. It merely states that it expects a `bpy_prop_collection` of `NodeSettings` and has a link that points to the node.py file. The `NodeSettings` should be documented, but currently aren't, to explain the key value format. The options cannot be documented for `add_node` directly, because they vary depending on the `type` argument. Therefore you need to look at the type of node you want to create, in order to find the name of the properties and the allowed values. For instance [[ https:*docs.blender.org/api/current/bpy.types.ShaderNodeMath.html | bpy.types.ShaderNodeMath ](https:*docs.blender.org/api/current/bpy.ops.node.html#bpy.ops.node.add_node) with `"operation"` and `"SQRT"`. This should also be explained in the description of `NodeSettings`. cc @Blendify Edit: I was too slow ;)

Campbell Barton commented

2020-06-16 05:40:30 +02:00

Added subscriber: @ideasman42

Campbell Barton commented

2020-06-16 05:40:30 +02:00

Note that this operator is only meant to be used from the interface,
if you're adding nodes from Python, you're best off to use tree.nodes.new.

Documentation for this operator should probably mention this.

Note that this operator is only meant to be used from the interface, if you're adding nodes from Python, you're best off to use `tree.nodes.new`. Documentation for this operator should probably mention this.

Aaron Carlisle removed the

Module

Python API

label 2023-02-08 05:03:24 +01:00

Aaron Carlisle added the

Module

Python API

label 2023-08-13 15:30:49 +02:00

Sign in to join this conversation.