"code" --- 解释器基类
*********************

**源代码：** Lib/code.py

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

"code" 模块提供了在 Python 中实现 read-eval-print 循环的功能。它包含两
个类和一些快捷功能，可用于构建提供交互式解释器的应用程序。

class code.InteractiveInterpreter(locals=None)

   这个类会处理解析和解释器状态（用户的命名空间）；它不会处理输入缓冲
   、提示或输入文件命名（文件名总是显式地传入）。 可选的 *locals* 参数
   指定一个映射作为代码执行所在的命名空间；它默认是一个新创建的字典，
   该字典中的键 "'__name__'" 设为 "'__console__'" 而键 "'__doc__'" 设
   为 "None"。

   请注意在 "InteractiveInterpreter" 实例下创建的函数和类对象将属于由
   *locals* 指定的命名空间。 只有当 *locals* 是现有模块的命名空间时它
   们才是可 pickle 的。

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)

   运行一个读取-求值-打印循环的便捷函数。 这会创建一个新的
   "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()" 返回了一个代码对象。 将通过调用
     "runcode()" 执行代码（该方法也会处理运行时异常，"SystemExit" 除外
     ）。 "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" 读取；子类可
   以用其他实现代替。
