How to avoid operator `collection_instance_add`?

Question

How to create a instance of a collection from a Python Script/addon without using the collection_instance_add operator?

With the operator I use something like:

bpy.ops.object.collection_instance_add(
    collection=the_name_of_the_collection_to_use,
    align='WORLD',
    location=(0, 0, 0),
    rotation=(0, 0, 0),
)

With this I get no reference to the resulting object, and also don't know how it is named (automatic name wrangling).

Answer 1

Just do all necessary steps

1. Create a new Empty object
2. Set instance_collection to the collection you want
3. Set instance_type to 'COLLECTION'
4. Link the resulting object to the place you want to have it in
   (reference: Basic Object Operations Example)

source_collection = bpy.data.collections["the_name_of_the_collection_to_use"]
instance_obj = bpy.data.objects.new(
    name="my_new__obj_instance_name", 
    object_data=None
)
instance_obj.instance_collection = source_collection
instance_obj.instance_type = 'COLLECTION'
parent_collection = bpy.context.view_layer.active_layer_collection
parent_collection.collection.objects.link(instance_obj)