Python file naming convention?

  • I've seen this part of PEP-8 https://www.python.org/dev/peps/pep-0008/#package-and-module-names

    I'm not clear on whether this refers to the file name of a module/class/package.

    If I had one example of each, should the filenames be all lower case with underscores if appropriate? Or something else?

    tl;dr: two classes `FooBar` and `FooBiz` might both go in file `somepkg/foobar.py` (thus: `from somepkg.foobar import FooBar`) but class `TimerError` could go in `except/timer_error.py` (thus `from except.timer_error import TimerError`), since removing the `CamelCase` sometimes makes the word harder to read, thus `snake_case` may be used for the filename.

  • agold

    agold Correct answer

    5 years ago

    Quoting https://www.python.org/dev/peps/pep-0008/#package-and-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.

    For classes:

    Class names should normally use the CapWords convention.

    And function and (local) variable names should be:

    lowercase, with words separated by underscores as necessary to improve readability

    See this answer for the difference between a module, class and package:

    • A Python module is simply a Python source file, which can expose classes, functions and global variables.
    • A Python package is simply a directory of Python module(s).

    So PEP 8 tells you that:

    • modules (filenames) should have short, all-lowercase names, and they can contain underscores;
    • packages (directories) should have short, all-lowercase names, preferably without underscores;
    • classes should use the CapWords convention.

    PEP 8 tells that names should be short; this answer gives a good overview of what to take into account when creating variable names, which also apply to other names (for classes, packages, etc.):

    • variable names are not full descriptors;
    • put details in comments;
    • too specific name might mean too specific code;
    • keep short scopes for quick lookup;
    • spend time thinking about readability.

    To finish, a good overview of the naming conventions is given in the Google Python Style Guide.

    And I'll embarrassedly ask to confirm my understanding, modules contain classes - so you would use classes within modules and could have multiple classes in one module?

    Yes, you can have 0, 1, or more classes in a module.

    I am glad I found this in time before my project grew out of hand, as all my packages were following the CapsWords convention just like my classes.

    Example from a comment above: two classes `FooBar` and `FooBiz` might both go in file `somepkg/foobar.py` (thus: `from somepkg.foobar import FooBar`). Java devs: note the distinction in filename convention.

    Once in a while, I come across the situation where you can't give a package name that is short enough without losing the meaning. If you can't separate words in a package name with underscores, then how should you go about it?

    @pypmannetjies this is actually another question, but I'd say that you should prefer long understandable names over short not understandable ones.

    For package name, it says "the use of underscores is discouraged", not forbidden. In python philosophy, you should follow the rule, "although practicality beats purity". Of course, the best is to find a way to follow the rule *and* be practical (maybe make several packages to split the name, `some` > `long` > `name` instead of `somelongname`?)

License under CC-BY-SA with attribution


Content dated before 6/26/2020 9:53 AM