С помощью property() в Python вы можете создавать управляемые атрибуты в своих классах. Управляемые атрибуты, также известные как свойства (англ. properties), используются, если вам нужно изменять их внутреннюю реализацию без изменения общедоступного API класса. Когда пользователи полагаются на ваши классы и объекты, важно, чтобы ваш API был стабильным.
Свойства, вероятно, самый популярный способ быстрого создания управляемых атрибутов в абсолютно питоническом стиле.
Начало работы с property() в Python
property() позволяет вам превращать атрибуты класса в свойства или управляемые атрибуты. Поскольку это встроенная функция, вы можете использовать ее, ничего не импортируя. Для обеспечения оптимальной производительности property() была реализована на языке C .
С помощью property() вы можете присоединить геттеры и сеттеры к атрибутам класса. Это даст возможность обрабатывать внутреннюю реализацию этого атрибута, не раскрывая геттеры и сеттеры в вашем API. Вы также можете указать способ управления удалением атрибута и предоставить соответствующую строку документации для ваших свойств.
Вот полная сигнатура property:
property(fget=None, fset=None, fdel=None, doc=None)
Первые два аргумента принимают объекты функции, которые будут играть роль геттера (fget) и сеттера (fset). Вот краткое описание того, что делает каждый аргумент:
| Аргумент | Описание |
|---|---|
fget | Функция, возвращающая значение управляемого атрибута |
fset | Функция, позволяющая установить значение управляемого атрибута |
fdel | Функция для определения того, как управляемый атрибут обрабатывает удаление |
doc | Строка, представляющая docstring свойства |
Возвращаемое значение property() – это сам управляемый атрибут. Если вы обращаетесь к управляемому атрибуту, как в obj.attr, Python автоматически вызывает fget(). Если вы присваиваете атрибуту новое значение, как в obj.attr = value, Python вызывает fset(), используя входное значение в качестве аргумента. Наконец, если вы запустите оператор del obj.attr, Python автоматически вызовет fdel().
Вы можете использовать doc, чтобы предоставить соответствующую строку документации для ваших свойств. Вы и ваши коллеги-программисты сможете прочитать ее с помощью help(). Аргумент doc также полезен, когда вы работаете с редакторами кода и IDE, которые поддерживают доступ к строкам документации.
Вы можете использовать property() как функцию или как декоратор для создания ваших свойств. В следующих двух разделах вы познакомитесь с обоими подходами. Но стоит сразу отметить, что подход с декоратором более популярен в сообществе Python.
Создание атрибутов с помощью property()
Вы можете создать свойство, вызвав property() с соответствующим набором аргументов и присвоив возвращаемое значение атрибуту класса. Все аргументы для property() необязательны.
В следующем примере показано, как создать класс Circle с удобным свойством для управления его радиусом radius:
# circle.py
class Circle:
def __init__(self, radius):
self._radius = radius
def _get_radius(self):
print("Get radius")
return self._radius
def _set_radius(self, value):
print("Set radius")
self._radius = value
def _del_radius(self):
print("Delete radius")
del self._radius
radius = property(
fget=_get_radius,
fset=_set_radius,
fdel=_del_radius,
doc="The radius property."
)
В этом фрагменте кода вы создаете Circle. Инициализатор класса .__init__() принимает радиус в качестве аргумента и сохраняет его в закрытом атрибуте с именем ._radius. Затем вы определяете три закрытых метода:
._get_radius()возвращает текущее значение._radius._set_radius()принимает значение в качестве аргумента и присваивает его._radius._del_radius()удаляет атрибут экземпляра._radius
Чтобы инициализировать свойство, вы передаете три метода в качестве аргументов в property(). Вы также передаете соответствующую строку документации.
Запустим следующий код, чтобы посмотреть, как работает Circle:
>>> from circle import Circle
>>> circle = Circle(42.0)
>>> circle.radius
Get radius
42.0
>>> circle.radius = 100.0
Set radius
>>> circle.radius
Get radius
100.0
>>> del circle.radius
Delete radius
>>> circle.radius
Get radius
Traceback (most recent call last):
...
AttributeError: 'Circle' object has no attribute '_radius'
>>> help(circle)
Help on Circle in module __main__ object:
class Circle(builtins.object)
...
| radius
| The radius property.
Свойство .radius скрывает закрытый атрибут экземпляра ._radius, который теперь является вашим управляемым атрибутом. Вы можете получить доступ и назначить .radius напрямую. Под капотом Python при необходимости автоматически вызывает ._get_radius() и ._set_radius(). Когда вы выполняете del circle.radius, Python вызывает ._del_radius(), который удаляет базовый ._radius.
Свойства имеют приоритет над дескрипторами. Если вы используете dir() для проверки внутренних членов данного свойства, вы найдете в списке .__set__() и .__get__(). Эти методы обеспечивают реализацию протокола дескриптора по умолчанию.
Использование property() в качестве декоратора
Декораторы в Python используются повсюду. Это функции, которые принимают другую функцию в качестве аргумента и возвращают новую функцию с добавленным функционалом. С помощью декоратора вы можете присоединить операции предварительной и постобработки к существующей функции.
property() также может работать как декоратор, поэтому вы можете использовать синтаксис @property для быстрого создания свойств:
# circle.py
class Circle:
def __init__(self, radius):
self._radius = radius
@property
def radius(self):
"""The radius property."""
print("Get radius")
return self._radius
@radius.setter
def radius(self, value):
print("Set radius")
self._radius = value
@radius.deleter
def radius(self):
print("Delete radius")
del self._radius
Теперь код выглядит более питоническим и чистым. Вам больше не нужно использовать такие имена методов, как ._get_radius(), ._set_radius() и ._del_radius(). И у вас есть три метода с одинаковым понятным и описательным именем, похожим на атрибут.
Подход декоратора для создания свойств требует определения первого метода, использующего публичное имя для нижележащего управляемого атрибута, которым в данном случае является .radius. Этот метод должен реализовывать логику получения – геттер. В приведенном выше примере этот метод реализуется в строках с 7 по 11.
Строки с 13 по 16 определяют сеттер для .radius. В этом случае синтаксис сильно отличается. Вместо того, чтобы снова использовать @property, вы используете @radius.setter. Почему? Посмотрим на вывод dir():
>>> dir(Circle.radius) [..., 'deleter', ..., 'getter', 'setter']
Помимо .fget, .fset, .fdel и множества других специальных атрибутов и методов, property также предоставляет .deleter(), .getter() и .setter(). Каждый из этих трех методов возвращает новое свойство.
Когда вы декорируете второй метод .radius() с помощью @radius.setter, вы создаете новое свойство и переназначаете имя уровня класса .radius для его хранения. Это новое свойство содержит тот же набор методов, что и начальное, с добавлением нового сеттера, представленного в строке 14. Наконец, синтаксис декоратора переназначает новое свойство на имя уровня класса .radius. Механизм определения метода удаления аналогичен.
Новая реализация Circle работает так же, как пример в разделе выше:
>>> from circle import Circle
>>> circle = Circle(42.0)
>>> circle.radius
Get radius
42.0
>>> circle.radius = 100.0
Set radius
>>> circle.radius
Get radius
100.0
>>> del circle.radius
Delete radius
>>> circle.radius
Get radius
Traceback (most recent call last):
...
AttributeError: 'Circle' object has no attribute '_radius'
>>> help(circle)
Help on Circle in module __main__ object:
class Circle(builtins.object)
...
| radius
| The radius property.
Вам не нужно использовать пару круглых скобок для вызова .radius() в качестве метода. Вместо этого вы можете получить доступ к .radius, как к обычному атрибуту. Это, собственно, основной вариант использования свойств. Они позволяют относиться к методам, как к атрибутам, и автоматически вызывают базовый набор методов.
Предоставление атрибутов только для чтения
Вероятно, простейший вариант использования property() – предоставление атрибутов только для чтения. Допустим, вам нужен неизменяемый класс Point, который не позволяет пользователю изменять исходное значение его координат x и y. Для этого вы можете создать Point, как в следующем примере:
# point.py
class Point:
def __init__(self, x, y):
self._x = x
self._y = y
@property
def x(self):
return self._x
@property
def y(self):
return self._y
Здесь вы сохраняете входные аргументы в атрибутах ._x и ._y. Кроме того, вы определяете два метода-геттера и декорируете их с помощью @property.
Теперь у вас есть два свойства только для чтения, .x и .y, в качестве ваших координат:
>>> from point import Point
>>> point = Point(12, 5)
>>> # Read coordinates
>>> point.x
12
>>> point.y
5
>>> # Write coordinates
>>> point.x = 42
Traceback (most recent call last):
...
AttributeError: can't set attribute
Здесь point.x и point.y – простые примеры свойств, доступных только для чтения. Их поведение зависит от базового дескриптора, который предоставляет свойство. Реализация же по умолчанию .__set__() вызывает AttributeError, если вы не определяете правильный метод-сеттер.
Вы можете пойти дальше этой реализации Point и предоставить явные сеттеры, которые вызывают настраиваемое исключение с более сложными и конкретными сообщениями:
# point.py
class WriteCoordinateError(Exception):
pass
class Point:
def __init__(self, x, y):
self._x = x
self._y = y
@property
def x(self):
return self._x
@x.setter
def x(self, value):
raise WriteCoordinateError("x coordinate is read-only")
@property
def y(self):
return self._y
@y.setter
def y(self, value):
raise WriteCoordinateError("y coordinate is read-only")
В этом примере вы определяете настраиваемое исключение с именем WriteCoordinateError. Это исключение позволяет вам настроить способ реализации неизменяемого класса Point. Теперь оба сеттера вызывают ваше настраиваемое исключение с более явным сообщением.
Создание атрибутов, доступных для чтения и записи
Вы также можете использовать property() для предоставления управляемых атрибутов с возможностью чтения и записи. На практике вам просто нужно предоставить соответствующие геттер (чтение) и сеттер (запись) для ваших свойств, чтобы создать управляемые атрибуты чтения-записи.
Допустим, вы хотите, чтобы ваш класс Circle имел атрибут .diameter. Однако использование и радиуса, и диаметра в инициализаторе класса кажется ненужным, потому что вы можете вычислить одно, используя другое. Вот Circle, который управляет .radius и .diameter как атрибутами чтения и записи:
# circle.py
import math
class Circle:
def __init__(self, radius):
self.radius = radius
@property
def radius(self):
return self._radius
@radius.setter
def radius(self, value):
self._radius = float(value)
@property
def diameter(self):
return self.radius * 2
@diameter.setter
def diameter(self, value):
self.radius = value / 2
Здесь вы создаете класс Circle с .radius, доступным для чтения и записи. В этом случае геттер просто возвращает значение радиуса. Сеттер же преобразует входное значение для радиуса и присваивает его закрытому ._radius, который является переменной, используемой для хранения окончательных данных.
В этой новой реализации Circle и его атрибута .radius есть небольшая деталь. В этом случае инициализатор класса присваивает входное значение свойству .radius напрямую, вместо того, чтобы сохранять его в выделенном непубличном атрибуте, таком как ._radius.
Почему? Потому что вам нужно убедиться, что каждое значение, указанное в виде радиуса, включая значение инициализации, проходит через сеттер и преобразуется в число с плавающей точкой.
Circle также реализует атрибут .diameter как свойство. Геттер рассчитывает диаметр, используя радиус. Метод-сеттер делает кое-что любопытное. Вместо того, чтобы сохранять входное значение диаметра в специальном атрибуте, он вычисляет радиус и записывает результат в .radius.
Вот как работает наш Circle:
>>> from circle import Circle >>> circle = Circle(42) >>> circle.radius 42.0 >>> circle.diameter 84.0 >>> circle.diameter = 100 >>> circle.diameter 100.0 >>> circle.radius 50.0
И .radius, и .diameter работают как обычные атрибуты в этих примерах, обеспечивая чистый и общедоступный API для вашего класса Circle.
Предоставление атрибутов только для записи
Вы также можете создать атрибуты только для записи, изменив реализацию метода-геттера в ваших свойствах. Например, вы можете заставить свой геттер генерировать исключение каждый раз, когда пользователь обращается к значению базового атрибута.
Вот пример обработки паролей со свойством только для записи:
# users.py
import hashlib
import os
class User:
def __init__(self, name, password):
self.name = name
self.password = password
@property
def password(self):
raise AttributeError("Password is write-only")
@password.setter
def password(self, plaintext):
salt = os.urandom(32)
self._hashed_password = hashlib.pbkdf2_hmac(
"sha256", plaintext.encode("utf-8"), salt, 100_000
)
Инициализатор User принимает имя пользователя и пароль в качестве аргументов и сохраняет их в .name и .password соответственно. Вы используете свойство для управления тем, как ваш класс обрабатывает входной пароль. Геттер вызывает ошибку AttributeError всякий раз, когда пользователь пытается получить текущий пароль. Это превращает .password в атрибут только для записи:
>>> from users import User
>>> john = User("John", "secret")
>>> john._hashed_password
b'b\xc7^ai\x9f3\xd2g ... \x89^-\x92\xbe\xe6'
>>> john.password
Traceback (most recent call last):
...
AttributeError: Password is write-only
>>> john.password = "supersecret"
>>> john._hashed_password
b'\xe9l$\x9f\xaf\x9d ... b\xe8\xc8\xfcaU\r_'
В этом примере вы создаете john как экземпляр User с начальным паролем. Сеттер хеширует пароль и сохраняет его в ._hashed_password. Обратите внимание, что когда вы пытаетесь получить доступ к .password напрямую, вы получаете AttributeError. Наконец, присвоение нового значения .password запускает метод установки и создает новый хешированный пароль.
В методе установки .password вы используете os.urandom() для генерации 32-байтовой случайной строки. Чтобы сгенерировать хешированный пароль, вы используете hashlib.pbkdf2_hmac(). Затем вы сохраняете полученный хешированный пароль в закрытом атрибуте ._hashed_password. Это гарантирует, что вы никогда не сохраните пароль в виде открытого текста ни в каком извлекаемом атрибуте.
property() в действии
Иногда вам нужно отслеживать, что делает ваш код и как работают ваши программы. Один из способов сделать это в Python – использовать logging. Этот модуль предоставляет все функции, которые могут потребоваться для логирования вашего кода. Это позволит вам постоянно следить за кодом и генерировать полезную информацию о том, как он работает.
Если вам когда-либо понадобится отслеживать, как и когда вы получаете доступ к данному атрибуту и изменяете его, то вы также можете воспользоваться для этого функцией property():
# circle.py
import logging
logging.basicConfig(
format="%(asctime)s: %(message)s",
level=logging.INFO,
datefmt="%H:%M:%S"
)
class Circle:
def __init__(self, radius):
self._msg = '"radius" was %s. Current value: %s'
self.radius = radius
@property
def radius(self):
"""The radius property."""
logging.info(self._msg % ("accessed", str(self._radius)))
return self._radius
@radius.setter
def radius(self, value):
try:
self._radius = float(value)
logging.info(self._msg % ("mutated", str(self._radius)))
except ValueError:
logging.info('validation error while mutating "radius"')
Здесь вы сначала импортируете logging и определяете базовую конфигурацию. Затем вы реализуете Circle с управляемым атрибутом .radius. После чего геттер генерирует информацию каждый раз, когда вы обращаетесь к .radius в своем коде. Кроме того, сеттер регистрирует каждое изменение в .radius. Он также регистрирует те ситуации, в которых вы получаете ошибку из-за неверных входных данных.
Вот как можно использовать Circle в своем коде:
>>> from circle import Circle >>> circle = Circle(42.0) >>> circle.radius 14:48:59: "radius" was accessed. Current value: 42.0 42.0 >>> circle.radius = 100 14:49:15: "radius" was mutated. Current value: 100 >>> circle.radius 14:49:24: "radius" was accessed. Current value: 100 100 >>> circle.radius = "value" 15:04:51: validation error while mutating "radius"
Заключение
property в Python – это особый тип члена класса, обеспечивающий функциональность, занимающую место где-то между обычными атрибутами и методами. Более того, свойства позволяют изменять реализацию атрибутов экземпляра без изменения общедоступного API класса.
В этом руководстве мы разобрали, что такое property() и как эта функция работает. Кроме того, мы рассмотрели на примерах, как использовать property в Python в качестве декоратора.
Надеемся данная статья была вам полезна! Успехов в написании кода!
Сокращенный перевод статьи «Python’s property(): Add Managed Attributes to Your Classes».
