309

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?

Improve this question
1
  • 5
    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.
    – michael
    Commented Sep 19, 2018 at 21:24

2 Answers 2

Reset to default
322

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.

Improve this answer
9
  • 7
    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?
    – darkace
    Commented Feb 1, 2016 at 17:13
  • 6
    Yes, you can have 0, 1, or more classes in a module.
    – agold
    Commented Feb 1, 2016 at 17:14
  • 3
    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.
    – Bas Jansen
    Commented Aug 16, 2018 at 14:42
  • 2
    @pypmannetjies this is actually another question, but I'd say that you should prefer long understandable names over short not understandable ones.
    – agold
    Commented Apr 30, 2019 at 12:50
  • 2
    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?)
    – Juh_
    Commented May 6, 2019 at 9:06
90

Here is a link for different types of Python name conventions.

The style guide for Python is based on Guido’s naming convention recommendations.

enter image description here

Improve this answer
4
  • 42
    This answer crucially misses the filename part of the question.
    – Grant Birchmeier
    Commented Aug 24, 2021 at 20:43
  • 7
    Yes and no. A module is usually a file. (Not my favourite part of Python.)
    – MEMark
    Commented Feb 1, 2022 at 14:10
  • 2
    well since there is no clear distinction between the two, i would keep filenames to my-test-script.py for readability. my_test_script.py looks good but might have all sorted of weird contradictions with PEP?
    – mirageglobe
    Commented Aug 21, 2022 at 14:43
  • 3
    @mirageglobe importing modules from my-test-script.py wouldn't be as straight forward as my_test_script.py, I guess.
    – helloworld
    Commented Oct 17, 2023 at 13:08

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.