Rooba
/
cpython
mirror of https://github.com/python/cpython.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Use \citetitle and \programopt as appropriate.

This commit is contained in:
Fred Drake 1999-11-10 16:21:37 +00:00
parent e15eb35fd0
commit 37f1574f2e
13 changed files with 149 additions and 144 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
Doc/lib/lib.tex
View File

@ -30,16 +30,16 @@ Python is an extensible, interpreted, object-oriented programming
language. It supports a wide range of applications, from simple text
processing scripts to interactive WWW browsers.
While the \emph{Python Reference Manual} describes the exact syntax and
semantics of the language, it does not describe the standard library
that is distributed with the language, and which greatly enhances its
immediate usability. This library contains built-in modules (written
in C) that provide access to system functionality such as file I/O
that would otherwise be inaccessible to Python programmers, as well as
modules written in Python that provide standardized solutions for many
problems that occur in everyday programming. Some of these modules
are explicitly designed to encourage and enhance the portability of
Python programs.
While the \citetitle[../ref/ref.html]{Python Reference Manual}
describes the exact syntax and semantics of the language, it does not
describe the standard library that is distributed with the language,
and which greatly enhances its immediate usability. This library
contains built-in modules (written in C) that provide access to system
functionality such as file I/O that would otherwise be inaccessible to
Python programmers, as well as modules written in Python that provide
standardized solutions for many problems that occur in everyday
programming. Some of these modules are explicitly designed to
encourage and enhance the portability of Python programs.
This library reference manual documents Python's standard library, as
well as many optional library modules (which may or may not be
@ -50,11 +50,13 @@ functions and exceptions, many of which are not or incompletely
documented in the Reference Manual.
This manual assumes basic knowledge about the Python language. For an
informal introduction to Python, see the \emph{Python Tutorial}; the
\emph{Python Reference Manual} remains the highest authority on
syntactic and semantic questions. Finally, the manual entitled
\emph{Extending and Embedding the Python Interpreter} describes how to
add new extensions to Python and how to embed it in other applications.
informal introduction to Python, see the
\citetitle[../tut/tut.html]{Python Tutorial}; the
\citetitle[../ref/ref.html]{Python Reference Manual} remains the
highest authority on syntactic and semantic questions. Finally, the
manual entitled \citetitle[../ext/ext.html]{Extending and Embedding
the Python Interpreter} describes how to add new extensions to Python
and how to embed it in other applications.
\end{abstract}

3
Doc/lib/libcurses.tex
View File

@ -16,7 +16,8 @@ curses.
\begin{seealso}
\seetext{Tutorial material on using curses with Python is available
on the Python Web site as Andrew Kuchling's \emph{Curses
on the Python Web site as Andrew Kuchling's
\citetitle[http://www.python.org/doc/howto/curses/curses.html]{Curses
Programming with Python}, at
\url{http://www.python.org/doc/howto/curses/curses.html}.}
\end{seealso}

26
Doc/lib/libexcs.tex
View File

@ -11,15 +11,17 @@ and users are encouraged to do the same. The source code for those
exceptions is present in the standard library module
\module{exceptions}; this module never needs to be imported explicitly.
For backward compatibility, when Python is invoked with the \code{-X}
option, most of the standard exceptions are strings\footnote{For
forward-compatibility the new exceptions \exception{Exception},
\exception{LookupError},
\exception{ArithmeticError}, \exception{EnvironmentError}, and
\exception{StandardError} are tuples.}. This option may be used to
run code that breaks because of the different semantics of class based
exceptions. The \code{-X} option will become obsolete in future
Python versions, so the recommended solution is to fix the code.
For backward compatibility, when Python is invoked with the
\programopt{-X} option, most of the standard exceptions are
strings\footnote{
For forward-compatibility the new exceptions \exception{Exception},
\exception{LookupError}, \exception{ArithmeticError},
\exception{EnvironmentError}, and \exception{StandardError} are
tuples.
}. This option may be used to run code that breaks because of the
different semantics of class based exceptions. The
\programopt{-X} option will become obsolete in future Python versions,
so the recommended solution is to fix the code.
Two distinct string objects with the same value are considered different
exceptions. This is done to force programmers to use exception names
@ -122,8 +124,8 @@ created with other than 2 or 3 arguments. In this last case,
\setindexsubitem{(built-in exception)}
The following exceptions are the exceptions that are actually raised.
They are class objects, except when the \code{-X} option is used to
revert back to string-based standard exceptions.
They are class objects, except when the \programopt{-X} option is used
to revert back to string-based standard exceptions.
\begin{excdesc}{AssertionError}
Raised when an \keyword{assert} statement fails.
@ -150,7 +152,7 @@ Raised when an \keyword{assert} statement fails.
\begin{excdesc}{FloatingPointError}
Raised when a floating point operation fails. This exception is
always defined, but can only be raised when Python is configured
with the \code{--with-fpectl} option, or the
with the \programopt{-}\programopt{-with-fpectl} option, or the
\constant{WANT_SIGFPE_HANDLER} symbol is defined in the
\file{config.h} file.
\end{excdesc}

8
Doc/lib/libimaplib.tex
View File

@ -72,10 +72,10 @@ At the end of the module, there is a test section that contains a more
extensive example of usage.
\begin{seealso}
\seetext{Documents describing the protocol, and sources and binaries
for servers implementing it, can all be found at the University of
Washington's \emph{IMAP Information Center}
(\url{http://www.cac.washington.edu/imap/}).}
\seetext{Documents describing the protocol, and sources and binaries
for servers implementing it, can all be found at the
University of Washington's \emph{IMAP Information Center}
(\url{http://www.cac.washington.edu/imap/}).}
\end{seealso}

4
Doc/lib/libobjs.tex
View File

@ -20,5 +20,5 @@ listing them in order of ascending priority (within a table) and
grouping operators that have the same priority in the same box.
Binary operators of the same priority group from left to right.
(Unary operators group from right to left, but there you have no real
choice.) See Chapter 5 of the \emph{Python Reference Manual} for the
complete picture on operator priorities.
choice.) See Chapter 5 of the \citetitle[../ref/ref.html]{Python
Reference Manual} for the complete picture on operator priorities.

34
Doc/lib/libparser.tex
View File

@ -35,23 +35,23 @@ the \module{parser} module are presented.
Most importantly, a good understanding of the Python grammar processed
by the internal parser is required. For full information on the
language syntax, refer to the \emph{Python Language Reference}. The
parser itself is created from a grammar specification defined in the file
\file{Grammar/Grammar} in the standard Python distribution. The parse
trees stored in the AST objects created by this module are the
actual output from the internal parser when created by the
\function{expr()} or \function{suite()} functions, described below. The AST
objects created by \function{sequence2ast()} faithfully simulate those
structures. Be aware that the values of the sequences which are
considered ``correct'' will vary from one version of Python to another
as the formal grammar for the language is revised. However,
transporting code from one Python version to another as source text
will always allow correct parse trees to be created in the target
version, with the only restriction being that migrating to an older
version of the interpreter will not support more recent language
constructs. The parse trees are not typically compatible from one
version to another, whereas source code has always been
forward-compatible.
language syntax, refer to the \citetitle[../ref/ref.html]{Python
Language Reference}. The parser itself is created from a grammar
specification defined in the file \file{Grammar/Grammar} in the
standard Python distribution. The parse trees stored in the AST
objects created by this module are the actual output from the internal
parser when created by the \function{expr()} or \function{suite()}
functions, described below. The AST objects created by
\function{sequence2ast()} faithfully simulate those structures. Be
aware that the values of the sequences which are considered
``correct'' will vary from one version of Python to another as the
formal grammar for the language is revised. However, transporting
code from one Python version to another as source text will always
allow correct parse trees to be created in the target version, with
the only restriction being that migrating to an older version of the
interpreter will not support more recent language constructs. The
parse trees are not typically compatible from one version to another,
whereas source code has always been forward-compatible.
Each element of the sequences returned by \function{ast2list()} or
\function{ast2tuple()} has a simple form. Sequences representing

14
Doc/lib/libsocket.tex
View File

@ -9,13 +9,13 @@ This module provides access to the BSD \emph{socket} interface.
It is available on \UNIX{} systems that support this interface.
For an introduction to socket programming (in C), see the following
papers: \emph{An Introductory 4.3BSD Interprocess Communication
Tutorial}, by Stuart Sechrest and \emph{An Advanced 4.3BSD Interprocess
Communication Tutorial}, by Samuel J. Leffler et al, both in the
\UNIX{} Programmer's Manual, Supplementary Documents 1 (sections PS1:7
and PS1:8). The \UNIX{} manual pages for the various socket-related
system calls are also a valuable source of information on the details of
socket semantics.
papers: \citetitle{An Introductory 4.3BSD Interprocess Communication
Tutorial}, by Stuart Sechrest and \citetitle{An Advanced 4.3BSD
Interprocess Communication Tutorial}, by Samuel J. Leffler et al,
both in the \citetitle{\UNIX{} Programmer's Manual, Supplementary Documents 1}
(sections PS1:7 and PS1:8). The \UNIX{} manual pages for the various
socket-related system calls are also a valuable source of information
on the details of socket semantics.
The Python interface is a straightforward transliteration of the
\UNIX{} system call and library interface for sockets to Python's

4
Doc/lib/libsocksvr.tex
View File

@ -16,8 +16,8 @@ lost while in transit. The more infrequently used
\class{UnixStreamServer} and \class{UnixDatagramServer} classes are
similar, but use \UNIX{} domain sockets; they're not available on
non-\UNIX{} platforms. For more details on network programming, consult
a book such as W. Richard Steven's \emph{UNIX Network Programming}
or Ralph Davis's \emph{Win32 Network Programming}.
a book such as W. Richard Steven's \citetitle{UNIX Network Programming}
or Ralph Davis's \citetitle{Win32 Network Programming}.
These four classes process requests \dfn{synchronously}; each request
must be completed before the next request can be started. This isn't

17
Doc/lib/libsoundex.tex
View File

@ -32,13 +32,12 @@ is equivalent to
\begin{seealso}
\seetext{Donald E. Knuth, \emph{Sorting and Searching,} vol. 3 in
``The Art of Computer Programming.'' Addison-Wesley Publishing
Company: Reading, MA: 1973. pp.\ 391-392. Discusses the origin and
usefulness of the algorithm, as well as the algorithm itself. Knuth
gives his sources as \emph{U.S. Patents 1261167} (1918) and
\emph{1435663} (1922), attributing the algorithm to Margaret K. Odell
and Robert C. Russel. Additional references are provided.}
\seetext{Donald E. Knuth, \citetitle{Sorting and Searching}, vol. 3
in ``The Art of Computer Programming.'' Addison-Wesley
Publishing Company: Reading, MA: 1973. pp.\ 391-392.
Discusses the origin and usefulness of the algorithm, as
well as the algorithm itself. Knuth gives his sources as
\emph{U.S. Patents 1261167} (1918) and \emph{1435663}
(1922), attributing the algorithm to Margaret K. Odell and
Robert C. Russel. Additional references are provided.}
\end{seealso}

38
Doc/lib/libstdtypes.tex
View File

@ -302,14 +302,14 @@ division by \code{pow(2, \var{n})} without overflow check.
There are three sequence types: strings, lists and tuples.
Strings literals are written in single or double quotes:
\code{'xyzzy'}, \code{"frobozz"}. See Chapter 2 of the \emph{Python
Reference Manual} for more about string literals. Lists are
constructed with square brackets, separating items with commas:
\code{[a, b, c]}. Tuples are constructed by the comma operator (not
within square brackets), with or without enclosing parentheses, but an
empty tuple must have the enclosing parentheses, e.g.,
\code{a, b, c} or \code{()}. A single item tuple must have a trailing
comma, e.g., \code{(d,)}.
\code{'xyzzy'}, \code{"frobozz"}. See Chapter 2 of the
\citetitle[../ref/ref.html]{Python Reference Manual} for more about
string literals. Lists are constructed with square brackets,
separating items with commas: \code{[a, b, c]}. Tuples are
constructed by the comma operator (not within square brackets), with
or without enclosing parentheses, but an empty tuple must have the
enclosing parentheses, e.g., \code{a, b, c} or \code{()}. A single
item tuple must have a trailing comma, e.g., \code{(d,)}.
\indexii{sequence}{types}
\indexii{string}{type}
\indexii{tuple}{type}
@ -629,7 +629,8 @@ written as \code{<module 'os' from '/usr/local/lib/python1.5/os.pyc'>}.
\subsubsection{Classes and Class Instances \label{typesobjects}}
\nodename{Classes and Instances}
See Chapters 3 and 7 of the \emph{Python Reference Manual} for these.
See Chapters 3 and 7 of the \citetitle[../ref/ref.html]{Python
Reference Manual} for these.
\subsubsection{Functions \label{typesfunctions}}
@ -667,7 +668,8 @@ implementing the method. Calling \code{\var{m}(\var{arg-1},
calling \code{\var{m}.im_func(\var{m}.im_self, \var{arg-1},
\var{arg-2}, \textrm{\ldots}, \var{arg-n})}.
See the \emph{Python Reference Manual} for more information.
See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
information.
\subsubsection{Code Objects \label{bltin-code-objects}}
@ -689,7 +691,8 @@ source string) to the \keyword{exec} statement or the built-in
\stindex{exec}
\bifuncindex{eval}
See the \emph{Python Reference Manual} for more information.
See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
information.
\subsubsection{Type Objects \label{bltin-type-objects}}
@ -715,9 +718,10 @@ It is written as \code{None}.
\subsubsection{The Ellipsis Object \label{bltin-ellipsis-object}}
This object is used by extended slice notation (see the \emph{Python
Reference Manual}). It supports no special operations. There is
exactly one ellipsis object, named \code{Ellipsis} (a built-in name).
This object is used by extended slice notation (see the
\citetitle[../ref/ref.html]{Python Reference Manual}). It supports no
special operations. There is exactly one ellipsis object, named
\constant{Ellipsis} (a built-in name).
It is written as \code{Ellipsis}.
@ -868,9 +872,9 @@ attribute.
\subsubsection{Internal Objects \label{typesinternal}}
See the \emph{Python Reference Manual} for this information. It
describes code objects, stack frame objects, traceback objects, and
slice objects.
See the \citetitle[../ref/ref.html]{Python Reference Manual} for this
information. It describes code objects, stack frame objects,
traceback objects, and slice objects.
\subsection{Special Attributes \label{specialattrs}}

5
Doc/lib/libundoc.tex
View File

@ -14,8 +14,9 @@ effort spent.
\begin{description}
\item[\module{Tkinter}]
--- Interface to Tcl/Tk for graphical user interfaces;
Fredrik Lundh is working on this one! See \emph{An Introduction to
--- Interface to Tcl/Tk for graphical user interfaces; Fredrik Lundh
is working on this one! See
\citetitle[http://www.pythonware.com/library/]{An Introduction to
Tkinter} at \url{http://www.pythonware.com/library/} for on-line
reference material.

20
Doc/lib/libwhrandom.tex
View File

@ -22,13 +22,9 @@ Returns the next random floating point number in the range [0.0 ... 1.0).
\end{funcdesc}
\begin{funcdesc}{seed}{x, y, z}
Initializes the random number generator from the integers
\var{x},
\var{y}
and
\var{z}.
When the module is first imported, the random number is initialized
using values derived from the current time.
Initializes the random number generator from the integers \var{x},
\var{y} and \var{z}. When the module is first imported, the random
number is initialized using values derived from the current time.
\end{funcdesc}
\begin{funcdesc}{uniform}{a, b}
@ -43,10 +39,10 @@ available at the module level. Therefore one can write either
generator = whrandom.whrandom()
N = generator.random()
\end{verbatim}
%
\begin{seealso}
\seemodule{random}{generators for various random distributions}
\seetext{Wichmann, B. A. \& Hill, I. D., ``Algorithm AS 183:
An efficient and portable pseudo-random number generator'',
\emph{Applied Statistics} 31 (1982) 188-190}
\seemodule{random}{generators for various random distributions}
\seetext{Wichmann, B. A. \& Hill, I. D., ``Algorithm AS 183:
An efficient and portable pseudo-random number generator'',
\citetitle{Applied Statistics} 31 (1982) 188-190.}
\end{seealso}

88
Doc/tut/tut.tex
View File

@ -48,11 +48,12 @@ Python interpreter handy for hands-on experience, but all examples are
self-contained, so the tutorial can be read off-line as well.
For a description of standard objects and modules, see the
\emph{Python Library Reference} document. The \emph{Python Reference
Manual} gives a more formal definition of the language. To write
extensions in C or \Cpp{}, read the \emph{Extending and Embedding} and
\emph{Python/C API} manuals. There are also several books covering
Python in depth.
\citetitle[../lib/lib.html]{Python Library Reference} document. The
\citetitle[../ref/ref.html]{Python Reference Manual} gives a more
formal definition of the language. To write extensions in C or
\Cpp{}, read \citetitle[../ext/ext.html]{Extending and Embedding the
Python Interpreter} and \citetitle[../api/api.html]{Python/C API
Reference}. There are also several books covering Python in depth.
This tutorial does not attempt to be comprehensive and cover every
single feature, or even every commonly used feature. Instead, it
@ -60,7 +61,8 @@ introduces many of Python's most noteworthy features, and will give
you a good idea of the language's flavor and style. After reading it,
you will be able to read and write Python modules and programs, and
you will be ready to learn more about the various Python library
modules described in the \emph{Python Library Reference}.
modules described in the \citetitle[../lib/lib.html]{Python Library
Reference}.
\end{abstract}
@ -196,11 +198,11 @@ a file as standard input, it reads and executes a \emph{script} from
that file.
A third way of starting the interpreter is
\samp{python -c command [arg] ...}, which
executes the statement(s) in \code{command}, analogous to the shell's
\code{-c} option. Since Python statements often contain spaces or other
characters that are special to the shell, it is best to quote
\code{command} in its entirety with double quotes.
\samp{\program{python} \programopt{-c} \var{command} [arg] ...}, which
executes the statement(s) in \var{command}, analogous to the shell's
\programopt{-c} option. Since Python statements often contain spaces
or other characters that are special to the shell, it is best to quote
\var{command} in its entirety with double quotes.
Note that there is a difference between \samp{python file} and
\samp{python <file}. In the latter case, input requests from the
@ -213,9 +215,9 @@ is connected to standard input of the Python interpreter.
When a script file is used, it is sometimes useful to be able to run
the script and enter interactive mode afterwards. This can be done by
passing \code{-i} before the script. (This does not work if the script
is read from standard input, for the same reason as explained in the
previous paragraph.)
passing \programopt{-i} before the script. (This does not work if the
script is read from standard input, for the same reason as explained
in the previous paragraph.)
\subsection{Argument Passing \label{argPassing}}
@ -224,11 +226,11 @@ arguments thereafter are passed to the script in the variable
\code{sys.argv}, which is a list of strings. Its length is at least
one; when no script and no arguments are given, \code{sys.argv[0]} is
an empty string. When the script name is given as \code{'-'} (meaning
standard input), \code{sys.argv[0]} is set to \code{'-'}. When \code{-c
command} is used, \code{sys.argv[0]} is set to \code{'-c'}. Options
found after \code{-c command} are not consumed by the Python
interpreter's option processing but left in \code{sys.argv} for the
command to handle.
standard input), \code{sys.argv[0]} is set to \code{'-'}. When
\programopt{-c} \var{command} is used, \code{sys.argv[0]} is set to
\code{'-c'}. Options found after \programopt{-c} \var{command} are
not consumed by the Python interpreter's option processing but left in
\code{sys.argv} for the command to handle.
\subsection{Interactive Mode \label{interactive}}
@ -1845,11 +1847,9 @@ If you intend to use a function often you can assign it to a local name:
\section{More on Modules \label{moreModules}}
A module can contain executable statements as well as function
definitions.
These statements are intended to initialize the module.
They are executed only the
\emph{first}
time the module is imported somewhere.\footnote{
definitions. These statements are intended to initialize the module.
They are executed only the \emph{first} time the module is imported
somewhere.\footnote{
In fact function definitions are also `statements' that are
`executed'; the execution enters the function name in the
module's global symbol table.
@ -1944,22 +1944,22 @@ Some tips for experts:
\begin{itemize}
\item
When the Python interpreter is invoked with the \code{-O} flag,
When the Python interpreter is invoked with the \programopt{-O} flag,
optimized code is generated and stored in \file{.pyo} files.
The optimizer currently doesn't help much; it only removes
\keyword{assert} statements and \code{SET_LINENO} instructions.
When \code{-O} is used, \emph{all} bytecode is optimized; \code{.pyc}
files are ignored and \code{.py} files are compiled to optimized
bytecode.
When \programopt{-O} is used, \emph{all} bytecode is optimized;
\code{.pyc} files are ignored and \code{.py} files are compiled to
optimized bytecode.
\item
Passing two \code{-O} flags to the Python interpreter (\code{-OO})
will cause the bytecode compiler to perform optimizations that could
in some rare cases result in malfunctioning programs. Currently only
\code{__doc__} strings are removed from the bytecode, resulting in more
compact \file{.pyo} files. Since some programs may rely on having
these available, you should only use this option if you know what
you're doing.
Passing two \programopt{-O} flags to the Python interpreter
(\programopt{-OO}) will cause the bytecode compiler to perform
optimizations that could in some rare cases result in malfunctioning
programs. Currently only \code{__doc__} strings are removed from the
bytecode, resulting in more compact \file{.pyo} files. Since some
programs may rely on having these available, you should only use this
option if you know what you're doing.
\item
A program doesn't run any faster when it is read from a
@ -1976,14 +1976,14 @@ script that imports that module.
\item
It is possible to have a file called \file{spam.pyc} (or
\file{spam.pyo} when \code{-O} is used) without a module
\file{spam.pyo} when \programopt{-O} is used) without a module
\file{spam.py} in the same module. This can be used to distribute
a library of Python code in a form that is moderately hard to reverse
engineer.
\item
The module \module{compileall}\refstmodindex{compileall} can create
\file{.pyc} files (or \file{.pyo} files when \code{-O} is used) for
\file{.pyc} files (or \file{.pyo} files when \programopt{-O} is used) for
all modules in a directory.
\end{itemize}
@ -1992,13 +1992,13 @@ all modules in a directory.
\section{Standard Modules \label{standardModules}}
Python comes with a library of standard modules, described in a separate
document, the \emph{Python Library Reference} (``Library Reference''
hereafter). Some modules are built into the interpreter; these
provide access to operations that are not part of the core of the
language but are nevertheless built in, either for efficiency or to
provide access to operating system primitives such as system calls.
The set of such modules is a configuration option; e.g., the
\module{amoeba} module is only provided on systems that somehow
document, the \citetitle[../lib/lib.html]{Python Library Reference}
(``Library Reference'' hereafter). Some modules are built into the
interpreter; these provide access to operations that are not part of
the core of the language but are nevertheless built in, either for
efficiency or to provide access to operating system primitives such as
system calls. The set of such modules is a configuration option; e.g.,
the \module{amoeba} module is only provided on systems that somehow
support Amoeba primitives. One particular module deserves some
attention: \module{sys}\refstmodindex{sys}, which is built into every
Python interpreter. The variables \code{sys.ps1} and