What are the requirements for naming Python modules?

Question

I've been going through Learn Python The Hard Way. Instead of naming each example ex#.py (where # is the number of the exercise), however, I've just been calling them #.py. This worked fine until I got to Exercise 25, which requires you to import a module you just created through the interpreter. When I try this the following happens:

>>> import 25
  File "<stdin>", line 1
    import 25
            ^

SyntaxError: invalid syntax

I tried renaming the file to ex25.py and it then worked as expected (>>> import ex25). What are the naming requirements for Python modules? I had a look at the official documentation here but didn't see it mention any restrictions.

Answer 1

Modules that you import with the import statement must follow the same naming rules set for variable names (identifiers). Specifically, they must start with either a letter¹ or an underscore and then be composed entirely of letters, digits², and/or underscores.

You may also be interested in what PEP 8, the official style-guide for Python code, has to say about module names:

Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability. Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.

---

_{¹ Letters are the ASCII characters A-Z and a-z.
² Digits are the ASCII characters 0-9.}

Answer 2

Strictly speaking, you can name a Python file anything you want. However, in order to import it using the import statement, the filename needs to be a valid Python identifier --- something you could use as a variable name. That means it must use only alphanumerics and underscores, and not start with a digit. This is because the grammar of the import statement requires the module name to be an identifier.

This is why you didn't see the problem until you got to an exercise that requires importing. You can run a Python script with a numeric name from the command line with python 123.py, but you won't be able to import that module.

Answer 3

The explicit rules for what is allowed to be a valid identifier (variable, module name etc.) can be found here: https://docs.python.org/dev/reference/lexical_analysis.html#identifiers

In your case, this is the relevant sentence:

Within the ASCII range (U+0001..U+007F), the valid characters for identifiers are the same as in Python 2.x: the uppercase and lowercase letters A through Z, the underscore _ and, except for the first character, the digits 0 through 9.