sixのIteratorの真意がわからなくてちょっと困った

ドキュメントを書く際には気をつけないといけないこと、なんだけど…。

A class for making portable iterators. The intention is that it be subclassed and subclasses provide a __next__ method. In Python 2, Iterator has one method: next. It simply delegates to __next__. An alternate way to do this would be to simply alias next to __next__. However, this interacts badly with subclasses that override __next__. Iterator is empty on Python 3. (In fact, it is just aliased to object.)

これね、six のソースみればやってることはこれだけ:

pix.py
1 if PY3:
2     # ...snip...
3     Iterator = object
4 else:
5     # ...snip...
6     class Iterator(object):
7 
8         def next(self):
9             return type(self).__next__(self)

なんかね、説明上手じゃないなぁ、と思った。要するに、
1. Python 2 では、イタレータとして振舞うには、__iter__next の提供が必要
2. Python 3 では、イタレータとして振舞うには、__iter____next__ の提供が必要
3. 従って、移植性の高い Iterator の具としては、「Python 2での next を忘れさせてくれる」のが美味しい

というだけのことなのよね。

で、翻訳しにくかったのは「An alternate way」の真意が取りにくいからだったんだけど、なんで訳しにくいかってぇと、これね、「そのデザインのための技術的な理由」と「利用者への説明」が渾然一体で説明されちゃってるからなのね。

自分でも良くやっちゃうよ、これ、と思うんだけど、みなさんはどうですかね?

結局こんな訳にした:

移植性のあるイタレータを作るための class です。これは subclass 化して
用い、subclass は “__next__“ を提供することで機能することを意図しています。
Python 2 においては six の :class:`Iterator` はたった一つのメソッド “next“ を
持っています。それは単純に “__next__“ に処理を委譲しています。
“next“ を “__next__“ へのエイリアスとして作る代替案はありますが、
これはサブクラスが “__next__“ をオーバライドすることと相性が悪いです(のでそうしていません)。
Python 3 では :class:`Iterator` は空です。(実際、これは単に :class:`py3:object`
へのエイリアスになっています。)

「(のでそうしていません)」は原文にはないです。

なんか無駄に苦労した。(というか他の苦心した箇所の方が遥かに「苦心」なんだけど、この Iterator のそれは、理由が「馬鹿らしい」のがなんだか徒労感増してさ…。)