How to create collections?

#1

I am still quite new to Python scripting in Blender. Right now, I am reading through the Quickstart in the API documentation.

In an example, where a custom property is added to a collection, a new collection is created with the following line of code

collection = bpy.data.collections.new("MyTestCollection")

I read in the documentation for collection operators that you can also create a collection with bpy.ops.collection.create.

bpy.ops.collection.create("MyTestCollection")
collection = bpy.data.collections["MyTestCollection"]

However, in both cases, the result is not visible in the outliner. (Is that bad?)

Could anybody please explain whether both ways of creating a collection are equivalent?
If not, in what cases should we use one or another ?

#2

When using api you need to link it to parent collection, via parent.children.link(yourcollection)

When using operator, most likely it adds it to active collection defined by context.

#3

Thanks for the linking to parent explanation!

After running

collection = bpy.data.collections.new("MyTestCollection")
bpy.context.scene.collection.children.link(collection)

or

bpy.ops.collection.create(name  = "MyTestCollection")
bpy.context.scene.collection.children.link(bpy.data.collections["MyTestCollection"])

the collection is created and shown in the outliner.

I still wonder whether these two ways of creating a collection are equivalent ?
If they are not equivalent, which is preferred in what situation ?

#4

In general, operators are UI-oriented. They rely on context and use selected/active stuff and so on.

#5

Oh, I see the difference now.
On a new file (with Blender defaults) bpy.data.collections.new("MyTestCollection") creates an empty collection whereas bpy.ops.collection.create("MyTestCollection") creates a collection that contains the default cube. This is in line with your explanation because when opening a new file, the cube is active/selected.