What is the underscore prefix for python file name?

Question

In cherryPy for example, there are files like:

• __init__.py
• _cptools.py

How are they different? What does this mean?

Deucalion

Answer 1

__...__ means reserved Python name (both in filenames and in other names). You shouldn't invent your own names using the double-underscore notation; and if you use existing, they have special functionality.

In this particular example, __init__.py defines the 'main' unit for a package; it also causes Python to treat the specific directory as a package. It is the unit that will be used when you call import cherryPy (and cherryPy is a directory). This is briefly explained in the Modules tutorial.

Another example is the __eq__ method which provides equality comparison for a class. You are allowed to call those methods directly (and you use them implicitly when you use the == operator, for example); however, newer Python versions may define more such methods and thus you shouldn't invent your own __-names because they might then collide. You can find quite a detailed list of such methods in Data model docs.

_... is often used as 'internal' name. For example, modules starting with _ shouldn't be used directly; similarly, methods with _ are supposedly-private and so on. It's just a convention but you should respect it.

Quiescent

You are not expressly forbidden from inventing your own names. It is discouraged because the language might add more such names in the future, so the namespace is reserved. Using __...__ names for your own projects is at your own risk. – Flashover

@MartijnPieters: ok, replaced that with 'shouldn't'. – Albi

Answer 2

These, and other, naming conventions are described in detail in Style Guide for Python Code - Descriptive: Naming Styles

Briefly:

• __double_leading_and_trailing_underscore__: "magic" objects or attributes that live in user-controlled namespaces. E.g.__init__, __import__ or __file__. Never invent such names; only use them as documented.
• _single_leading_underscore: weak "internal use" indicator. E.g. from M import * does not import objects whose name starts with an underscore.

Elodea

Answer 3

__init__.py is a special file that, when existing in a folder turns that folder into module. Upon importing the module, __init__.py gets executed. The other one is just a naming convention but I would guess this would say that you shouldn't import that file directly.

Take a look here: 6.4. Packages for an explanation of how to create modules.

General rule: If anything in Python is namend __anything__ then it is something special and you should read about it before using it (e.g. magic functions).

Yseulta

Answer 4

The current chosen answer already gave good explanation on the double-underscore notation for __init__.py.

And I believe there is no real need for _cptools.py notation in a filename. It is presumably an unnecessary extended usage of applying the "single leading underscore" rule from the Style Guide for Python Code - Descriptive: Naming Styles:

• _single_leading_underscore: weak "internal use" indicator. E.g. from M import * does not import objects whose name starts with an underscore.

If anything, the said Style Guide actually is against using _single_leading_underscore.py in filename. Its Package and Module Names section only mentions such usage when a module is implemented in C/C++.

In general, that _single_leading_underscore notation is typically observed in function names, method names and member variables, to differentiate them from other normal methods.

There is few need (if any at all), to use _single_leading_underscore.py on filename, because the developers are not scrapers , they are unlikely to salvage a file based on its filename. They would just follow a package's highest level of APIs (technically speaking, its exposed entities defined by __all__), therefore all the filenames are not even noticeable, let alone to be a factor, of whether a file (i.e. module) would be used.

Skirt