Module Naming Conventions
The .py extension identifies the saved Python file, while the filename without .py becomes the module name used in an import statement.
One File, Two Roles
A Python program is also a module. The key step is saving Python code in a file whose name ends with the .py extension. Once saved this way, the file can be treated as a module, and its filename supplies the name used when importing it.
The .py extension identifies the saved Python file, while the filename without .py becomes the module name used in an import statement.
What do you think happens?
If a file is named calculator.py, what module name would an import statement use?
Reveal answer
calculator
Python drops the .py extension when the filename becomes the module name used in an import statement.
From Filename to Import Name
The relationship is direct: begin with the complete filename, remove the .py extension, and use what remains as the module name. For example, the file calculator.py supplies the module name calculator. The import statement refers to calculator rather than calculator.py because Python handles the extension automatically.
The import name in this example corresponds to a file named calculator.py. Writing import calculator.py would not follow the filename-to-module-name relationship described here, because the .py extension is omitted in the import statement.
Saving the First Module
Creating mymodule
Create a simple module and identify the name used to import it.
- 1Write Python code
Place a simple Python statement in a file. The source material describes a module containing a single string statement.
- 2Save the file
Save the file with the name
mymodule.py. Saving Python code with the .py extension creates the module file. - 3Remove the extension for importing
The complete filename is
mymodule.py, but the module name is mymodule because the .py extension is dropped in the import statement. - 4Write the import
The corresponding import name is mymodule.
The file mymodule.py becomes the module named mymodule when imported.
The important change is not a special declaration inside the file. Saving the Python code as mymodule.py gives the file its module identity. The filename and the import name are connected by removing only the .py extension.
Where Python Looks
Creating the file is only half of the task. Python must also be able to find it when the importing program requests the module. The module file must be in the same directory as the importing program or in a directory listed in sys.path.
When an import does not work, check the module's location before changing the import name. Confirm that the file is in the same directory as the importing program or in a directory listed in sys.path.
Names That Import Reliably
Module filenames should use valid Python identifiers. In particular, avoid spaces, hyphens, and special characters. These characters can lead to import errors because the filename no longer follows the naming form expected for a module name.
Common mistake Including the .py extension in the import name
What it looks likeThe file is calculator.py, but the import is written as calculator.py.
Why it failsThe module name is the filename without the .py extension.
Do this insteadUse calculator as the module name.
Common mistake Using spaces in a module filename
What it looks likesaving the file as data tools.py
Why it failsModule filenames should use valid Python identifiers, and spaces are not valid in those names.
Do this insteadChoose a filename without spaces.
Common mistake Using a hyphen in a module filename
What it looks likesaving the file as data-tools.py
Why it failsHyphens are not valid in a Python identifier used as a module filename.
Do this insteadChoose a filename without hyphens.
Common mistake Putting the module outside Python's searchable locations
What it looks likeThe importing program requests mymodule, but mymodule.py is neither in the same directory nor in a sys.path directory.
Why it failsPython must find the file in one of those locations before it can import it.
Do this insteadPlace the file in the same directory as the importing program or in a sys.path directory.
Naming and Placement Practice
A learner saves Python code in a file named report_data.py. The importing program is in the same directory. What module name should the import statement use, and which placement requirement is satisfied?
Hints
- Remove the .py extension to find the module name.
- Compare the locations of the two files.
Checking the answer
Determine the import name and placement result for report_data.py.
- 1Find the module name
Remove the .py extension from
report_data.py. The module name isreport_data. - 2Check the location
The importing program and the module are in the same directory, which is one of the locations where Python can find the module.
The import name is report_data, and the same-directory placement satisfies the stated search requirement.
Module Naming Checklist
- 1Every Python program is a module.
- 2Saving Python code with the .py extension creates a module file.
- 3The filename without .py becomes the module name used in an import statement.
- 4The module must be in the same directory as the importing program or in a
sys.pathdirectory. - 5Use valid Python identifiers for module filenames, avoiding spaces, hyphens, and special characters.
Key Takeaways
- A Python program saved as a .py file is a module.
- Python removes the .py extension when deriving the module name for an import statement.
- A module must be located where Python searches, such as the importing program's directory or a
sys.pathdirectory. - Valid Python identifier characters make module filenames safer to import.
- Successful importing depends on both the module's name and its placement.