updating documentation

[jacques_duflos]

Hi there,
I sometimes bump into inconsistencies in the python script documentation (or things that look like so to me, I'm not at all an expert). 

Here is an example : the gimp_image_insert_layer's documentation displayed in the python procedure navigator is :

Quote:This procedure adds the specified layer to the image at the given position. If the specified parent is a valid layer group (See 'gimp-item-is-group' and 'gimp-layer-group-new') then the layer is added inside the group. If the parent is 0, the layer is added inside the main stack, outside of any group. The position argument specifies the location of the layer inside the stack (or the group, if a valid parent was supplied), starting from the top (0) and increasing. If the position is specified as -1 and the parent is specified as 0, then the layer is inserted above the active layer, or inside the group if the active layer is a layer group. The layer type must be compatible with the image base type.

But specifying 0 as parent returns an error

Code:

➤> img=gimp.image_list()[0]
➤> layer = pdb.gimp_layer_new(img, 100, 100, RGB_IMAGE, "layer", 100, 0)
➤> pdb.gimp_image_insert_layer(img, layer, 0, 0)
Traceback (most recent call last):
 File "<input>", line 1, in <module>
TypeError: wrong parameter type
➤>

after struggling a little, I found out that you should use None instead of 0

Code:

➤> img=gimp.image_list()[0]
➤> layer = pdb.gimp_layer_new(img, 100, 100, RGB_IMAGE, "layer", 100, 0)
➤> pdb.gimp_image_insert_layer(img, layer, None, 0)
➤> img.layers
[<gimp.Layer 'layer'>, <gimp.Layer 'Arrière-plan'>]
➤>

From my point of view, the documentation should be modified (correct me if I'm wrong).
It's not a bug as such, but maybe it would be useful to report it through the bug report procedure ?

[Ofnuts]

You can report it... but it has been that way for over 10 years. In practice, all the PDB calls are automatically generated from the script-fu API, so their doc is auto-generated from the script-fu doc. So you learn to make mental adjustments:

• In the PDB browser the function names use the script-fu convention naming scheme with dashes: gimp-context-set-foreground when the Python function takes underscores: gimp_context_set_foreground (because dahses aren't valid in Python identifiers)
  
• Ids (image id, layer id...) are replaced by the object itself.
  
• Consequence of the above, the equivalent of 0 or -1 that denotes "no object" for Gimp is None that says "no object" in Python)
  
• Integers 0/1 used as booleans are replaced by the more Pythonic True/False
  
• When the first position parameter of a call is the run mode ( RUN_INTERACTIVE, etc...), it is replaced by the run_mode keyword argument.
  
• I may be forgetting some more, but when you see them they make sense in light of the above.
  

[jacques_duflos]

ok so it's an already well known issue. It's more like asking for a new feature than reporting a bug. Thanks for the list of correspondence, I only knew about the dash and underscore.

[Rendu]

(08-15-2023, 09:51 PM)jacques_duflos Wrote: ok so it's an already well known issue. It's more like asking for a new feature than reporting a bug. Thanks for the list of correspondence, I only knew about the dash and underscore.

Thank you so much for posting this!! I have been bashing my head against the Python-fu "documentation" since day one! Good to know I am neither stupid nor crazy (Well, that struggling with Python-fu is not evidence of that, at least!).