Converting the API doc to Python

[Ofnuts]

A little bit of C.

In C you have two kinds of data types.

• The "native" ones: int and floats of various lengths, and pointers (memory addresses)
  
• The "complex" ones (anything else, "structs" or arrays)
  

When you call a function:

• native types are passed "by value": their value is copied in the call stack
  
• complex types are passed "by reference": a pointer to them is copied in the calls stack. The fact that this is a pointer is indicated by *
  
• the function can only "return" a single native type
  
• the function can also update memory locations to which a pointer has been passed, this is how extra return values can be used
  

For instance with this "C" prototype from the Gimp.Drawable description:

Code:

gboolean
gimp_drawable_get_offsets (
 GimpDrawable* drawable,
 gint* offset_x,
 gint* offset_y
)

Where GimpDrawable is a "complex" type, and gboolean and gint are "native" type (just  names for machine-size integers).

* the function returns a boolean
* the first argument is a pointer/reference to GimpDrawable. Since GimpDrawable is a complex type it is a simple "input" argument.
* offset_x and offset_y are references to native types, and so are outputs to the function. In Python your inputs are immutable, so this is converted to extra return values, and the method returns a tuple.

So this would be called as:

boolean_success, offset_x,offset_y= get_offsets(layer: Gimp.Drawable)

But since the first argument is of the type described, in Python this method call on a  Gimp.Drawable object, so it is passed implicitly when calling the method.

boolean_success, offset_x,offset_y= layer.get_offsets()

The returned boolean here is a bit artificial. This is probably because the method has to use output arguments to return X and Y, so this is the only way to check that the memory locations passed for the offsets have been updated. This can still be ignored in the vast majority of cases by writing:

_, offset_x,offset_y= layer.get_offsets()

where _ is the Python convention to indicate that you don't really care about this value.

Slightly harder:

Code:

GimpLayer*
gimp_image_get_layer_by_name (
 GimpImage* image,
 const gchar* name
)

• The function takes a reference to a GimpImage, so in this case this is the implicit reference to the object on which the method is called.
  
• The function takes a reference to gchar. This isn't an output for a single char, this is a reference to an array of characterss (arrays and pointer are equivalent in C, an array is defined by the address of its first element). And an array of gchar is... a string. What also indicates that this is an input-only argument is the const modifier.
  
• The call returns a pointer to a GimpLayer, so in Python, a plain Gimp.Layer
   
  

So this defines a Gimp.Image method that would be type-hinted as:

def get_layer_by_name(name: str) -> Gimp.Layer

Raising the bar:

Code:

GimpLayer **
gimp_image_get_selected_layers (
 GimpImage* image
)

Here the call return a pointer to a pointer to GimpLayer... this is really a pointer to an array of GimpLayer, so for Python just a list of Gimp.Layer. So this is just:

def get_selected_layers() -> list[Gimp.Layer]

Gotcha:

Note that some calls are defined as functions and not as object methods. For instance:

Code:

gboolean
gimp_file_save (
 GimpRunMode run_mode,
 GimpImage* image,
 GFile* file,
 GimpExportOptions* options
)

This is a plain function in the Gimp namespace that takes 4 explicit arguments.