The rules below come from the Naming Conventions section of PEP 8. PEP 8 also says consistency within a project matters more than consistency with the guide, so an existing codebase with its own style wins.
The PEP 8 naming table
| Identifier | Convention | Example |
|---|---|---|
| Packages | short, all lowercase; underscores discouraged | mypackage |
| Modules | short, all lowercase; underscores allowed if they help | my_module |
| Classes | CapWords | UserAccount |
| Exceptions | CapWords, with an Error suffix if it's an error | ValidationError |
| Type variables | CapWords, short | T, AnyStr, Num |
| Functions | lowercase with underscores | get_user() |
| Variables | lowercase with underscores | user_count |
| Methods | lowercase with underscores | save_changes() |
| Constants | all capitals with underscores, at module level | MAX_OVERFLOW |
Acronyms keep their capitals in CapWords
PEP 8 says to capitalize every letter of an acronym in a CapWords name, so HTTPServerError is better than HttpServerError. In a snake_case name the acronym is just lowercase: http_server_error.
Underscores that change meaning
- One leading underscore (
_cache) marks a name as non-public. It's a convention, andfrom module import *skips these names. - Two leading underscores (
__token) inside a class trigger name mangling: in classFoo,__abecomesFoo._Foo__a, which avoids clashes with subclasses. - One trailing underscore (
class_) avoids a clash with a keyword. PEP 8 prefers it to a misspelling likeclss. - Two underscores on both sides (
__init__) are reserved for Python's own special names. Don't invent new ones.
self, cls and C extension modules
The first argument of an instance method is always self, and the first argument of a class method is always cls. A C or C++ extension module wrapped by a Python module gets a leading underscore, as in _socket.
When mixedCase is allowed
PEP 8 permits mixedCase function names only where that's already the style of the surrounding code, for backward compatibility. The threading module is the usual example. New code should use snake_case.
Converting names with Transform Case
Our snake_case, camelCase, PascalCase and CONSTANT_CASE converters treat an acronym as one word, so HTTP server error becomes HttpServerError and http_server_error. That matches PEP 8 for snake_case and CONSTANT_CASE names. For a class name containing an acronym, put the acronym's capitals back by hand: HttpServerError becomes HTTPServerError.
Naming conventions in other languages: Java, C#, Go (Golang), Rust, Kotlin, Swift, Dart, PHP. All side by side: 20 languages compared.
Sources
- PEP 8, Style Guide for Python Code, Python Software Foundation
Questions
Should Python class names use HTTP or Http?
PEP 8 says to capitalize every letter of an acronym in a CapWords name, so HTTPServerError, not HttpServerError.
Are Python constants enforced?
No. An all-caps name like MAX_SIZE is a convention that tells readers not to reassign it; Python itself doesn't stop you.
Does PEP 8 allow camelCase?
Only where camelCase is already the prevailing style in the code you're working on. New Python code uses snake_case for functions, methods and variables.