Краткий ответ

Одного __int__ недостаточно: для индексов Python ожидает протокол __index__. Он означает, что объект имеет точное целочисленное представление и может безопасно использоваться там, где требуется именно целое число, например в индексах, срезах и функции range.

__int__ отвечает за общее преобразование к int и не гарантирует, что результатом является допустимый точный индекс. Поэтому объект может успешно преобразовываться через int, но вызывать TypeError при использовании в срезе.

Исторический контекст

Протокол __index__ появился для отделения точного целочисленного представления от общего числового преобразования. Исходная проблема заключалась в том, что не каждый объект, из которого можно получить int, должен автоматически считаться корректным индексом.

Например, числовой объект может поддерживать преобразование к целому с округлением или потерей информации. Для индексации требуется более сильная гарантия: значение уже является целым в смысле своей модели данных, а не просто было приведено к целому.

Постановка проблемы

Если код принимает объект, который должен обозначать позицию, размер или количество повторений, использование только __int__ создаёт неоднозначность. Python не может считать любое успешное преобразование к int доказательством того, что объект допустим в индексном контексте.

Неверная реализация приводит к TypeError в срезах, индексах последовательностей, range и других операциях. Попытка заранее вызывать int вручную может скрыть ошибку модели данных и незаметно округлить или преобразовать неподходящее значение.

Подробное решение

__index__ вызывается протоколом точного целочисленного представления. Его используют, в частности, операции индексирования, границы срезов, range, а также функции вроде bin и hex.

Минимальный пример:

class Position:
    def __init__(self, value):
        self.value = value

    def __int__(self):
        return int(self.value)

    def __index__(self):
        return self.value

items = ['a', 'b', 'c', 'd']
print(items[:Position(2)])

В этом примере срез использует __index__, а не произвольное преобразование через __int__. Метод должен вернуть целое значение; если объект не представляет точное целое, реализовывать __index__ для него нельзя.

int(obj) и operator.index(obj) имеют разный смысл. Первый просит получить целочисленное преобразование, а второй проверяет именно индексный протокол. Если у класса определён только __int__, operator.index(obj) и операции, использующие индексный протокол, завершатся ошибкой.

Практическое правило: реализуйте __int__, когда нужен общий числовой перевод, и __index__, когда объект действительно является точным целочисленным значением. Иногда нужны оба метода, но наличие одного не должно автоматически подменять другой.

Ситуация из практики

Допустим, библиотека принимает объект конфигурации, задающий число элементов для отображения. Разработчик реализовал только __int__ и внутри библиотеки начал передавать объект непосредственно в срезы. В результате обычное преобразование работает, но встроенные операции Python завершаются TypeError.

Вариант с принудительным вызовом int перед каждым использованием прост в реализации, но рассеивает правила преобразования по коду и может принять значение, которое лишь приблизительно приводится к целому. Вариант с реализацией __index__ лучше выражает контракт объекта: библиотека и встроенные операции получают единый стандартный механизм проверки.

Выбранное решение — реализовать __index__, если значение действительно точно целочисленное, и оставить __int__ только при наличии отдельного полезного сценария общего преобразования. Это делает ошибки явными, сохраняет совместимость с протоколами Python и не заставляет вызывающий код вручную нормализовать значение.

Что кандидаты часто упускают

Дополнительный вопрос: Можно ли считать наличие __int__ основанием для автоматического использования объекта в range?

Ответ: Нет. range использует индексный протокол, то есть ожидает __index__. Наличие __int__ сообщает только о поддержке общего преобразования к целому и не даёт гарантии точного индексного смысла. Поэтому класс с одним __int__ может быть принят функцией int, но отклонён range.
Дополнительный вопрос: Что произойдёт, если __index__ вернёт объект с пользовательским числовым поведением, но не целое значение?

Ответ: Python сочтёт реализацию протокола некорректной и поднимет исключение, обычно TypeError. __index__ должен возвращать целочисленный результат, а не произвольный объект, который можно ещё раз преобразовать к целому. Это защищает операции индексации от неоднозначных или многоступенчатых преобразований.
Дополнительный вопрос: Почему bool допустим в индексном контексте, хотя это логический тип?

Ответ: В Python bool является подклассом int: значения False и True соответствуют 0 и 1. Поэтому они обладают корректным целочисленным индексным поведением. Это формально допустимо, хотя в прикладном коде использование логического значения как индекса может быть неочевидным и требовать отдельной проверки намерений.