Appearance
String representation - __repr__, __str__, __doc__
Каждый объект можно превратить в строку двумя способами, а у каждого класса и метода есть встроенная «сопроводительная» строка — документация (__doc__). Python выбирает инструмент по ситуации:
__str__— печатная форма для человека (print, f-строки,str());__repr__— отладочная форма, максимально информативная, в идеале допускающая воссоздание объекта (repr(), интерактивный интерпретатор, контейнеры);__doc__— атрибут с docstring (документирующей строкой) класса или метода: встроенная справкаhelp(), подсказки IDE, генераторы документации.
Правило выбора: print и f-строки ищут __str__, а при его отсутствии используют __repr__. Контейнеры (list, dict) всегда используют __repr__ вложенных элементов.
Без переопределения
python
class ParcelBox:
def __init__(self, description, weight):
self.description, self.weight = description, weight
box = ParcelBox('Книги', 2.5)
print(box) # <__main__.ParcelBox object at 0x...>
print(repr(box)) # <__main__.ParcelBox object at 0x...>
print([box]) # [<__main__.ParcelBox object at 0x...>]Полезно для проверки памяти (уникальный адрес), но не несёт информации о содержимом.
__repr__ — «для разработчика»: что писать и зачем
Цель __repr__ — безымянная, однозначная картина содержимого для разработчика. Лучший формат — вызов конструктора с именованными аргументами: ClassName(arg1=value1, arg2=value2).
Почему именно так:
- вывод можно скопировать в код и получить тот же объект — «восстанавливаемая» запись;
print(список), логи и отладчики показывают каждый элемент в формате__repr__— именованные аргументы читаются без сопоставления с__init__;!rу строковых атрибутов автоматически добавляет кавычки — вывод остаётся валидным Python.
python
class ParcelBox:
def __init__(self, description, weight):
self.description, self.weight = description, weight
def __repr__(self):
return f"ParcelBox(description={self.description!r}, weight={self.weight})"
box = ParcelBox('Книги', 2.5)
print(repr(box)) # ParcelBox(description='Книги', weight=2.5)
print([box]) # [ParcelBox(description='Книги', weight=2.5)] — контейнер берёт repr
print(box) # ParcelBox(description='Книги', weight=2.5) — нет __str__, падает на __repr__Что писать, когда объект хранит внешние ресурсы (файл, соединение, БД): не содержимое, а идентификатор — путь или URL, потому что «воссоздать» файл по его содержимому нельзя: Cache(path='data.bin').
__str__ — «для человека»: что писать и зачем
Цель __str__ — человек видит готовое значение с единицами и подписями, а не список атрибутов. Что туда писать:
- единицы и человекочитаемое форматирование:
ParcelBox→ «Посылка 'Книги' — 2.5 кг», температура → «23.5 °C»; - короткие подписи: «Посылка 'Книги'», а не
description='Книги', weight=2.5; - без отладочного шума (адреса, внутренние флаги) — это задача
__repr__.
python
class ParcelBox:
def __init__(self, description, weight):
self.description, self.weight = description, weight
def __repr__(self):
return f"ParcelBox(description={self.description!r}, weight={self.weight})"
def __str__(self):
return f'Посылка {self.description!r} — {self.weight} кг'
box = ParcelBox('Книги', 2.5)
print(box) # Посылка 'Книги' — 2.5 кг
print(repr(box)) # ParcelBox(description='Книги', weight=2.5)
print([box]) # [ParcelBox(description='Книги', weight=2.5)]Здесь __str__ добавляет реальную ценность (единицы и человекочитаемая подпись), а __repr__ — точную машинную запись. Именно такое разделение — стандартный приём: каждый формат делает своё дело.
Частый приём: __str__ делегирует в __repr__
Если «для человека» и «для разработчика» различий нет:
python
class Point:
def __init__(self, x, y):
self.x, self.y = x, y
def __repr__(self):
return f'Point(x={self.x}, y={self.y})'
def __str__(self):
return self.__repr__()
p = Point(1, 2)
print(p) # Point(x=1, y=2)
print(repr(p)) # Point(x=1, y=2)__doc__ — встроенная документация: как работает и как оформляется
__doc__ — это атрибут (строка), а не метод: он есть у каждого класса, функции и метода. Значение берётся из docstring — первого строкового литерала в теле:
python
def clamp(value, low, high):
"""Ограничивает `value` диапазоном [low, high].
Args:
value (float): значение, которое нужно ограничить.
low (float): нижняя граница.
high (float): верхняя граница.
"""
return max(low, min(high, value))
print(clamp.__doc__) # Ограничивает `value` диапазоном [low, high].
print(clamp(15, 0, 10)) # 10Как работает:
- интерпретатор автоматически кладёт первый строковый литерал тела в атрибут
__doc__при определении класса/функции; строкового литерала нет —__doc__ is None; obj.__doc__,Класс.__doc__,Класс.метод.__doc__— доступ к тексту;help(obj)и F1 в REPL печатают docstring: первая строка становится заголовком справки;- IDE показывают docstring при наведении на имя; Sphinx/pdoc собирают из них сайт; модуль
doctestпрогоняет секциюExamples:как тесты.
Как оформляется (базовые правила PEP 257):
- Первая строка — однострочное резюме: что это и что делает, заканчивается точкой. Именно её видят все:
help(), однострочная подсказка IDE,pydoc. - Пустая строка, затем развёрнутое описание: назначение, когда применять, особенности.
- У класса — секция
Attributes:, у метода —Args:,Returns:,Raises:, по необходимостиExamples:. - Общий отступ всех строк интерпретатор сбрасывает сам, поэтому docstring пишут как обычный блок кода, с отступом от края
def.
Почему это стоит писать: docstring — единственная документация, которая живёт рядом с кодом, уезжает вместе с пакетом при переносе файлов и одинаково пригодна и человеку (IDE, help), и машинам (генераторы, doctest).
Полный стиль — отдельно
Здесь рассмотрены только механика __doc__ и минимальное оформление. Полный стандарт оформления — Google Style со всеми секциями (Args:, Returns:, Raises:, Note:, Warning:, Examples:), doctest и @property — раскрывается в отдельном уроке «Документирование кода».
Полный пример: все три в одном классе
python
class ParcelBox:
"""Класс, представляющий почтовую коробку для отправки посылок.
Хранит описание содержимого и вес; печатная форма
добавляет единицы и подпись «Посылка».
Attributes:
description (str): описание содержимого коробки.
weight (float): вес посылки в килограммах.
"""
def __init__(self, description: str, weight: float) -> None:
"""Создаёт коробку.
Args:
description (str): описание содержимого коробки.
weight (float): вес посылки в килограммах.
"""
self.description = description
self.weight = weight
def __repr__(self) -> str:
"""Возвращает отладочную форму — вызов конструктора."""
return f"ParcelBox(description={self.description!r}, weight={self.weight})"
def __str__(self) -> str:
"""Возвращает печатную форму для человека."""
return f'Посылка {self.description!r} — {self.weight} кг'
box = ParcelBox('Книги', 2.5)
print(box) # Посылка 'Книги' — 2.5 кг
print(repr(box)) # ParcelBox(description='Книги', weight=2.5)
print([box]) # [ParcelBox(description='Книги', weight=2.5)]
print(ParcelBox.__init__.__doc__.splitlines()[0]) # Создаёт коробку.Каждая часть делает своё: __str__ — человек читает «Посылка 'Книги' — 2.5 кг», __repr__ — разработчик восстанавливает объект из лога, __doc__ — IDE и help объясняют класс и конструктор. ParcelBox.__doc__ хранит текст docstring класса, а help(box) (F1 в REPL) печатает его с секциями.
Рекомендации
- Формат
__repr__— как вызов конструктора с именованными аргументами:ClassName(arg=value); строки — через!r. __str__— человекочитаемое: единицы, подписи, «Посылка 'Книги' — 2.5 кг».- Если пишете только один метод — пишите
__repr__: он работает и дляprint. - Не делайте
__repr__тяжёлым (без обращений к БД) — он вызывается при любой печати списков. - Docstring у каждого публичного класса и метода: первая строка — резюме с точкой, дальше
Attributes:/Args:/Returns:/Raises:(Google Style). - Приватным методам (
_/__) подробный docstring не обязателен, но краткая первая строка нужна и им — её видят разработчики в IDE.
Проверьте себя
Для кого предназначен `__str__`?
Что покажет `print(box)`, если у класса переопределён только `__repr__`?
Какой формат используют контейнеры (list, dict) для вывода вложенных элементов?
Какой формат считается лучшим для `__repr__`?
Что такое `__doc__`?
Если вы пишете только один из двух методов, какой выбрать?
Упражнения:
Возьмите класс
RomanNumber, созданный на старте курса. Добавьте:__repr__, возвращающий строкуRomanNumber('XIV')— форма вызова конструктора;__str__, возвращающий просто римскую строку:XIV.
Проверьте вывод:
pythonrn = RomanNumber('XIV') print(repr(rn)) # RomanNumber('XIV') print(rn) # XIVДальше — арифметика и сравнение римских чисел.
Создайте для
ParcelBox__repr__в форме вызова конструктора (ParcelBox(description='Одежда', weight=3.5)) и человекочитаемый__str__вида «Посылка 'Одежда' — 3.5 кг». Убедитесь, чтоprint(box)использует__str__, аrepr(box)—__repr__.Создайте класс
Book(title,author,pages) с__repr__в форматеBook(title='...', author='...', pages=100):- добавьте
__str__, печатающий «"Война и мир" — Лев Толстой, 1000 стр.»; - проверьте вывод
print(book),repr(book)и[book]— какой метод вызвался в каждом случае?
- добавьте