"code" --- インタープリター基底クラス
*************************************

**ソースコード:** Lib/code.py

======================================================================

"code" モジュールはread-eval-print (読み込み-評価-表示)ループをPython
で実装するための機能を提供します。対話的なインタプリタプロンプトを提供
するアプリケーションを作るために使える二つのクラスと便利な関数が含まれ
ています。

class code.InteractiveInterpreter(locals=None)

   このクラスは構文解析とインタープリター状態(ユーザの名前空間)を取り
   扱います。入力バッファリングやプロンプト出力、または入力ファイル指
   定を扱いません(ファイル名は常に明示的に渡されます)。オプションの
   *locals* 引数はその中でコードが実行される名前空間として使用されるマ
   ッピングを指定します。その初期値は、キー "'__name__'" が
   "'__console__'" に設定され、キー "'__doc__'" が "None" に設定された
   新しく作られた辞書です。

class code.InteractiveConsole(locals=None, filename='<console>', local_exit=False)

   Python の対話型インタープリターの振る舞いを忠実にエミュレートします
   。このクラスは "InteractiveInterpreter" を継承しており、よく知られ
   た "sys.ps1" と "sys.ps2" を使用してプロンプトと入力バッファリング
   を追加します。 *local_exit* が真の場合、コンソールでの "exit()" と
   "quit()" は "SystemExit" を送出せず、代わりに呼び出し元のコードに戻
   ります。

   バージョン 3.13 で変更: *local_exit* 引数が追加されました。

code.interact(banner=None, readfunc=None, local=None, exitmsg=None, local_exit=False)

   read-eval-print ループを実行するための便利な関数。これは
   "InteractiveConsole" の新しいインスタンスを作り、 *readfunc* が与え
   られた場合は "InteractiveConsole.raw_input()" メソッドとして使われ
   るように設定します。 *local* が与えられた場合は、インタープリタール
   ープのデフォルト名前空間として使うために "InteractiveConsole" コン
   ストラクタへ渡されます。 *local_exit* が与えられた場合は、
   "InteractiveConsole" コンストラクタへ渡されます。そして、インスタン
   スの "interact()" メソッドは、もし提供されていれば、見出しと終了メ
   ッセージして使うために *banner* と *exitmsg* を受け取り実行されます
   。コンソールオブジェクトは使われた後捨てられます。

   バージョン 3.6 で変更: *exitmsg* 引数が追加されました.

   バージョン 3.13 で変更: *local_exit* 引数が追加されました。

code.compile_command(source, filename='<input>', symbol='single')

   この関数はPythonのインタプリタメインループ(別名、read-eval-printル
   ープ)をエミュレートしようとするプログラムにとって役に立ちます。扱い
   にくい部分は、ユーザが(完全なコマンドや構文エラーではなく)さらにテ
   キストを入力すれば完全になりうる不完全なコマンドを入力したときを決
   定することです。この関数は *ほとんど* の場合に実際のインタプリタメ
   インループと同じ決定を行います。

   *source* はソース文字列です。*filename* はオプションのソースが読み
   出されたファイル名で、デフォルトで "'<input>'" です。*symbol* はオ
   プションの文法の開始記号で、"'single'" (デフォルト)または "'eval'"
   か "'exec'" にすべきです。

   コマンドが完全で有効ならば、コードオブジェクトを返します
   ("compile(source, filename, symbol)" と同じ)。コマンドが完全でない
   ならば、 "None" を返します。コマンドが完全で構文エラーを含む場合は
   、 "SyntaxError" を発生させます。または、コマンドが無効なリテラルを
   含む場合は、 "OverflowError" もしくは "ValueError" を発生させます。


対話的なインタプリタオブジェクト
================================

InteractiveInterpreter.runsource(source, filename='<input>', symbol='single')

   インタプリタ内のあるソースをコンパイルし実行します。引数は
   "compile_command()" のものと同じです。 *filename* のデフォルトは
   "'<input>'" で、 *symbol* は "'single'" です。あるいくつかのことが
   起きる可能性があります:

   * 入力が不正。 "compile_command()" が例外("SyntaxError" か
     "OverflowError")を起こした場合。 "showsyntaxerror()" メソッドの呼
     び出によって、構文トレースバックが表示されるでしょう。
     "runsource()" は "False" を返します。

   * 入力が完全でなく、さらに入力が必要。 "compile_command()" が
     "None" を返した場合。 "runsource()" は "True" を返します。

   * 入力が完全。 "compile_command()" がコードオブジェクトを返した場合
     。 ("SystemExit" を除く実行時例外も処理する) "runcode()" を呼び出
     すことによって、コードは実行されます。 "runsource()" は "False"
     を返します。

   戻り値は、次の行のプロンプトに "sys.ps1" か "sys.ps2" のどちらを使
   うのか判断するために使えます。

