Understanding Python documentation: how to know what a function returns?

Question

I am having trouble understanding the background assumptions for reading Python documentation.

An example: Documentation for the importlib.import_module function can be found at https://docs.python.org/3/library/importlib.html#importlib.import_module. The function documentation does not specify a return value for the function, but it (maybe obviously) returns the module it has just loaded.

I feel like there are actually a lot of functions for which the return value is not specified. I'm trying to decide which of the following options is closest to the truth.

1. The documentation of this function happens to be incomplete. Don't be so paranoid.
2. Whenever there is no specified return value, the function is assumed to be sufficiently auto-documenting that you can work it out. Just assign a name to the return value: foo = f(bar) and then print(foo).
3. There is a conventional way of knowing what the return value is, and I need to learn the convention.

Case 3 is obviously the one that really worries me!

Any advice would be much appreciated.

Answer 1

The documentation for import_lib.import_module() says what it returns.

The most important difference is that import_module() returns the specified package or module (e.g. pkg.mod), while _ _import__() returns the top-level package or module (e.g. pkg).

Generally speaking: The documentation might be incomplete in places, if it is, do not assume it's a convention you know nothing about.