.. _2to3-reference:

2to3 - Python 2 から 3 への自動コード変換
===============================================

.. sectionauthor:: Benjamin Peterson

2to3 は Python 2.x のソースコードを読み込み、 *変換プログラム* の系列
を適用し、 Python 3.x のコードに変換するプログラムです。標準ライブラリ
はほとんど全てのコードを取り扱うのに十分な変換プログラムを含んでいます。
2to3 を支援しているライブラリは、柔軟かつ一般的な :mod:`lib2to3` です
が、 2to3 のために、あなた自身が変換プログラムを書くこともできます。
:mod:`lib2to3` は Python コードを自動編集する必要がある場合にも、適用
することができます。


2to3 の使用
-----------

2to3 は大抵の場合、 Python インタープリターと共に、スクリプトとしてイ
ンストールされます。場所は、 Python のルートディレクトリにある、
:file:`Tools/scripts` ディレクトリです。

2to3 に与える基本の引数は、変換対象のファイル、もしくは、ディレクトリ
のリストです。ディレクトリの場合は、 Python ソースコードを再帰的に探索
します。

Python 2.x のサンプルコード、 :file:`example.py` を示します。::

   def greet(name):
       print "Hello, {0}!".format(name)
   print "What's your name?"
   name = raw_input()
   greet(name)

これは、コマンドラインから 2to3 を呼び出すことで、 Python 3.x コードに
変換されます。::

   $ 2to3 example.py

オリジナルのソースファイルに対する差分が表示されます。 2to3 は必要となる
変更をソースファイルに書き込むこともできます ( もちろんオリジナルの
バックアップも作成されます ) 。変更の書き戻しは、 :option:`-w` フラグ
によって有効化されます。::

   $ 2to3 -w example.py

変換後、 :file:`example.py` は以下のようになります。::

   def greet(name):
       print("Hello, {0}!".format(name))
   print("What's your name?")
   name = input()
   greet(name)

変換処理を通じて、コメントと、インデントは保存されます。

デフォルトでは、 2to3 はあらかじめ定義された一連の変換プログラムを実行
します。オプション :option:`-l` フラグは、利用可能な変換プログラムの一
覧を表示します。オプション :option:`-f` フラグにより、実行する変換プロ
グラムを明示的に与えることもできます。下記の例では、 ``imports`` と、
``has_key`` 変換プログラムだけを実行します。::

   $ 2to3 -f imports -f has_key example.py

いくつかの変換プログラムは *明示的* 、つまり、デフォルトでは実行され
ず、コマンドラインで実行するものとして列記する必要があります。
デフォルトの変換プログラムに ``idioms`` 変換プログラムを追加して実行す
るには、下記のようにします。::

   $ 2to3 -f all -f idioms example.py

ここで、 ``all`` を指定することで、全てのデフォルトの変換プログラムを
有効化できることに注意して下さい。

時に、 2to3 はあなたのソースコードに修正すべき点を見つけるでしょう。し
かし、 2to3 は自動的には修正できません。この場合、 2to3 はファイルの変
更点の下に警告を表示します。あなたは、 3.x に準拠したコードにするよう、
警告に対処しなくてはなりません。

2to3 は、 doctests の修正もできます。このモードを有効化するには、オプ
ション、 :option:`-d` フラグを指定して下さい。
doctests *だけ* が修正されることに注意して下さい。これは、モジュール
が有効な Python であることを要求しないことでもあります。例えば、
doctest に似た、例えば reST ドキュメントなども、このオプションで修正す
ることができるということです。

オプション、 :option:`-v` は、変換処理のより詳しい情報の出力を有効化し
ます。

オプション、 :option:`-p` が指定されると、 2to3 は、 ``print`` を文で
はなく、関数として扱います。これは、 ``from __future__ import
print_function`` が使われている場合に便利です。もし、このオプションが
与えられなければ、 print 変換プログラムは丸括弧付きの print 文
(``print ("a" + "b" + "c")`` のような)と、本当の関数呼び出しの区別が付
かないため、 print 呼び出しを、丸括弧で囲みます。


:mod:`lib2to3` - 2to3's library
-------------------------------

.. module:: lib2to3
   :synopsis: the 2to3 library
.. moduleauthor:: Guido van Rossum
.. moduleauthor:: Collin Winter


.. warning::

   :mod:`lib2to3` API は不安定で、将来、劇的に変更されるかも知れないと
   考えるべきです。

.. XXX What is the public interface anyway?