InteractiveInterpreter.runcode(code)

   コードオブジェクトを実行します。例外が生じたときは、トレースバック
   を表示するために "showtraceback()" が呼び出されます。伝搬することが
   許されている "SystemExit" を除くすべての例外が捉えられます。

   "KeyboardInterrupt" についての注意。このコードの他の場所でこの例外
   が生じる可能性がありますし、常に捕らえることができるとは限りません
   。呼び出し側はそれを処理するために準備しておくべきです。

InteractiveInterpreter.showsyntaxerror(filename=None)

   起きたばかりの構文エラーを表示します。複数の構文エラーに対して一つ
   あるのではないため、これはスタックトレースを表示しません。
   *filename* が与えられた場合は、Pythonのパーサが与えるデフォルトのフ
   ァイル名の代わりに例外の中へ入れられます。なぜなら、文字列から読み
   込んでいるときはパーサは常に "'<string>'" を使うからです。出力は
   "write()" メソッドによって書き込まれます。

InteractiveInterpreter.showtraceback()

   起きたばかりの例外を表示します。スタックの最初の項目を取り除きます
   。なぜなら、それはインタプリタオブジェクトの実装の内部にあるからで
   す。出力は "write()" メソッドによって書き込まれます。

   バージョン 3.5 で変更: 最初のトレースバックではなく、完全なトレース
   バックの連鎖が表示されます。

InteractiveInterpreter.write(data)

   文字列を標準エラーストリーム("sys.stderr")へ書き込みます。必要に応
   じて適切な出力処理を提供するために、派生クラスはこれをオーバーライ
   ドすべきです。


対話的なコンソールオブジェクト
==============================

"InteractiveConsole" クラスは "InteractiveInterpreter" のサブクラスで
す。以下の追加メソッドだけでなく、インタプリタオブジェクトのすべてのメ
ソッドも提供します。

InteractiveConsole.interact(banner=None, exitmsg=None)

   対話的な Python コンソールをそっくりにエミュレートします。オプショ
   ンの *banner* 引数は最初のやりとりの前に表示するバナーを指定します
   。デフォルトでは、標準 Python インタプリタが表示するものと同じよう
   なバナーを表示します。それに続けて、実際のインタプリタと混乱しない
   ように (とても似ているから!) 括弧の中にコンソールオブジェクトのクラ
   ス名を表示します。

   オプション引数の *exitmsg* は、終了時に出力される終了メッセージを指
   定します。空文字列を渡すと、出力メッセージを抑止します。もし、
   *exitmsg* が与えられないか、"None" の場合は、デフォルトのメッセージ
   が出力されます。

   バージョン 3.4 で変更: バナーの表示を抑制するには、空の文字列を渡し
   てください。

   バージョン 3.6 で変更: 終了時に、終了メッセージを表示します。

InteractiveConsole.push(line)

   ソーステキストの一行をインタープリターへ送ります。その行の末尾に改
   行がついていてはいけません。内部に改行を持っているかもしれません。
   その行はバッファへ追加され、ソースとして連結されたバッファの内容が
   渡されインタープリターの "runsource()" メソッドが呼び出されます。コ
   マンドが実行されたか、有効であることをこれが示している場合は、バッ
   ファはリセットされます。そうでなければ、コマンドが不完全で、その行
   が付加された後のままバッファは残されます。さらに入力が必要ならば、
   戻り値は "True" です。その行がある方法で処理されたならば、 "False"
   です(これは "runsource()" と同じです)。

InteractiveConsole.resetbuffer()

   入力バッファから処理されていないソーステキストを取り除きます。

InteractiveConsole.raw_input(prompt='')

   プロンプトを書き込み、一行を読み込みます。返る行は末尾に改行を含み
   ません。ユーザがEOFキーシーケンスを入力したときは、 "EOFError" を発
   生させます。基本実装では、 "sys.stdin" から読み込みます。サブクラス
   はこれを異なる実装と置き換えるかもしれません。
