Name mangling in Python - Deep Dive

Overview - Name mangling

What is it?

Name mangling is a way Python changes the names of class attributes that start with double underscores to make them harder to access from outside the class. It helps protect these attributes from being accidentally changed or accessed. This is not true private protection but a way to avoid name conflicts in subclasses. It works by adding the class name to the front of the attribute name internally.

Why it matters

Without name mangling, attributes meant to be private could be easily accessed or overwritten from outside the class or in subclasses, causing bugs or unexpected behavior. Name mangling helps programmers signal which parts of their code are internal and should not be touched, improving code safety and maintainability. It also prevents accidental name clashes when classes are extended.

Where it fits

Learners should know basic Python classes and attributes before learning name mangling. After this, they can explore Python's access control conventions, like single underscore for protected members, and then move on to decorators and property methods for controlled access.

Mental Model

Core Idea

Name mangling is Python's way of hiding class attributes by changing their names internally to avoid accidental access or conflicts.

Think of it like...

It's like putting a secret code on your personal diary's lock so only you know how to open it, even if others see the diary on the shelf.

Class Example
┌─────────────────────────────┐
│ class MyClass:              │
│   __hidden = 42             │
│                             │
│ Internally stored as:       │
│ _MyClass__hidden = 42       │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Python class attributes

Concept: Learn how to create and access attributes inside Python classes.

In Python, classes can have attributes that store data. You create them inside the class using variables. For example: class Dog: def __init__(self, name): self.name = name Here, 'name' is an attribute you can access with dog_instance.name.

Result

You can store and retrieve data inside objects using attributes.

Knowing how attributes work is essential before understanding how Python changes attribute names.

2

Foundation

Using underscores in attribute names

Concept: Learn the meaning of single and double underscores in attribute names.

Python programmers use underscores to signal how attributes should be treated: - single underscore _var means 'internal use, but accessible' - double underscore __var means 'private, avoid outside access' Example: class Cat: def __init__(self): self._age = 5 # internal use self.__weight = 10 # private

Result

You understand the naming conventions that hint at attribute privacy.

These naming styles help communicate intent but behave differently internally.

3

Intermediate

How name mangling changes attribute names

🤔Before reading on: do you think __var is stored as '__var' or changed internally? Commit to your answer.

Concept: Python changes double underscore attribute names by adding the class name to avoid conflicts.

When you use __var inside a class, Python changes its name to _ClassName__var behind the scenes. This makes it harder to access from outside or subclasses. Example: class Bird: def __init__(self): self.__secret = 'chirp' Internally, this is stored as _Bird__secret.

Result

Attributes with double underscores are stored with a modified name including the class name.

Understanding this internal renaming explains why double underscore attributes are harder to access.

4

Intermediate

Accessing mangled names directly

🤔Before reading on: can you access __var directly from an instance? Yes or no? Commit to your answer.

Concept: You can still access mangled names if you know the new name format.

Even though __var is hidden, you can access it using _ClassName__var. Example: class Fish: def __init__(self): self.__scale = 'shiny' f = Fish() print(f._Fish__scale) # prints 'shiny' But accessing f.__scale will cause an error.

Result

You can bypass name mangling if you know the mangled name format.

Name mangling is a deterrent, not true privacy; it relies on convention and internal renaming.

5

Intermediate

Name mangling prevents subclass conflicts

🤔Before reading on: do you think subclasses can overwrite double underscore attributes accidentally? Yes or no? Commit to your answer.

Concept: Name mangling helps avoid attribute name clashes in subclasses by renaming attributes with the parent class name.

If a subclass defines an attribute with the same double underscore name, it gets mangled with the subclass name, so it doesn't overwrite the parent's attribute. Example: class Parent: def __init__(self): self.__value = 1 class Child(Parent): def __init__(self): super().__init__() self.__value = 2 p = Parent() c = Child() print(p._Parent__value) # 1 print(c._Child__value) # 2

Result

Subclasses can have their own private attributes without overwriting parent ones.

This behavior prevents bugs from accidental attribute overwrites in inheritance.

6

Advanced

Limitations and pitfalls of name mangling

🤔Before reading on: does name mangling guarantee true attribute privacy? Yes or no? Commit to your answer.

Concept: Name mangling is not true privacy and can be bypassed; it only prevents accidental access and conflicts.

Name mangling only changes the attribute name internally; it does not block access. Anyone who knows the mangled name can access or modify it. Also, it only applies to attributes starting with exactly two underscores and not ending with two underscores. Example: class Test: def __init__(self): self.__hidden = 5 # Access possible via _Test__hidden This means name mangling is a convention and a tool, not a security feature.

Result

You realize name mangling is a helpful but limited protection.

Knowing these limits helps avoid over-relying on name mangling for security or strict privacy.

7

Expert

Name mangling in Python internals and tooling

🤔Before reading on: do you think name mangling affects method names or only attributes? Commit to your answer.

Concept: Name mangling applies to any identifier starting with double underscores, including methods, and affects introspection and tooling.

Python mangles any identifier starting with two underscores and not ending with two underscores, including methods and variables. This affects how tools like debuggers, serializers, and IDEs show or access these names. For example, a method __foo becomes _ClassName__foo internally. This can cause confusion in debugging or when using reflection, as the original name is hidden. Understanding this helps when reading stack traces or using advanced Python features.

Result

You understand the broader impact of name mangling beyond simple attributes.

Knowing how name mangling affects all identifiers helps avoid surprises in debugging and tooling.

Under the Hood

