Skip to content

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):

  1. Первая строка — однострочное резюме: что это и что делает, заканчивается точкой. Именно её видят все: help(), однострочная подсказка IDE, pydoc.
  2. Пустая строка, затем развёрнутое описание: назначение, когда применять, особенности.
  3. У класса — секция Attributes:, у метода — Args:, Returns:, Raises:, по необходимости Examples:.
  4. Общий отступ всех строк интерпретатор сбрасывает сам, поэтому 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) печатает его с секциями.

Рекомендации ​

  1. Формат __repr__ — как вызов конструктора с именованными аргументами: ClassName(arg=value); строки — через !r.
  2. __str__ — человекочитаемое: единицы, подписи, «Посылка 'Книги' — 2.5 кг».
  3. Если пишете только один метод — пишите __repr__: он работает и для print.
  4. Не делайте __repr__ тяжёлым (без обращений к БД) — он вызывается при любой печати списков.
  5. Docstring у каждого публичного класса и метода: первая строка — резюме с точкой, дальше Attributes: / Args: / Returns: / Raises: (Google Style).
  6. Приватным методам (_/__) подробный docstring не обязателен, но краткая первая строка нужна и им — её видят разработчики в IDE.

Проверьте себя ​

❓Для кого предназначен `__str__`?
❓Что покажет `print(box)`, если у класса переопределён только `__repr__`?
❓Какой формат используют контейнеры (list, dict) для вывода вложенных элементов?
❓Какой формат считается лучшим для `__repr__`?
❓Что такое `__doc__`?
❓Если вы пишете только один из двух методов, какой выбрать?

Упражнения: ​

  1. Возьмите класс RomanNumber, созданный на старте курса. Добавьте:

    • __repr__, возвращающий строку RomanNumber('XIV') — форма вызова конструктора;
    • __str__, возвращающий просто римскую строку: XIV.

    Проверьте вывод:

    python
    rn = RomanNumber('XIV')
    print(repr(rn))   # RomanNumber('XIV')
    print(rn)         # XIV

    Дальше — арифметика и сравнение римских чисел.

  2. Создайте для ParcelBox __repr__ в форме вызова конструктора (ParcelBox(description='Одежда', weight=3.5)) и человекочитаемый __str__ вида «Посылка 'Одежда' — 3.5 кг». Убедитесь, что print(box) использует __str__, а repr(box) — __repr__.

  3. Создайте класс Book (title, author, pages) с __repr__ в формате Book(title='...', author='...', pages=100):

    • добавьте __str__, печатающий «"Война и мир" — Лев Толстой, 1000 стр.»;
    • проверьте вывод print(book), repr(book) и [book] — какой метод вызвался в каждом случае?