[Python-checkins] CVS: python/dist/src/Doc/lib libcode.tex,1.9,1.9.4.1 libcodeop.tex,1.1,1.1.2.1

Fred L. Drake fdrake@weyr.cnri.reston.va.us
Mon, 31 Jan 2000 22:48:58 -0500 (EST)


Update of /projects/cvsroot/python/dist/src/Doc/lib
In directory weyr:/home/fdrake/projects/python/Doc-152p1/lib

Modified Files:
      Tag: release152p1-patches
	libcode.tex libcodeop.tex 
Log Message:
Update descriptions.

For the code module, add information about the interpreter base classes,
since that's what is really interesting here.


Index: libcode.tex
===================================================================
RCS file: /projects/cvsroot/python/dist/src/Doc/lib/libcode.tex,v
retrieving revision 1.9
retrieving revision 1.9.4.1
diff -C2 -r1.9 -r1.9.4.1
*** libcode.tex	1999/01/27 15:48:23	1.9
--- libcode.tex	2000/02/01 03:48:54	1.9.4.1
***************
*** 1,30 ****
  \section{\module{code} ---
!          Code object services.}
  \declaremodule{standard}{code}
  
! \modulesynopsis{Code object services.}
  
  
! The \code{code} module defines operations pertaining to Python code
! objects.  It defines the following function:
! 
  
! \begin{funcdesc}{compile_command}{source, \optional{filename\optional{, symbol}}}
  This function is useful for programs that want to emulate Python's
  interpreter main loop (a.k.a. the read-eval-print loop).  The tricky
  part is to determine when the user has entered an incomplete command
! that can be completed by entering more text (as opposed to a complete
! command or a syntax error).  This function \emph{almost} always makes
! the same decision as the real interpreter main loop.
! 
! Arguments: \var{source} is the source string; \var{filename} is the
! optional filename from which source was read, defaulting to
! \code{'<input>'}; and \var{symbol} is the optional grammar start
! symbol, which should be either \code{'single'} (the default) or
! \code{'eval'}.
! 
! Return a code object (the same as \code{compile(\var{source},
! \var{filename}, \var{symbol})}) if the command is complete and valid;
! return \code{None} if the command is incomplete; raise
! \exception{SyntaxError} if the command is a syntax error.
  \end{funcdesc}
--- 1,173 ----
  \section{\module{code} ---
!          Interpreter base classes}
  \declaremodule{standard}{code}
  
! \modulesynopsis{Base classes for interactive Python interpreters.}
  
  
! The \code{code} module provides facilities to implement
! read-eval-print loops in Python.  Two classes and convenience
! functions are included which can be used to build applications which
! provide an interactive interpreter prompt.
! 
! 
! \begin{classdesc}{InteractiveInterpreter}{\optional{locals}}
! This class deals with parsing and interpreter state (the user's
! namespace); it does not deal with input buffering or prompting or
! input file naming (the filename is always passed in explicitly).
! The optional \var{locals} argument specifies the dictionary in
! which code will be executed; it defaults to a newly created
! dictionary with key \code{'__name__'} set to \code{'__console__'}
! and key \code{'__doc__'} set to \code{None}.
! \end{classdesc}
! 
! \begin{classdesc}{InteractiveConsole}{\optional{locals\optional{, filename}}}
! Closely emulate the behavior of the interactive Python interpreter.
! This class builds on \class{InteractiveInterpreter} and adds
! prompting using the familiar \code{sys.ps1} and \code{sys.ps2}, and
! input buffering.
! \end{classdesc}
! 
! 
! \begin{funcdesc}{interact}{\optional{banner\optional{,
!                            readfunc\optional{, local}}}}
! Convenience function to run a read-eval-print loop.  This creates a
! new instance of \class{InteractiveConsole} and sets \var{readfunc}
! to be used as the \method{raw_input()} method, if provided.  If
! \var{local} is provided, it is passed to the
! \class{InteractiveConsole} constructor for use as the default
! namespace for the interpreter loop.  The \method{interact()} method
! of the instance is then run with \var{banner} passed as the banner
! to use, if provided.  The console object is discarded after use.
! \end{funcdesc}
  
