This guide explains module naming mistakes that shadow standard modules through a focused Python example. You will learn the behavior to expect, why it matters in a real program, and how to recognize the common mistakes before applying it in your own project.
What You Will Learn
Naming a source file after a standard module such as json.py, math.py or typing.py can cause Python to import the wrong file. The symptom may be missing attributes or confusing circular import messages.
When and Why to Use It
The following example focuses on a practical use of Module Naming Mistakes That Shadow Standard Modules.
Step-by-Step Example
from pathlib import Path
risky_filenames = {"json.py", "typing.py", "math.py", "random.py"}
project_filenames = {"main.py", "json.py", "helpers.py"}
print(sorted(risky_filenames & project_filenames))Understanding the Example
json.py is reported as a collision risk. Rename the local script and remove stale cache files if necessary before rerunning.
Expected Output
['json.py']Important Behavior and Edge Cases
Deleting a __pycache__ directory without fixing the filename cannot resolve the underlying naming conflict.
Try It Yourself
Inspect a practice project for filenames matching standard-library modules.
Run environment-management commands in your terminal, not in a Python source file. Use the executable associated with the selected project interpreter and verify the environment before installing dependencies.
Common Beginner Mistakes
- Deleting a __pycache__ directory without fixing the filename cannot resolve the underlying naming conflict.
- Running installation commands against a different Python interpreter than the one used for the project.
- Skipping the practice step and assuming the example covers every input. Test at least one normal case and one edge case relevant to this topic.
Key Takeaways
- Naming a source file after a standard module such as json.py, math.py or typing.py can cause Python to import the wrong file.
- json.py is reported as a collision risk.
- Apply the technique deliberately, checking its documented input requirements and failure behavior before integrating it into a larger project.