Exploring Name Mangling in Python: What It Is and How It Works

Python is known for its simplicity and readability, but when it comes to object-oriented programming (OOP), there are some less-discussed mechanisms that are crucial for writing robust code. One such mechanism is name mangling. This article will guide you through what name mangling is, why Python uses it, and how it can help prevent name collisions in complex class hierarchies.

What Is Name Mangling

Python allows methods in classes to be overridden by subclasses. However, this can sometimes lead to name conflicts when a subclass unintentionally overrides attributes or methods from the parent class. Name mangling is a mechanism Python uses to avoid these conflicts, specifically for attributes that are meant to be private.

Name mangling in Python is a feature where the interpreter changes the names of private class properties in order to minimize the risk of them being accessed and overridden by mistake. This provides a level of privacy in class attributes, though it is not strictly enforced. However, it is not a strict enforcement.

Technical Definition

In Python, any identifier with two leading underscores (__) and no more than one trailing underscore will undergo name mangling. The interpreter transforms the name by prefixing it with the class name.

Why Does Python Use Name Mangling

In order to prevent naming conflicts, particularly in the situation when the subclasses may have their own variables that may override the variables in the parent class, Python implements name mangling. Name mangling addresses this problem.

from datetime import datetime, timedelta
from time import time, sleep

class Machine:
    def __init__(self, id):
        self.id = id
        self._started = time()

    def uptime(self):
        return time() - self._started

class PetrolMachine(Machine):
    def __init__(self, id):
        super().__init__(id)
        self._started = datetime.now()

    def cost(self):
        duration = datetime.now() - self._started
        return duration/timedelta(seconds=60) *0.02

worked = PetrolMachine('12345')
sleep(0.123)
print(f"uptime : {worked.uptime():.2f}")

In this example, the Machine class stores an ID and records the start time using Python’s time() function. When you request uptime, it calculates the difference between the current time and the start time, which is stored as a floating-point number. The subclass PetrolMachine, however, stores the start time using datetime.now(). When we try to calculate the uptime, the program throws an error because it expects start_time to be a floating-point number, but it's now a datetime object. This naming conflict can happen when subclass attributes unintentionally override parent class attributes. Name mangling helps avoid this issue.

How Does Name Mangling Works

So how does name mangling help resolve this issue? When a class attribute is prefixed with two underscores, Python internally changes the name to include the class name as a prefix. Here's how you can modify the Machine class to avoid name conflicts using name mangling:

We can resolve the error by applying name mangling to the __started attribute in the Machine class, as shown below:

from datetime import datetime, timedelta
from time import time, sleep

class Machine:
    def __init__(self, id):
        self.id = id
        self.__started = time()

    def uptime(self):
        return time() - self.__started  

class PetrolMachine(Machine):
    def __init__(self, id):
        super().__init__(id)
        self._started = datetime.now()

    def cost(self):
        duration = datetime.now() - self._started
        return duration/timedelta(seconds=60) *0.02


worked = PetrolMachine('12345')
sleep(0.123)
print(f"uptime : {worked.uptime():.2f}")

A simple way of expressing name mangling is shown below. I have a class ClassA, which have one private_variable, which is name mangled.

class MyClass:
    def __init__(self):
        self.__private_var = "I am private"

    def get_private_var(self):
        return self.__private_var

my_object = MyClass()
print(my_object.get_private_var())  # This works
print(my_object.__private_var)

The second print() will raise an AttributeError because the variable __private_var has been name-mangled. Internally, Python has changed the name to _MyClass__private_var, making it harder to access from outside the class.

Accessing The Mangled Name

While Python's name mangling is designed to prevent accidental access, it doesn’t enforce strict privacy. You can still access the mangled attribute by using the full mangled name, though this is discouraged. Here's how it works: my_object._MyClass__private_var

print(my_object._MyClass__private_var)

When Does Python Mangle Names

I will explain it through a simple example

class MyClass:
    def __init__(self):
        self._protected_var = "I'm protected"
        self.__private_var__ = "I'm not mangled"

In Python, a leading single underscore (e.g., _protected_var) indicates that the attribute is "protected" and should not be accessed directly from outside the class. However, Python does not enforce this. In contrast, names with two leading underscores (e.g., __private_var) are mangled to prevent accidental overriding. Importantly, names with double underscores on both sides (e.g., __special__) are not mangled and are reserved for special use cases such as magic methods.

Benefits and Limitations

Benefits

• Helps prevent accidental overriding of class attributes in subclasses
• Provides a lightweight mechanism for privacy without being too restrictive.

Limitations

• It’s not truly private—other developers can still access the mangled name if they know how.
• Can make debugging and reading code more complex if overused.

_ Despite these limitations, name mangling remains a useful tool in Python’s OOP toolkit. While it’s not a strict enforcement of privacy, it helps prevent naming conflicts and accidental attribute overriding. Understanding name mangling will enable you to write more robust, maintainable code, especially when working with complex class hierarchies. Give it a try in your projects, and share your experiences or questions in the comments below!_

Comments

[Twisted_Code]

So if I'm understanding this correctly, it maps the unmangled identifier in the class scope (I.e. in the class's static code), and the mangled identifier anywhere else? In other words, anything not appearing within the same class block will need —if wanting to disregard the pseudo-privatization of the attribute— to use the mangled name.
Thank you for the article. I was not entirely clear on exactly which scopes apply the mangling and which do not, and starting to think I was going to have to play with it myself in the interpreter to figure it out. (Surprisingly, even as easy as the Python shell makes experimentation, none of the other four articles I found thought to give a practical example...)
PS: Double check your headings. I think you left one of them in editing limbo.

[Adarsh Theruvathkandy]

Great topic