Using ModelBlockDefintion within Python Script?

[ed.p.may]

I wonder if anyone can provide a hint or point me towards the documentation for the ghpythonlib.components.ModelBlockDefinition object? I’m not able to use it properly for some reason, and unsure why? I can figure out how to use the other Model components (Layer, ModelObject,…) but I can’t quite determine what to pass to this definition one?

For example, in the script below:

from ghpythonlib.components import ModelObject, ModelLayer, ModelBlockDefinition

# Try a Layer...
test_layer = ModelLayer(layer="test_layer").layer
print test_layer # >>>   Model Layer : test :)

# Try a ModelObject...
test_obj = ModelObject(object=box,name="test_name", layer=test_layer).object
print test_obj # >>>   Model Brep : test_name :)

# Try a Bock Definition...
test_def = ModelBlockDefinition(
                block_definition=None, #< --- What goes here? 
                objects=test_obj,
                name="test_def"
            ).block_definition
print test_def # >>>   None :(

I can’t figure out what to pass to get it to create the block-definition? It keeps just returning a None?

help(ModelBlockDefinition) just gives me:

   |  ModelBlockDefinition(*args, **kwargs) |      
   |      Block Definition
   |      Input:
   |      	block_definition (in, optional) [Model Block Definition] - Model Block Definition
   |      	objects (in, optional) [Model Object] - Model objects used to define the block.
   |      	name (in, optional) [Text] - The name of the block definition.
   |      Returns:
   |      	block_definition [Model Block Definition] - Model Block Definition
   |      	objects [Model Object] - Model objects used to define the block.
   |      	name [Text] - The name of the block definition.

which seems to indicate that first parameter is Optional? But if I omit it, I get an error:

  Warning: Model Block Definition: input 1 block_definition. warning: Input parameter Block Definition failed to collect data
  Warning: Model Block Definition: solver component. warning: Input parameter Block Definition failed to collect data

Environment:

• MacOS Sequoia 15.6
• Version 8 (8.25.25308.13002, 2025-11-04)

Example File:

• example.gh (12.0 KB)

any advice is much appreciated - thank you!
@ed.p.may