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?

Solution 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.

Solution 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.

Solution 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).

Solution 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.

View more solutions

Comments

[Martijn Pieters]

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.

[Michał Górny]

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