Organizing Code with Packages
Every Python program is a module; creating a module requires only saving a file with the .py extension.
From Program to Module
A Python program can be more than a file that runs on its own. Every Python program is also a module, which means its code can be organized in a file and made available for importing. The basic act of creating a module is simple: save Python code in a file whose name ends with .py.
Think of a module as Python code packaged in one source file. The file gives the code a name and provides a unit that another Python program can import. The module idea therefore connects two activities: saving code in a .py file and referring to that file by its module name in an import statement.
Naming the Module
The filename determines the module name used in an import statement. Python removes the .py extension when the file is referred to as a module. For example, a file named helpers.py has the module name helpers, so the import statement uses helpers rather than helpers.py.
Deriving an Import Name
A Python file is saved as mymodule.py. What module name should an importing program use?
Start with the filename: The saved file is named mymodule.py.
Remove the extension: The .py extension is dropped when the file is used in an import statement.
Write the module name: The resulting module name is mymodule.
The importing program uses mymodule as the module name, not mymodule.py.
Saving a First Module
To create the simple module described in the lesson, save Python code in a file named mymodule.py. The saved file is now a module. Its module name is mymodule because Python handles the removal of the .py extension when the file is imported.
The important change is not a special conversion command. The file becomes a module when Python code is saved with the .py extension. The filename supplies the name that another program will use when it imports the module.
What do you think happens?
A file is named mymodule.py. Which name represents the module when it is imported?
Reveal answer
Answer: mymodule
The .py extension belongs to the filename. Python drops that extension when forming the module name used in an import statement.
Making the File Findable
Creating the module file is only half of the task. Python must also be able to find that file. A module must be in the same directory as the program that imports it, or in a directory listed in sys.path. If the file is placed outside those locations, Python cannot find it through the import.
Checking Module Placement
An importing program needs a module named helpers. The file is helpers.py. Where can the file be placed so Python can find it?
Check the filename: helpers.py supplies the module name helpers.
Check the importing program's directory: The file can be placed in the same directory as the program that imports it.
Check sys.path: The file can instead be placed in a directory listed in sys.path.
Reject an unlisted location: A location that is neither the same directory nor a sys.path directory is not one of the specified places Python searches for the module.
Place helpers.py beside the importing program or in a directory listed in sys.path.
Choosing Safe Filenames
A module filename should be a valid Python identifier apart from its .py extension. In practice, avoid spaces, hyphens, and other special characters in module filenames. Names that do not follow these rules can cause import errors.
| Filename characteristic | Importing consequence |
|---|---|
| Valid Python identifier | Suitable as a module filename |
| Contains spaces | Can cause import errors |
| Contains hyphens | Can cause import errors |
| Contains other special characters | Can cause import errors |
Module filenames should follow valid Python identifier rules.
Mistakes That Block Imports
Writing the .py extension in the module name used for an import
Python drops the .py extension when forming the module name used in an import statement.
Fix:
Use the filename without .py as the module name.Placing the module where Python does not search
Python must find the file in the same directory as the importing program or in a sys.path directory.
Fix:
Move the module into the importing program's directory or into a directory listed in sys.path.Using spaces, hyphens, or special characters in the module filename
Such filenames can cause import errors.
Fix:
Use a filename that follows valid Python identifier rules.
Module Setup Practice
A file named report_tools.py is intended to be imported by a Python program. State the module name formed from the filename, identify two locations where the file can be placed for Python to find it, and name two filename features that should be avoided.
Hints
- Remove the .py extension to determine the module name.
- Use the two module-search locations described in this article.
- Check whether the filename contains spaces, hyphens, or other special characters.
- Every Python program is also a module.
- Saving Python code in a .py file creates a module.
- The module name is the filename without the .py extension.
- Python can find a module in the importing program's directory or in a directory listed in sys.path.
- Module filenames should use valid Python identifiers and avoid spaces, hyphens, and special characters.
Key Takeaways
- A Python source file saved with the .py extension is a module.
- Python forms the module name by removing .py from the filename.
- The module file must be in the same directory as the importing program or in a sys.path directory.
- Valid Python identifiers are the safest module filenames; spaces, hyphens, and special characters can cause import errors.
- Successful importing depends on both the module's name and its location.