"code" --- Classes Bases do Interpretador
*****************************************

**Código-fonte:** Lib/code.py

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

O módulo "code" fornece facilidades para implementar laços de leitura-
execução-escrita no código Python. São incluídas duas classes e
funções de conveniência que podem ser usadas para criar aplicações que
fornecem um prompt de interpretador interativo.

class code.InteractiveInterpreter(locals=None)

   Esta classe trata de analisar e interpretar o estado (espaço de
   nome do usuário); o mesmo não lida com buffer de entrada ou
   solicitação ou nomeação de arquivo de entrada (o nome do arquivo é
   sempre passado explicitamente). O argumento opcional *local*
   especifica o dicionário no qual o código será executado; ele é
   padrão para um dicionário recém-criado com a chave "'__name__'" set
   to "'__console__'" and key "'__doc__'" definido com "None".

class code.InteractiveConsole(locals=None, filename="<console>")

   Emula de forma bem similiar o comportamento do interpretador Python
   interativo. Esta classe se baseia em "InteractiveInterpreter" e
   adiciona prompting usando os familiares "sys.ps1" e "sys.ps2", e
   buffering de entrada.

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

   Convenience function to run a read-eval-print loop.  This creates a
   new instance of "InteractiveConsole" and sets *readfunc* to be used
   as the "InteractiveConsole.raw_input()" method, if provided.  If
   *local* is provided, it is passed to the "InteractiveConsole"
   constructor for use as the default namespace for the interpreter
   loop.  The "interact()" method of the instance is then run with
   *banner* and *exitmsg* passed as the banner and exit message to
   use, if provided.  The console object is discarded after use.

   Alterado na versão 3.6: Parâmetro adicionado *exitmsg*.

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

   Esta função é útil para programas que desejam emular o laço
   principal do interpretador Python (também conhecido como laço de
   leitura-execução-impressão). A parte complicada é determinar quando
   o usuário digitou um comando incompleto que pode ser concluído
   inserindo mais texto (em vez de um comando completo ou um erro de
   sintaxe). Esta função *quase* sempre toma a mesma decisão que o
   laço principal do interpretador real.

   *source* é a string fonte; *filename* é o nome do arquivo opcional
   do qual a fonte foi lida, sendo o padrão "'<input>'"; e *symbol* é
   o símbolo opcional de início da gramática, que deve ser "'single'"
   (o padrão), "'eval'" ou "'exec'".

   Retorna um objeto código (o mesmo que "compile(source, filename,
   symbol)") se o comando for completo e válido; "None" se o comando
   estiver incompleto; levanta "SyntaxError" se o comando estiver
   completo e contém um erro de sintaxe, ou levanta "OverflowError" ou
   "ValueError" se o comando contiver um literal inválido.


Objetos de interpretador interativo
===================================

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

   Compila e executa alguma fonte no interpretador. Os argumentos são
   os mesmos de "compile_command()"; o padrão para *filename* é
   "'<input>'", e para *symbol* é "'single'". Uma de várias coisas
   pode acontecer:

   * A entrada está incorreta; "compile_command()" levantou uma
     exceção ("SyntaxError" ou "OverflowError"). Um traceback da
     sintaxe será impresso chamando o método "showsyntaxerror()".
     "runsource()" retorna "False".

   * A entrada está incompleta e são necessárias mais entradas;
     "compile_command()" retornou "None". "runsource()" retorna
     "True".

   * A entrada está completa; "compile_command()" retornou um objeto
     código. O código é executado chamando "runcode()" (que também
     lida com exceções de tempo de execução, exceto "SystemExit").
     "runsource()" retorna "False".

   O valor de retorno pode ser usado para decidir se usar "sys.ps1" ou
   "sys.ps2" para solicitar a próxima linha.

InteractiveInterpreter.runcode(code)

   Executa um objeto código. Quando ocorre uma exceção,
   "showtraceback()" é chamado para exibir um traceback. Todas as
   exceções são capturadas, exceto "SystemExit", que pode ser
   propagada.

   Uma observação sobre "KeyboardInterrupt": esta exceção pode ocorrer
   em outro lugar neste código e nem sempre pode ser detectada. O
   chamador deve estar preparado para lidar com isso.

InteractiveInterpreter.showsyntaxerror(filename=None)

   Exibe o erro de sintaxe que acabou de ocorrer. Isso não exibe um
   stack trace (situação da pilha de execução) porque não há um para
   erros de sintaxe. Se *filename* for fornecido, ele será inserido na
   exceção em vez do nome de arquivo padrão fornecido pelo analisador
   sintático do Python, porque ele sempre usa "'<string>'" ao ler uma
   string. A saída é escrita pelo método "write()".

InteractiveInterpreter.showtraceback()

   Exibe a exceção que acabou de ocorrer. Removemos o primeiro item da
   pilha porque ele está dentro da implementação do objeto
   interpretador. A saída é escrita pelo método "write()".

   Alterado na versão 3.5: O traceback encadeado completo é exibido em
   vez de apenas o traceback primário.

InteractiveInterpreter.write(data)

   Escreve uma string no fluxo de erro padrão ("sys.stderr"). As
   classes derivadas devem substituir isso para fornecer o tratamento
   de saída apropriado conforme necessário.


Objetos de console Interativo
=============================

A classe "InteractiveConsole" é uma subclasse de
"InteractiveInterpreter" e, portanto, oferece todos os métodos dos
objetos interpretadores, bem como as seguintes adições.

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

   Emula de forma muito semelhante o console interativo do Python. O
   argumento opcional *banner* especifica o banner a ser impresso
   antes da primeira interação; por padrão ele imprime um banner
   semelhante ao impresso pelo interpretador Python padrão, seguido
   pelo nome da classe do objeto console entre parênteses (para não
   confundir isso com o interpretador real -- já que está tão
   próximo!).

   O argumento opcional *exitmsg* especifica uma mensagem de saída
   impressa ao sair. Passe a string vazia para suprimir a mensagem de
   saída. Se *exitmsg* não for fornecido ou "None", uma mensagem
   padrão será impressa.

   Alterado na versão 3.4: Para suprimir a impressão de qualquer
   banner, passe uma string vazia.

   Alterado na versão 3.6: Imprime uma mensagem de saída ao sair.

InteractiveConsole.push(line)

   Push a line of source text to the interpreter. The line should not
   have a trailing newline; it may have internal newlines.  The line
   is appended to a buffer and the interpreter's "runsource()" method
   is called with the concatenated contents of the buffer as source.
   If this indicates that the command was executed or invalid, the
   buffer is reset; otherwise, the command is incomplete, and the
   buffer is left as it was after the line was appended.  The return
   value is "True" if more input is required, "False" if the line was
   dealt with in some way (this is the same as "runsource()").

InteractiveConsole.resetbuffer()

   Remove qualquer texto fonte não tratado do buffer de entrada.

InteractiveConsole.raw_input(prompt="")

   Escreve um prompt e leia uma linha. A linha retornada não inclui a
   nova linha final. Quando o usuário insere a sequência de teclas de
   fim de linha, uma exceção "EOFError" é levantada. A implementação
   base lê "sys.stdin"; uma subclasse pode substituir isso por uma
   implementação diferente.