When Python compiles a class, it scans for any identifiers starting with two underscores and not ending with two underscores. It then rewrites these names by prefixing them with an underscore and the class name. This happens at compile time, so the bytecode uses the mangled names. At runtime, attribute access uses these mangled names internally, making direct access via the original name fail.

Why designed this way?

Python's designers wanted a simple way to avoid accidental attribute name clashes in subclasses without enforcing strict access control. They chose name mangling as a lightweight mechanism that signals privacy intent and prevents common bugs, while keeping Python's philosophy of trusting the programmer. Alternatives like true private keywords were rejected to keep the language simple and flexible.

Class Compilation Process
┌───────────────────────────────┐
│ Source code with __var names   │
│                               │
│  class MyClass:               │
│      def __init__(self):      │
│          self.__data = 10     │
└──────────────┬────────────────┘
               │
               ▼
┌───────────────────────────────┐
│ Compiler rewrites __data to    │
│ _MyClass__data internally      │
└──────────────┬────────────────┘
               │
               ▼
┌───────────────────────────────┐
│ Bytecode uses _MyClass__data   │
│ for attribute access           │
└───────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does name mangling make attributes truly private and inaccessible? Commit yes or no.

Common Belief: Name mangling makes attributes completely private and inaccessible from outside the class.

Reality: Name mangling only changes the attribute name internally; anyone who knows the mangled name can access it.

Why it matters: Believing in true privacy can lead to security mistakes or fragile code relying on inaccessible attributes.

Quick: Does name mangling apply to all attributes starting with underscores? Commit yes or no.

Common Belief: Any attribute starting with an underscore is name mangled by Python.

Reality: Only attributes starting with exactly two underscores and not ending with two underscores are mangled.

Why it matters: Misunderstanding this can cause confusion about which attributes are protected and which are not.

Quick: Can subclasses accidentally overwrite double underscore attributes from parent classes? Commit yes or no.

Common Belief: Subclasses can overwrite double underscore attributes from parent classes by defining the same name.

Reality: Name mangling prevents this by renaming attributes with the subclass name, so they don't clash.

Why it matters: Not knowing this can cause unnecessary workarounds or bugs when extending classes.

Quick: Does name mangling affect method names as well as variables? Commit yes or no.

Common Belief: Name mangling only applies to variables, not methods.

Reality: Name mangling applies to any identifier starting with double underscores, including methods.

Why it matters: Ignoring this can cause confusion when calling or overriding methods with double underscores.

Expert Zone

1

Name mangling only applies within the class scope where the attribute is defined; accessing mangled names outside requires knowing the exact class name.

2

If a class name changes (e.g., by renaming or subclassing), the mangled names also change, which can break code relying on direct mangled access.

3

Name mangling does not apply to attributes with double underscores at the end (like __init__), preserving special method names.

When NOT to use

Avoid using name mangling when you need true encapsulation or security; instead, use properties, descriptors, or external access control. For simple internal use, a single underscore is often enough. Also, do not use name mangling for attributes meant to be accessed or overridden by subclasses.

Production Patterns

In production, name mangling is used to protect internal state in complex class hierarchies, especially in frameworks or libraries to avoid accidental overrides. It is combined with properties to control access and with documentation to signal intended usage. Developers rarely access mangled names directly but rely on the convention to prevent mistakes.

Connections

Encapsulation in Object-Oriented Programming

Name mangling is a Python-specific way to support encapsulation by hiding internal details.

Understanding name mangling helps grasp how Python approaches encapsulation differently from languages with strict private keywords.

Symbol Mangling in Compilers

Name mangling in Python is similar to symbol mangling in compiled languages that encode extra information in names.

Knowing this connection reveals how programming languages use name changes internally to manage scope and avoid conflicts.

Data Hiding in Security

Name mangling relates to data hiding, a security concept aiming to protect information from unauthorized access.

Recognizing name mangling as a weak form of data hiding clarifies its limits and the need for stronger security measures.

Common Pitfalls

#1 Trying to access a double underscore attribute directly from an instance.

Wrong approach:

class A:
def __init__(self):
self.__hidden = 5

obj = A()
print(obj.__hidden) # AttributeError

Correct approach:

print(obj._A__hidden) # 5

Root cause:

Not understanding that Python changes the attribute name internally, so the original name is not accessible.

#2 Using double underscores for attributes meant to be overridden by subclasses.

Wrong approach:

class Base:
def __init__(self):
self.__value = 1

class Child(Base):
def __init__(self):
super().__init__()
self.__value = 2

# Child's __value does not override Base's __value

Correct approach:

Use single underscore for protected attributes:
class Base:
def __init__(self):
self._value = 1

class Child(Base):
def __init__(self):
super().__init__()
self._value = 2

Root cause:

Misunderstanding that name mangling renames attributes per class, preventing overriding.

#3 Assuming name mangling provides security against malicious access.

Wrong approach:

class Secret:
def __init__(self):
self.__password = '1234'

# Believing __password is secure and inaccessible

Correct approach:

# Use encryption or secure storage instead
# Name mangling is only a naming convention, not security

Root cause:

Confusing name mangling with true access control or encryption.

Key Takeaways

Name mangling changes attribute names starting with double underscores by adding the class name to avoid accidental access and conflicts.

It is a convention and internal renaming, not true privacy or security, and can be bypassed if the mangled name is known.

Name mangling helps prevent subclasses from accidentally overwriting parent class private attributes.

Only identifiers starting with exactly two underscores and not ending with two underscores are mangled.

Understanding name mangling clarifies Python's approach to encapsulation and helps avoid common bugs in class design.