! \begin{funcdesc}{compile_command}{source\optional{,
!                                   filename\optional{, symbol}}}
  This function is useful for programs that want to emulate Python's
  interpreter main loop (a.k.a. the read-eval-print loop).  The tricky
  part is to determine when the user has entered an incomplete command
! that can be completed by entering more text (as opposed to a
! complete command or a syntax error).  This function
! \emph{almost} always makes the same decision as the real interpreter
! main loop.
! 
! \var{source} is the source string; \var{filename} is the optional
! filename from which source was read, defaulting to \code{'<input>'};
! and \var{symbol} is the optional grammar start symbol, which should
! be either \code{'single'} (the default) or \code{'eval'}.
! 
! Returns a code object (the same as \code{compile(\var{source},
! \var{filename}, \var{symbol})}) if the command is complete and
! valid; \code{None} if the command is incomplete; raises
! \exception{SyntaxError} if the command is complete and contains a
! syntax error, or raises \exception{OverflowError} if the command
! includes a numeric constant which exceeds the range of the
! appropriate numeric type.
  \end{funcdesc}
+ 
+ 
+ \subsection{Interactive Interpreter Objects
+             \label{interpreter-objects}}
+ 
+ \begin{methoddesc}{runsource}{source\optional{, filename\optional{, symbol}}}
+ Compile and run some source in the interpreter.
+ Arguments are the same as for \function{compile_command()}; the
+ default for \var{filename} is \code{'<input>'}, and for
+ \var{symbol} is \code{'single'}.  One several things can happen:
+ 
+ \begin{itemize}
+ \item
+ The input is incorrect; \function{compile_command()} raised an
+ exception (\exception{SyntaxError} or \exception{OverflowError}).  A
+ syntax traceback will be printed by calling the
+ \method{showsyntaxerror()} method.  \method{runsource()} returns
+ \code{0}.
+ 
+ \item
+ The input is incomplete, and more input is required;
+ \function{compile_command()} returned \code{None}.
+ \method{runsource()} returns \code{1}.
+ 
+ \item
+ The input is complete; \function{compile_command()} returned a code
+ object.  The code is executed by calling the \method{runcode()} (which
+ also handles run-time exceptions, except for \exception{SystemExit}).
+ \method{runsource()} returns \code{0}.
+ \end{itemize}
+ 
+ The return value can be used to decide whether to use
+ \code{sys.ps1} or \code{sys.ps2} to prompt the next line.
+ \end{methoddesc}
+ 
+ \begin{methoddesc}{runcode}{code}
+ Execute a code object.
+ When an exception occurs, \method{showtraceback()} is called to
+ display a traceback.  All exceptions are caught except
+ \exception{SystemExit}, which is allowed to propogate.
+ 
+ A note about \exception{KeyboardInterrupt}: this exception may occur
+ elsewhere in this code, and may not always be caught.  The caller
+ should be prepared to deal with it.
+ \end{methoddesc}
+ 
+ \begin{methoddesc}{showsyntaxerror}{\optional{filename}}
+ Display the syntax error that just occurred.  This does not display
+ a stack trace because there isn't one for syntax errors.
+ If \var{filename} is given, it is stuffed into the exception instead
+ of the default filename provided by Python's parser, because it
+ always uses \code{'<string>'} when reading from a string.
+ The output is written by the \method{write()} method.
+ \end{methoddesc}
+ 
+ \begin{methoddesc}{showtraceback}{}
+ Display the exception that just occurred.  We remove the first stack
+ item because it is within the interpreter object implementation.
+ The output is written by the \method{write()} method.
+ \end{methoddesc}
+ 
+ \begin{methoddesc}{write}{data}
+ Write a string to standard output.  Derived classes should override
+ this to provide the appropriate output handling as needed.
+ \end{methoddesc}
+ 
+ 
+ \subsection{Interactive Console Objects
+             \label{console-objects}}
+ 
+ The \class{InteractiveConsole} class is a subclass of
+ \class{InteractiveInterpreter}, and so offers all the methods of the
+ interpreter objects as well as the following additions.
+ 
+ \begin{methoddesc}{interact}{\optional{banner}}
+ Closely emulate the interactive Python console.
+ The optional banner argument specify the banner to print before the
+ first interaction; by default it prints a banner similar to the one
+ printed by the standard Python interpreter, followed by the class
+ name of the console object in parentheses (so as not to confuse this
+ with the real interpreter -- since it's so close!).
+ \end{methoddesc}
+ 
+ \begin{methoddesc}{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
+ \method{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 \code{1} if more input is required,
+ \code{0} if the line was dealt with in some way (this is the same as
+ \method{runsource()}).
+ \end{methoddesc}
+ 
+ \begin{methoddesc}{resetbuffer}{}
+ Remove any unhandled source text from the input buffer.
+ \end{methoddesc}
+ 
+ \begin{methoddesc}{raw_input}{\optional{prompt}}
+ Write a prompt and read a line.  The returned line does not include
+ the trailing newline.  When the user enters the \EOF{} key sequence,
+ \exception{EOFError} is raised.  The base implementation uses the
+ built-in function \function{raw_input()}; a subclass may replace this
+ with a different implementation.
+ \end{methoddesc}

Index: libcodeop.tex
===================================================================
RCS file: /projects/cvsroot/python/dist/src/Doc/lib/libcodeop.tex,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -C2 -r1.1 -r1.1.2.1
*** libcodeop.tex	1999/06/23 13:33:40	1.1
--- libcodeop.tex	2000/02/01 03:48:54	1.1.2.1
***************
*** 1,6 ****
- % LaTeXed from excellent doc-string.
  \section{\module{codeop} ---
           Compile Python code}
  
  \declaremodule{standard}{codeop}
  \sectionauthor{Moshe Zadka}{mzadka@geocities.com}
--- 1,7 ----
  \section{\module{codeop} ---
           Compile Python code}
  
+ % LaTeXed from excellent doc-string.
+ 
  \declaremodule{standard}{codeop}
  \sectionauthor{Moshe Zadka}{mzadka@geocities.com}
***************
*** 8,12 ****
  
  The \module{codeop} module provides a function to compile Python code
! with hints on whether it certainly complete, possible complete or
  definitely incomplete.  This is used by the \refmodule{code} module
  and should not normally be used directly.
--- 9,13 ----
  
  The \module{codeop} module provides a function to compile Python code
! with hints on whether it is certainly complete, possibly complete or
  definitely incomplete.  This is used by the \refmodule{code} module
  and should not normally be used directly.
***************
*** 16,38 ****
  \begin{funcdesc}{compile_command}
                  {source\optional{, filename\optional{, symbol}}}
! 
! Try to compile \var{source}, which should be a string of Python
! code. Return a code object if \var{source} is valid
  Python code. In that case, the filename attribute of the code object
  will be \var{filename}, which defaults to \code{'<input>'}.
! 
! Return \code{None} if \var{source} is \emph{not} valid Python
  code, but is a prefix of valid Python code.
- 
- Raise an exception if there is a problem with \var{source}:
- \begin{itemize}
-         \item \exception{SyntaxError}
-               if there is invalid Python syntax.
-         \item \exception{OverflowError}
-               if there is an invalid numeric constant.
- \end{itemize}
  
! The \var{symbol} argument means whether to compile it as a statement
! (\code{'single'}, the default) or as an expression (\code{'eval'}).
  
  \strong{Caveat:}
--- 17,36 ----
  \begin{funcdesc}{compile_command}
                  {source\optional{, filename\optional{, symbol}}}
! Tries to compile \var{source}, which should be a string of Python
! code and return a code object if \var{source} is valid
  Python code. In that case, the filename attribute of the code object
  will be \var{filename}, which defaults to \code{'<input>'}.
! Returns \code{None} if \var{source} is \emph{not} valid Python
  code, but is a prefix of valid Python code.
  
! If there is a problem with \var{source}, an exception will be raised.
! \exception{SyntaxError} is raised if there is invalid Python syntax,
! and \exception{OverflowError} if there is an invalid numeric
! constant.
! 
! The \var{symbol} argument determines whether \var{source} is compiled
! as a statement (\code{'single'}, the default) or as an expression
! (\code{'eval'}).  Any other value will cause \exception{ValueError} to 
! be raised.
  
  \strong{Caveat:}