Skip to content

Mastering the _variable: Step-by-Step Guide to Effortlessly Use and Fix


Python Naming Conventions: Single and Double Underscores

Python has specific naming conventions that utilize underscores (_) to differentiate between public and non-public names, avoid conflicts, and adhere to Pythonic coding styles. Understanding and applying these conventions can make your code more readable, maintainable, and consistent, especially when collaborating with other developers. In this tutorial, we will explore these naming conventions and provide examples of their usage.

Public and Non-Public Names

Python distinguishes between public and non-public names by using a single leading underscore (_). By convention, a name starting with a single underscore indicates that it is non-public, meaning it should not be accessed or modified directly from outside its containing class or module. Non-public names are considered internal implementation details and should not be relied upon by other portions of the codebase.

Creating Public and Non-Public Names

Let’s take a look at an example of creating public and non-public names:

class MyClass:
public_var = "This is a public variable"
_non_public_var = "This is a non-public variable"
def public_method(self):
print("This is a public method")
def _non_public_method(self):
print("This is a non-public method")

In the above example, public_var and public_method are public names that can be accessed and used by other parts of the code. On the other hand, _non_public_var and _non_public_method are non-public names and should only be accessed within the class itself.

Using Public vs Non-Public Names

The usage of public and non-public names can help in distinguishing between implementation details and intended public APIs. By following this convention, you can prevent other developers from relying on non-public names, keeping your code more maintainable and preventing potential issues when making changes to the internal implementation.

Naming Conventions in Modules and Packages

Naming conventions also apply to modules and packages. Similar to the usage in classes, a single leading underscore is used to denote non-public names within the module.

Internal Variables and Constants

In modules, you can define internal variables and constants that are not intended to be accessed directly by other parts of the codebase. By prefixing these names with a single underscore, you indicate that they should be considered non-public.

_internal_var = "This is an internal variable"
_ANOTHER_INTERNAL_VAR = "This is another internal variable"

Helper Functions

Similarly, when defining helper functions within a module, a single leading underscore can be used to indicate that these functions are not intended to be directly used from outside the module.

def _helper_function():
# Do some internal processing

Non-Public Modules

In certain cases, you might have modules that are meant to be used only within a specific package and not directly by external code. These modules can be prefixed with a leading underscore to indicate their non-public nature.

_package_internal_module = "This is a non-public module"

Wildcard Imports and Non-Public Names

When using wildcard imports (from module import *), non-public names are not imported into the current namespace. This behavior is intentional, as it helps prevent name clashes and avoids polluting the importing module’s namespace with non-public names.

It is generally recommended to avoid using wildcard imports and instead import specific names explicitly for better code readability and clarity.

Class With Non-Public Members

In addition to non-public names in modules, you can also utilize non-public members within classes. By following naming conventions, you can create class attributes and methods that are not meant to be accessed directly from outside the class.

Non-Public Attributes

To define non-public attributes, you can prefix the attribute name with a single underscore. These attributes are intended for internal use within the class and should not be accessed directly from outside.

class MyClass:
def __init__(self):
self._non_public_attribute = "This is a non-public attribute"
def _non_public_method(self):
print("This is a non-public method")

Non-Public Methods

Non-public methods within a class can be defined using the same convention of a single leading underscore. These methods are meant for internal use and should not be called directly from outside the class.

class MyClass:
def public_method(self):
print("This is a public method")
def _non_public_method(self):
print("This is a non-public method")

Double Leading Underscore: Python’s Name Mangling

Python also utilizes double leading underscores to implement name mangling, a mechanism to avoid naming conflicts in subclasses. When a name is prefixed with two underscores, Python performs name mangling to prepend the class name, making the attribute or method effectively private to the class.

Understanding Name Mangling

Name mangling is used to avoid unintentionally overriding attributes or methods of a base class in a subclass. By prefixing attributes or method names with double underscores, they become hard to access directly from outside the class hierarchy.

class BaseClass:
def __init__(self):
self.__private_attribute = "This is a private attribute"
def __private_method(self):
print("This is a private method")
class SubClass(BaseClass):
def __init__(self):
self.__private_attribute = "This is a different private attribute" # Doesn't override the base class attribute
def __private_method(self):
print("This is a different private method") # Doesn't override the base class method

Using Name Mangling in Inheritance

Name mangling helps prevent accidental name clashes in subclasses by effectively making the attribute or method private to the class hierarchy. It allows each class to have its own private implementation, separate from the base class.

Other Usages of Underscores in Python

Apart from naming conventions related to public and non-public names, underscores have other commonly accepted usages in Python programming:

  • Trailing Underscores in Python Names: Trailing underscores are typically used to avoid naming conflicts with Python built-in keywords or identifiers. For example, if the desired variable name is already taken by a keyword, appending an underscore can resolve the conflict.

  • Dunder Names in Python: Dunder names, also known as magic or special names, are reserved for specific meanings or behaviors in Python. These names have a double underscore at the beginning and end, such as __init__ or __str__. They provide hooks for customization and are conventionally used for specific purposes.


Understanding and following Python’s naming conventions, which include single and double underscores, can greatly enhance your code’s readability, maintainability, and consistency. By differentiating public and non-public names, utilizing name mangling, and adhering to Pythonic coding styles, you can produce code that is easier to understand and collaborate on. Remember to always consider the intended audience of your code and apply the appropriate naming conventions for a better development experience.

Continue learning about Python’s naming conventions and refine your programming skills. Python offers a vast ecosystem with extensive libraries and frameworks, providing endless possibilities for professional development.

Get started with Python and make the most out of its naming conventions and coding styles to become a proficient developer.