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: The [documentation for
`import_lib.import_module()`](https://docs.python.org/3/library/importlib.html#importlib.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.

