Single and Double Underscores in Python Names

Python has a few naming conventions that are based on using either a single or double underscore character (_). These conventions allow you to differentiate between public and non-public names in APIs, write subclasses safely, prevent name collisions, and more.

Following these conventions makes your code look more Pythonic and consistent to other developers. This skill is especially helpful when you’re working on collaborative projects.

By the end of this tutorial, you’ll understand that:

• Underscores in Python names indicate intent: a single leading underscore signals a non-public name, a single trailing underscore helps avoid naming conflicts, and a double leading underscore triggers name mangling for class attributes and methods.
• Python doesn’t enforce public or private names with access restrictions. It relies on naming conventions, where public names have no underscores and non-public names start with a single underscore.
• Python’s name mangling automatically renames attributes or methods with double leading underscores by prefixing them with the class name, helping you avoid accidental overrides in subclasses.
• Double leading and trailing underscores—known as dunders—denote special methods or attributes, such as .__init__(), .__len__(), and __name__, which Python uses to support internal behaviors.

You’ll explore practical examples of these naming conventions, learn when and why to use each one, and understand their effects on code readability, API design, and inheritance.

Public Interfaces and Naming Conventions in Python

As a Python programmer, you’ll frequently work with public interfaces, known as application programming interfaces (APIs). An API is a type of programming interface that offers a service to other parts of a program or other programs.

For example, the Python standard library has many modules and packages that provide certain services. To use these modules and packages, you need to access their public components, such as classes, functions, variables, constants, and modules. All these objects are part of the module or package’s public interface. They’re available for you to use directly in your code.

However, many of these packages and modules define objects that aren’t intended for direct access. These objects are meant for internal use within the specific package or module and aren’t part of its public interface.

In the context of object-oriented programming, languages like C++ and Java have the notion of public and private methods and attributes—jointly called members. In these languages, you can use these types of class members as follows:

• Public: You can use them in your own code or client code.
• Private: You can use them only from inside the defining class and its subclasses.

These languages have specific keywords and syntax to define public and private members in their classes. Once you declare a member as private, you can’t use it outside the class because the language restricts access. So, private members aren’t part of the class’s public interface, and there’s no way to access them.

In contrast, Python doesn’t have the notion of public and private members. It has neither dedicated keywords nor syntax for defining them. Therefore, you can always access the members of a Python class.

If Python doesn’t have a specific syntax to define when an object is part of a public interface, then how do you tell your users that they can or can’t use a given class, method, function, variable, constant, or even module in their code?

To approach this question, the Python community has a well-established naming convention:

If a name starts with a letter in uppercase or lowercase, then you should consider that name public and, therefore, part of the code’s API. In contrast, if a name starts with an underscore character (_), then you should consider that name non-public, meaning it’s not a part of the public API.

You should observe these naming conventions to explicitly indicate whether other developers should directly use your variables, constants, functions, methods, and modules in external code.

The Python community uses the underscore character (_) as part of other naming conventions. Here’s a summary of what PEP 8 says about using this character in names:

Note that only two of these naming conventions enforce specific Python behaviors. Using double leading underscores triggers name mangling in Python classes. You’ll learn more about this behavior in the section on name mangling.

Additionally, those names with double leading and trailing underscores that are listed in the Python data model trigger internal behaviors in specific contexts. You’ll also learn more about this topic in the section on dunder names in Python.