def _try_type_conversions(procedure, gen_value, index):
'''
Attempt type conversions and upcast when passing to Gimp procedures.
Conversion: changes Python type of fundamental types, i.e. int to float
Upcast: not change any type, just return superclass type that Gimp wants.
Don't assume any arg does NOT need conversion:
a procedure can declare any arg of type float
'''
# hack: upcast subclass e.g. layer to superclass drawable
# hack that might be removed if Gimp was not wrongly stringent
# TODO optimize, getting type is simpler when is fundamental
# We could retain that the arg is fundamental during unwrapping
MarshalPDB.logger.debug(f"_try_type_conversions: index {index}")
formal_arg_type = procedure.get_formal_argument_type(index)
if formal_arg_type is None:
# Probably too many actual args.
proceed(f"Failed to get formal arg type for index: {index}.")
return
MarshalPDB.logger.debug(
f"_try_type_conversions: index {index} formal type: {formal_arg_type}"
)
gen_value.tryConversionsAndUpcasts(formal_arg_type)
if not gen_value.did_coerce:
MarshalPDB.logger.debug(
f"No type coercion: index {index} formal type: {formal_arg_type}"
)
def _get_property_value(self, name):
""" Get value of property of self.
Catching exceptions with fixup and proceed.
"""
self.logger.debug(f"_get_property_value name: {name}")
try:
# get property of the wrapped Gimp.PropertyConfig
result = self._config.get_property(name)
except TypeError:
"""
Usually property not exist.
Because failed to convey args to Gimp.
Because of current limitations of patches to Gimp.
"GParamBoxed is not handled"
Temporarily:
Most often it the property is type Gimp.RGB for 'color' arg/property,
so patch it.
But also the property type may be Gimp.Image and others, unfixed.
Permanently: return arbitrary GValue so we can proceed.
"""
proceed(f"Fail get property name: {name} from procedure config.")
if name == 'color':
result = FuGenericValue.new_rgb_value()
else:
result = FuGenericValue.new_int_gvalue()
# ensure result is-a GValue
return result
def get_formal_argument_spec(self, index):
'''
Get the formal argument spec for a PDB procedure
for argument with ordinal: index.
Returns an instance of GParamSpec
'''
# not require index is in range (will proceed)
arg_specs = self.argument_specs # some docs say it returns a count
# assert arg_specs is-a list of GParamSpec
## arg_specs = Gimp.ValueArray.new(arg_count)
##config.get_values(arg_specs)
# assert arg_specs is Gimp.ValueArray, sequence describing args of procedure
try:
result = arg_specs[index] # .index(index) ??
# assert is-a GObject.GParamSpec or subclass thereof
## OLD assert arg_spec is GObject.Value, describes arg of procedure (its GType is the arg's type)
except IndexError:
proceed(
"Formal argument not found, probably too many actual args.")
result = None
self.logger.debug(f"get_formal_argument_spec returns: {result}")
# assert result is-a GParamSpec
return result
def try_to_color(formal_arg_type, gen_value):
Upcast._try_to_type(formal_arg_type, gen_value, Gimp.RGB)
if gen_value.did_coerce:
# also convert value
try:
gen_value.to_color()
except Exception as err:
proceed(f"Converting to color: {err}")
def to_file_descriptor(self):
""" try convert self.actual_arg from string to Gio.File """
assert isinstance(self._actual_arg, str)
try:
gfile = Gio.file_new_for_path(self._actual_arg)
except Exception as err:
proceed(f"Failed Gio.file_new_for_path: {self._actual_arg}.")
if gfile is None:
proceed(f"Failed to create GFile for filename: {self._actual_arg}.")
else:
self._result_arg = gfile
self._result_arg_type = Gio.File
self._did_convert = True
def colors_from_list_of_python_type(cls, list):
""" Create a list of Gimp.RGB from a list of string or 3-tuple of ints.
Convenience method on the class.
"""
result = []
try:
for item in list:
color = GimpfuRGB.color_from_python_type(item)
result.append(color)
except:
proceed(f"Failed to convert list element to Gimp.RGB: {item}.")
# assert result is-a list of Gimp.RGB
return result
def to_string_array(cls, actual_arg):
""" Return GValue holding instance of type GStrv created from actual_arg """
# Fail: GStrv is not a GType, only a C typedef.
# Fail: GObject.TYPE_BOXED, cannot initialize GValue with type 'GBoxed', this type has no GTypeValueTable implementation
# Fail: GLib.VariantType
# G_TYPE_STRV
# Setter is not a GIMP method, but a method of GObject.Value
# See GObject>Structures>Value
# Fail: self.to_gimp_array(GObject.TYPE_STRV, GObject.Value.set_boxed )
# Fail: gvalue = FuGenericValueArray.to_gimp_array(actual_arg, GObject.TYPE_STRV, GObject.Value.set_variant )
cls.logger.info(f"to_string_array")
# require a sequence
try:
a_list = FuGenericValueArray.sequence_for_actual_arg(actual_arg)
except Exception as err:
proceed(
f"Exception in sequence_for_actual_arg: _actual_arg: {actual_arg}, {err}"
)
# Create GObject.Value
'''
gvalue = GObject.Value(GObject.TYPE_STRV, a_list)
'''
'''
try:
# create empty (i.e. no value) GValue of desired type,
gvalue = GObject.Value (GObject.TYPE_STRV)
except Exception as err:
proceed(f"Fail to create GObject.Value for array, err is: {err}.")
# GObject.GStrv is not a class?
# Code lifted from PyGObject/tests/test_properties.property
# GStrv inherits Python list type
class GStrv(list):
__gtype__ = GObject.TYPE_STRV
# Create instance from instance of Python list type
gstrv = GStrv(a_list)
# put instance in the gvalue.
gvalue.set_boxed(gstrv)
'''
gvalue = GObject.Value(GObject.TYPE_STRV)
gvalue.set_boxed(a_list)
assert GObject.type_check_value_holds(gvalue, GObject.TYPE_STRV)
return gvalue
def to_color(self):
''' Try convert self.actual_arg to type Gimp.RGB '''
assert self._did_upcast
RGB_result = GimpfuRGB.color_from_python_type(self._actual_arg)
# assert RGB_result is-a Gimp.RGB or None
if not RGB_result:
# formal arg type is Gimp.RGB but could not convert actual_arg
proceed(f"Not convertable to color: {self._actual_arg}.")
self._did_convert = False
else:
self._result_arg = RGB_result
self._result_arg_type = Gimp.RGB
# assert result_type is-a GType
self._did_convert = True
def new_gvalue(gvalue_type, value):
''' Returns GValue'''
# assert gvalue_type is a GObject type constant like GObject.TYPE_STRING
'''
An exception is usually not caused by author, usually GimpFu programming error.
Usually "Must be a GObject.GType, not a type"
'''
try:
result = GObject.Value(gvalue_type, value)
except Exception as err:
proceed(f"Creating GValue for type: {gvalue_type}, value: {value}, err: {err}")
# Return some bogus value so can proceed
result = FuGenericValue.new_int_gvalue()
# TODO would this work??
# result = GObject.Value( GObject.TYPE_NONE, None )
return result
def color_from_python_type(cls, value):
""" Create a Gimp.RGB from a string or 3-tuple of ints.
!!! Not a GimpFuRGB, a Gimp.RGB, i.e. an unwrapped Gimp type
Convenience method on the class.
"""
if isinstance(value, str):
result = GimpfuRGB.create_RGB_from_string(value)
elif isinstance(value, tuple):
result = GimpfuRGB.create_RGB_from_tuple(value)
else:
proceed(f"Illegal Python type: {type(value)} for color: {value}.")
# return an arbitrary color so we can proceed
result = GimpfuRGB.create_RGB_from_string("orange")
return result
def __getattr__(self, name):
'''
Adapts attribute access to become invocation of PDB procedure.
Returns an adapter_func
Override of Python special method.
The more common purpose of such override is to compute the attribute,
or get it from an adaptee.
'''
'''
Require that author previously called main()
which calls Gimp.main() to create PDB and establish GimpFu type is GimpPlugin
'''
if Gimp.get_pdb() is None:
# Severe error in GimpFu code, or did not call main()
# Cannot proceed.
raise Exception("Gimpfu: pdb accessed before calling main()")
else:
# TODO leave some calls unadapted, direct to PDB
# ??? e.g. run_procedure ???, recursion ???
# Map hyphens, and deprecated names.
mangled_proc_name = pdb_name_map[name]
if Gimp.get_pdb().procedure_exists(mangled_proc_name):
self.logger.debug(
f"__getattr__ returns callable _adaptor_func for reference to: {mangled_proc_name}"
)
# remember state for soon-to-come call
self.adapted_proc_name = mangled_proc_name
# return intercept function soon to be called
result = object.__getattribute__(self, "_adaptor_func")
# TODO We could redirect deprecated names to new procedure names
# if they have same signature
# e.g. gimp_image_get_filename => gimp-image-get-file (but not same signature)
# That case should be adapted, since a filename is not a GFile
# elif name = deprecate_pdb_procedure_name_map()
else:
# Can proceed if we catch the forthcoming call
# by returning a do_nothing_intercept_func
proceed(f"unknown pdb procedure {mangled_proc_name}")
result = object.__getattribute__(self, "_nothing_adaptor_func")
return result
def _try_to_type(formal_arg_type, gen_value, cast_to_type):
'''
When gen_value.actual_arg_type is subclass of cast_to_type
and procedure has signature expecting cast_to_type,
return cast_to_type, else return original type.
Does not actually change type i.e. no conversion, just casting.
Require gen_value a GObject (not wrapped).
Require formal_arg_type is-a GType.
'''
# assert type is like Gimp.Drawable, cast_to_type has name like Drawable
Upcast.logger.info(
f"Attempt upcast: {gen_value.actual_arg_type} to : {cast_to_type.__name__}"
)
from gimpfu.adaption.types import Types
if Types._should_upcast_or_convert(gen_value.actual_arg_type,
formal_arg_type, cast_to_type):
if is_subclass_of_type(gen_value.actual_arg, cast_to_type):
gen_value.upcast(cast_to_type)
elif gen_value.actual_arg == -1:
# v2 allowed -1 as arg for optional drawables
# # !!! convert arg given by Author
gen_value.upcast_to_None(cast_to_type)
elif gen_value.actual_arg is None:
# TODO migrate to create_nonetype_drawable or create_none_for_type(type)
# Gimp wants GValue( Gimp.Drawable, None), apparently
# This does not work: result = -1
# But we can upcast NoneType, None is in every type???
gen_value.upcast(cast_to_type)
else:
# Note case Drawable == Drawable will get here, but Author cannot create instance of Drawable.
proceed(
f"Require type: {formal_arg_type} , but got {gen_value} not castable."
)
else:
# No upcast was done
pass
# assert result_type is-a type (a Gimp type, a GObject type)
Upcast.logger.info(f"_try_to_type returns FuGenericValue: {gen_value}")
def _sanity_test_registration(self):
''' Quit when detect exceptional results or params. '''
self.params.sanity_test(self) # pass self for callback
for ent in self.RESULTS:
# ent is tuple
# TODO a class
if len(ent) < 3:
# TODO proceed
raise Exception(
("result definition must contain at least 3 elements "
"(%s given: %s)" % (len(ent), ent)))
if not isinstance(ent[0], int):
raise Exception("result must be of integral type")
if not self.letterCheck(ent[1], self.param_name_allowed):
# not fatal unless we use it?
proceed(f"result name '{ent[1]}' contains illegal characters")
def convert_gimpvaluearray_to_list_of_gvalue(array):
''' Convert from type *GimpValueArray*, to *list of GValue*. '''
list_of_gvalue = []
len = array.length() # !!! not len()
Types.logger.info(
f"convert_gimpvaluearray_to_list_of_gvalue length: {len}")
for i in range(len):
try:
gvalue = array.index(i)
except:
from gimpfu.adaption.generic_value import FuGenericValue
# Probably a bug in Gimp
proceed(f"Fail GimpValueArray.index() at index: {i}.")
# Fixup with some arbitrary GValue
gvalue = FuGenericValue.new_int_gvalue()
# Not convert elements from GValue to Python types
list_of_gvalue.append(gvalue)
# ensure is list of elements of type GValue, possibly empty
return list_of_gvalue
def sanity_test(self, metadata):
unique_names = []
"""
# TODO: this doesn't work because GimpFu allows user to declare or not declare args that Gimp always passes.
# since we are using the names to convey properties to Gimp,
# disallow names already used by Gimp for properties
unique_names.append("image")
unique_names.append("drawable")
"""
for param in self.PARAMS:
"""
TODO
if len(ent) < 4:
raise Exception( ("parameter definition must contain at least 4 "
"elements (%s given: %s)" % (len(ent), ent)) )
"""
if not isinstance(param.PF_TYPE, int):
# TODO check in range
exception_str = f"Plugin parameter type {param.PF_TYPE} not a valid PF_ enum"
raise Exception(exception_str)
# Fixup common mistake is a space in the LABEL
param.LABEL = param.LABEL.replace( ' ' , '_')
if not metadata.letterCheck(param.LABEL, metadata.param_name_allowed):
# Not fatal since we don't use it, args are a sequence, not by keyword
# But Gimp may yet complain.
# TODO transliterate space to underbar
proceed(f"parameter name '{param.LABEL}' contains illegal characters")
# Check for unique names. To convey to Gimp, must be unique.
# Names do NOT need to match the formal params of the run_func
if param.LABEL in unique_names:
proceed(f"parameter name '{param.LABEL}' is not unique")
else:
unique_names.append(param.LABEL)
def __init__(self,
r=None,
g=None,
b=None,
name=None,
a_tuple=None,
adaptee=None):
'''
!!! In call to constructor, you must use a keyword
assert (
(r is not None and g is not None and b is not None) # and are numbers
or (name is not None) # and is str from a certain subset
or (a_tuple is not None) # and is a 3-tuple or sequence of number
or (adaptee is not None) # and is-a RGB
)
'''
try:
if r is not None:
# Totally new adaptee, created at behest of author or GimpFu implementation
# Gimp constructor NOT named "new"
a_adaptee = Gimp.RGB()
a_adaptee.set(float(r), float(g), float(b))
elif name is not None:
a_adaptee = GimpfuRGB.create_RGB_from_string(name)
elif a_tuple is not None:
a_adaptee = GimpfuRGB.create_RGB_from_tuple(a_tuple)
elif adaptee is not None:
# Create wrapper for existing adaptee (from Gimp)
# Adaptee was created earlier at behest of Gimp user and is being passed into GimpFu plugin
a_adaptee = adaptee
else:
raise RuntimeError("Illegal call to GimpfuRGB constructor")
except Exception as err:
proceed(f"Creating GimpfuRGB: {err}")
# Adapter
super().__init__(a_adaptee)
def _adaptor_func(self, *args, **kwargs):
"""
Run a PDB procedure whose name was used like "pdb.name()" e.g. like a method call of pdb object.
Crux: wrap a call to PDB.run_procedure()
Wrapping requires marshalling args from Python types to GObject types.
Wrapping also requires inserting run_mode arg (GimpFu hides that from Authors.)
Args are from Author. That is, they are external (like i/o, beyond our control).
Thus we catch exceptions (and check for other errors) and proceed.
"""
self.logger.debug(f"_adaptor_func called, args: {args}")
if kwargs:
proceed(f"PDB procedures do not take keyword args.")
# !!! avoid infinite recursion
proc_name = object.__getattribute__(self, "adapted_proc_name")
# !!! Must unpack args before passing to _marshall_args
try:
marshaled_args = MarshalPDB.marshal_args(proc_name, *args)
except Exception as err: # TODO catch only MarshalError ???
proceed(f"marshalling args to pdb.{proc_name} {err}")
marshaled_args = None
if marshaled_args is not None:
# marshaled_args is-a list of GValues, but it could be an empty list.
# PyGObject will marshall the list into a GimpValueArray
"""
This is almost always a segfaulted callee plugin,
a separate process that crashed and is failing to respond to IPC.
We assert and don't try/except/proceed because the error is
serious and external to Author's plugin.
"""
inner_result = Gimp.get_pdb().run_procedure(
proc_name, marshaled_args)
assert inner_result is not None, f"PDB procedure {proc_name} failed to return value array."
# The first element of result is the PDB status
self.logger.debug(
f"run_procedure {proc_name}, result is: {inner_result.index(0)}"
)
# pdb is stateful for errors, i.e. gets error from last invoke, and resets on next invoke
error_str = Gimp.get_pdb().get_last_error()
if error_str != 'success': # ??? GIMP_PDB_SUCCESS
"""
Log the args because it is a common failure: wrong args.
We might also log what Author gave (args) before we marshalled them.
TODO i.e. { {*args} } ?, but that leaves braces in the output
TODO { {*args} } throws "unhashable type GimpfuImage"
"""
self.logger.warning(f"Args: {marshaled_args}")
proceed(f"PDB call fail: {proc_name} Gimp says: {error_str}")
result = None
else:
result = MarshalPDB.unmarshal_results(inner_result)
else:
result = None
# This is the simplified view of what we just did, without all the error checks
# object.__getattribute__(self, "_marshall_args")(proc_name, *args)
# Most PDB calls have side_effects on image, but few return values?
# ensure result is defined and (is-a list OR None)
# TODO throws for GBoxed, so log the types and not the values
self.logger.debug(f"_adaptor_func for: {proc_name} returns: {result}")
return result
def to_gimp_array(cls,
actual_arg,
to_container_gtype,
gvalue_setter,
is_setter_take_contained_type=False):
"""
Return GValue holding a Gimp<foo>Array
where <foo> is determined by to_container_gtype,
and contents are from actual_arg.
actual_arg can be a single item *or* Python native sequences.
GimpFu allows Author to pass an item where
the called PDB procedure expects an array.
Contain item in a list and then to to_container_gtype.
gvalue_setter is a method of Gimp e.g. Gimp.value_set_object_array.
One setter (Gimp.value_set_object_array) has extra arg: contained_gtype.
"""
cls.logger.info(f"to_gimp_array type: {to_container_gtype}")
#logger.info(f"to_gimp_array type of type: {type(to_container_gtype)}")
# prints: <class 'gobject.GType'>
#print(dir(to_container_gtype))
#print(dir(GObject.GType))
#foo =GObject.GType.from_name("GimpObjectArray")
#logger.info(f"to_gimp_array type of type: {type(foo)}")
# require a list to create an array
try:
list = FuGenericValueArray.sequence_for_actual_arg(actual_arg)
except Exception as err:
proceed(
f"Exception in sequence_for_actual_arg: _actual_arg: {actual_arg}, {err}"
)
# setter i.e. factory method needs gtype of contained items.
# hack
# use any GIMP boxed type, setter doesn't actually use it???
# TEMP This works but is not general
# it works only when testing GimpObjectArray
contained_gtype = Gimp.Item.__gtype__
# Create GObject.Value of the given to_container_gtype
try:
# create empty (i.e. no value) GValue of desired type,
gvalue = GObject.Value(to_container_gtype)
except Exception as err:
proceed(f"Fail to create GObject.Value for array, err is: {err}.")
"""
assert list is-a list, but is empty, or items are wrapped or fundamental types
But we don't know much about the contained items.
(They were passed as arguments by Author.)
Could be:
GimpFu wrapped GObjects
??? unwrapped GObjects (responds to .__gtype__)
fundamental types
"""
list = FuGenericValueArray.martial_list_to_bindable_types(
list, to_container_gtype)
try:
"""
Invoke setter to set value into GValue.
Invoking via GI i.e. gvalue_setter is-a callable.
For Gimp array types, setter is a method on Gimp.
For other array types, setter is ???
We are calling e.g. Gimp.value_set_object_array()
whose C signature is like (...len, array...)
PyGObject will convert "list" to "len(list), array"
Fail: Gimp.value_set_object_array(gvalue, len(list), list)
Elsewhere, the length is also passed to a PDB procedure
since the PDB API is C-like, not Python-like.
"""
# Some arrays want to know the contained type.
if is_setter_take_contained_type:
# Fail GObject.Type.ensure(GimpObjectArray)
# Fail GObject.GType.is_a(Gimp.ObjectArray)
cls.logger.debug(
f"Setting array of type: {to_container_gtype.name}, contained_gtype: {contained_gtype}"
)
# !!! Must pass a __gtype__, not a Python type
# assert contained_gtype is-a GObject.GType
assert isinstance(contained_gtype, GObject.GType)
gvalue_setter(gvalue, contained_gtype, list)
#foo = _gvalue.get_boxed() # Gvalue should hold a boxed type
#print(foo.__gtype__ )
else:
cls.logger.debug(
f"Setting array of type: {to_container_gtype.name}")
gvalue_setter(gvalue, list)
except Exception as err:
proceed(f"Fail to_gimp_array: {to_container_gtype.name}: {err}.")
return gvalue
def marshal_args(proc_name, *args):
'''
Marshal args to a PDB procedure.
Accepts: sequence of wrapped or primitive args
Returns: sequence of GValue
(We are returning a sequence, not a GValueArray.
If it were a GValueArray, we would use: result.insert(index, gvalue) )
Optionally synthesize (prefix result) with run mode
GimpFu feature: hide run_mode from calling author
For each arg:
- Unwrap wrapped arguments so result is GObjects (not a GimpFu object)
- Upcasts and conversions
- check for error "passing func" FunctionInfo
'''
result = []
formal_args_index = 0
# Called procedure knows its formal parameters
procedure = GimpPDB.get_procedure_by_name(proc_name)
"""
Check count of formal versus actual args.
GimpFu allows count actual args to be less by one,
if the procedure takes runmode, and then we insert it.
But some callers may have passed runmode
(did not use the GimpFu shortcut.)
"""
if (len(args) == procedure.formal_arg_count - 1
and procedure.takes_runmode_arg):
"""
Assume the case that run mode is in the formal args, not in passed actual args.
Synthesizing runmode might now work, the caller might have made an error
and not just using the GimpFu convention of not passing runmode.
"""
result.append(MarshalPDB.synthesize_marshalled_run_mode())
# skip to the next formal arg
formal_args_index = 1
elif len(args) != procedure.formal_arg_count:
'''
If more actual args than formal_args we can't know the formal type of the excess actual args.
If less actual args than formal_args, we could convert the given args,
but Gimp would return an error when we call the PDB procedure with too few args.
'''
proceed(
f"Mismatched count of formal versus actual args for {proc_name}"
)
for x in args:
MarshalPDB.logger.debug(
f"marshalling arg value: {x} index: {formal_args_index}")
# to dump more uncomment this
# MarshalPDB.logger.debug(f"cumulative marshalled args: {result}" )
go_arg, go_arg_type = MarshalPDB._unwrap_to_param(x)
# assert are GObject types, i.e. fundamental or Boxed
# We may yet convert some fundamental types (tuples) to Boxed (Gimp.RGB)
gen_value = FuGenericValue(go_arg, go_arg_type)
# One of the main capabilities of GimpFu: accept loose, Pythonic code and do convenient upcasts/conversions
try:
MarshalPDB._try_type_conversions(procedure, gen_value,
formal_args_index)
except Exception as err:
proceed(
f"Exception in _try_type_conversions: {gen_value}, formal_args_index: {formal_args_index}, {err}"
)
if is_wrapped_function(go_arg):
proceed("Passing function as argument to PDB.")
a_gvalue = gen_value.get_gvalue()
result.append(a_gvalue)
formal_args_index += 1
MarshalPDB.logger.debug(f"marshal_args returns: {result}")
"""
result sequence could be empty (normal)
or may be short or long, since we may have proceeded past an error.
"""
return result
def copy(self):
proceed("Cannot copy Display")
return None