Textbook of Python

A property is a managed attribute in a Python class, defined using the @property decorator. It allows you to define getter, setter, and deleter methods that are called automatically when the attribute is accessed, assigned, or deleted — while the user of the class sees it as a simple attribute, not a method call.

The typical pattern is to define a "private" attribute (by convention, prefixed with an underscore) and expose it through a property that adds validation, computation, or lazy loading. For example, a Circle class might store _radius and expose radius as a property whose setter rejects negative values. This lets you start with simple attributes and add behaviour later without changing the public interface.

Properties are implemented using Python's descriptor protocol. The property built-in is a descriptor that stores references to the getter, setter, and deleter functions. You can also use property() directly without decorators: x = property(get_x, set_x, del_x, "docstring"). Properties are one of the reasons Python rarely needs the Java-style getX()/setX() pattern: you can always add a property layer later without breaking existing code that accesses the attribute directly.