python property class namespace confusion

I think you’re a little astray in construing _x as an "instance property" and x as a "class property" – in fact, both are bound to the instance only, and neither is bound to the other except by the arbitrarily defined behaviour of the method decorated by @property.

They both occupy the same namespace, which is why, though they may represent the same quantity, they cannot share a name for fear of shadowing/confusing the namespace.

The issue of namespaces is not directly connected to the use of the @property decorator. You don’t HAVE to "hide" the attribute name – you just need to ensure that the attribute name differs from the name of the method, because once you apply the @property decorator, the method decorated by @property can be accessed just like any other attribute without a typical method call signature including the ().

Here’s an example, adjacent to the one you provided, that may help clarify. I define a class, PositionVector below, that holds the x, y and z coordinates of a point in space.

When initialising an instance of the class, I also create an attribute length that computes the length of the vector based on the x, y and z values. Trying this:

import numpy as np

class PositionVector:
    
    def __init__(self, x: float, y: float, z: float) -> None:
        self.x = x
        self.y = y
        self.z = z
        self.length = np.sqrt(x**2 + y**2 + z**2)
        
        
p1 = PositionVector(x = 10, y = 0, z = 0)

print (p1.length)
# Result -> 10.0

Only now I want to change the y attribute of the instance. I do this:

p1.y = 10.0
print (f"p1's 'y' value is {p1.y}")
# Result -> p1's 'y' value is 10.0

Except now, if I again access the length of the vector, I get the wrong answer:

print (f"p1's length is {p1.length}")
# Result -> p1's length is 10.0

This arises because length, which at any given instant depends on the current values of x, y, and z, is never updated and kept consistent. We could fix this issue by redefining our class so length is a method that is continuously recalculated every time the user wants to access it, like so:

class PositionVector:
    
    def __init__(self, x: float, y: float, z: float) -> None:
        self.x = x
        self.y = y
        self.z = z
        
    def length(self):
        return np.sqrt(self.x**2 + self.y**2 + self.z**2)

Now, I have a way to get the correct length of an instance of this class at all times by calling the instance’s length() method:

p1 = PositionVector(x = 10, y = 0, z = 0)

print (f"p1's length is {p1.length()}")
# Result -> p1's length is 10.0

p1.y = 10.0
print (f"p1's 'y' value is {p1.y}")
# Result -> p1's 'y' value is 10.0

print (f"p1's length is {p1.length()}")
# Result -> p1's length is 14.142135623730951

This is fine, except for two issues:

1. If this class had been in use already, going back and changing length from an attribute to a method would break backward compatibility, forcing any other code that uses this class to need modifications before it could work as before.

2. Though I DO want length to recalculate every time I invoke it, I want to be able to pick it up and "handle" it like it’s a "property" of the instance, not a "behaviour" of the instance. So using p1.length() to get the instance’s length instead of simply p1.length feels unidiomatic.

I can restore backward compatibility, AND permit length to be accessed like any other attribute by applying the @property decorator to the method. Simply adding @property to the length() method definition allows its call signature to go back to its original form:

    @property
    def length(self):
        return np.sqrt(self.x**2 + self.y**2 + self.z**2)

p1 = PositionVector(x=10, y=0, z=0)

print(f"p1's length is {p1.length}")
# Result -> p1's length is 10.0

p1.y = 10.0
print(f"p1's 'y' value is {p1.y}")
# Result -> p1's 'y' value is 10.0

print(f"p1's length is {p1.length}")
# Result -> p1's length is 14.142135623730951

At this point, there are no shadowed or "underscored" attribute names, I don’t need them – I can access x, y and z normally, and access length as though it were any other attribute, and yet be confident that anytime I call it, I get the most current value, correctly reflective of the current values of x, y, and z. Calling dict on p1 in this state yields:

print(p1.__dict__)
# Result -> {'x': 10, 'y': 10.0, 'z': 0}

There could be use cases where you want to not only calculate length, but also save its value as a static attribute of an instance. This is where you might want to create an attribute and have it hold the value of length every time its calculated. You’d accomplish this like so:

class PositionVector:
    def __init__(self, x: float, y: float, z: float) -> None:
        self.x = x
        self.y = y
        self.z = z
        self.placeholder_attribute_name = None

    @property
    def length(self):
        self.placeholder_attribute_name = np.sqrt(self.x**2 + self.y**2 + self.z**2)
        return self.placeholder_attribute_name

Doing this has no effect whatsoever on the prior functioning of the class. It simply creates a way to statically hold the value of length, independent of the act of creating it.

You don’t HAVE to name that attribute anything in particular. You can name it anything you want, except for any other name already in use. In the case above, you can’t name it x, y, z, or length, because all of those have other meanings.

For readability, however, it does make sense, and it’s common practice, to do the following two things:

1. Make it obvious that this attribute is not meant to be used directly. In the case above – you don’t want someone to get the length of the vector by calling p1.placeholder_attribute_name because this is not guaranteed to yield the correct current length – they should use p1.length instead. You indicate that this attribute is not for public consumption with a commonly adopted Python convention – the leading underscore:

    class PositionVector:
        def __init__(self, x: float, y: float, z: float) -> None:
            self.x = x
            self.y = y
            self.z = z
            self._placeholder_attribute_name = None
    
        @property
        def length(self):
            self._placeholder_attribute_name = np.sqrt(self.x**2 + self.y**2 + self.z**2)
            return self._placeholder_attribute_name

2. Use the name of the attribute to convey to anyone reading your code what the attribute actually means. If the attribute is meant to shadow the "length" property – putting length in there somewhere instead of the less helpful placeholder_attribute_name would enhance readability. You could indicate that this shadows length by naming it _length.

In summary:

• Employing the @property decorator does not compel you to use "public" and "private" attribute names – you would only do so if, besides computing your attribute’s value with the @property decorated method, you also wanted to save the value of that method’s return in a persistent attribute bound to every instance of the class.
• Even when you DO choose to use propertyname in public and _propertyname in private this is not an absolute rule, it is simply a convention adopted in aid of readability.