Recommended name for top level module in Python project?

Question

I am developing a program that I plan to distribute to multiple users. This consists of a folder containing the following files:

• convert_units.py
• fit_parameters.py
• plot_results.py
• top_level_module.py

The purpose of "top_level_module.py" is to import the other modules and call them as needed, as shown below:

from convert_units import convert_units
from fit_parameters import fit_parameters
from plot_results import plot_results

input_data = "somefile.csv"
intermediate_result = convert_units(input_data)
final_result = fit_parameters(intermediate_result)
plot_results(final_result)

The goal of naming the above file "top_level_module" is to help users who wish to inspect the code. Specifically, my hope is that when users see this filename they will immediately realise that this is the highest level module, and hence the correct file to read first. However, the name "top_level_module" seems verbose, and I am wondering if another name is already in common use for this purpose.

So my question is: Does anyone know if there is a convention for naming the top level module? Or if any other name would be more widely intuitive?

Answer 1

One way that is used often, is to have a folder named after your module with the submoduls (convert_units.py etc.) as files in that folder and an __init__.py-file where you put your code from the main-module instead of in a separate top_level_module.py-file.

Your submoduls can even have their own submoduls and so on for bigger projects. For this you'd have e.g. instead of the convert_units.py-file a convert_units-folder again containing an __init__.py-file with the module-level code and other files or folders for the submoduls of this submodule convert_units.

Your file-structure could in the end look something like this.

my_fancy_library  # name folder after what you want to call your module
├── __init__.py  # module-level code goes here (<- top_level_module.py)
├── fit_parameters.py  # smaller submodul that fits inside one file
├── plot_results.py
├── convert_units  # bigger submodul with own submodules
│   ├── __init__.py  # module-level code of submodule
│   ├── validator.py
│   ├── custom_exceptions.py
...

Your __init__.py-file of your main-module then can look like this to implement your example:

from .convert_units import convert_units
from .fit_parameters import fit_parameters
from .plot_results import plot_results


def fit_data_and_plot(input_data):
    intermediate_result = convert_units(input_data)
    final_result = fit_parameters(intermediate_result)
    plot_results(final_result)

Better to wrap your code inside a function, or otherwise it will be executed during the import. You then use this function in another module by importing it from my_fancy_library import fit_data_and_plot and calling it with the input-path fit_data_and_plot(input_data).

You can also look at the source-code of other libraries too, to get an idea. This can be really confusing for bigger libraries like numpy, so I would start with a smaller example like dateutil.