traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Use the new {methoddesc} and {memberdesc} environments as appropriate.

This commit is contained in:
Fred Drake 1998-03-27 05:27:08 +00:00
parent ec56109a0a
commit 8fe533e6a0
16 changed files with 402 additions and 414 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
Doc/lib/libformatter.tex
View File

@ -37,6 +37,7 @@ initialized.
One data element is defined at the module level: One data element is defined at the module level:
\begin{datadesc}{AS_IS} \begin{datadesc}{AS_IS}
Value which can be used in the font specification passed to the Value which can be used in the font specification passed to the
\code{push_font()} method described below, or as the new value to any \code{push_font()} method described below, or as the new value to any
@ -47,33 +48,30 @@ be called without having to track whether the property was changed.
The following attributes are defined for formatter instance objects: The following attributes are defined for formatter instance objects:
\setindexsubitem{(formatter attribute)}
\begin{datadesc}{writer} \begin{memberdesc}[formatter]{writer}
The writer instance with which the formatter interacts. The writer instance with which the formatter interacts.
\end{datadesc} \end{memberdesc}
\setindexsubitem{(formatter method)} \begin{methoddesc}[formatter]{end_paragraph}{blanklines}
\begin{funcdesc}{end_paragraph}{blanklines}
Close any open paragraphs and insert at least \var{blanklines} Close any open paragraphs and insert at least \var{blanklines}
before the next paragraph. before the next paragraph.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{add_line_break}{} \begin{methoddesc}[formatter]{add_line_break}{}
Add a hard line break if one does not already exist. This does not Add a hard line break if one does not already exist. This does not
break the logical paragraph. break the logical paragraph.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{add_hor_rule}{*args, **kw} \begin{methoddesc}[formatter]{add_hor_rule}{*args, **kw}
Insert a horizontal rule in the output. A hard break is inserted if Insert a horizontal rule in the output. A hard break is inserted if
there is data in the current paragraph, but the logical paragraph is there is data in the current paragraph, but the logical paragraph is
not broken. The arguments and keywords are passed on to the writer's not broken. The arguments and keywords are passed on to the writer's
\method{send_line_break()} method. \method{send_line_break()} method.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{add_flowing_data}{data} \begin{methoddesc}[formatter]{add_flowing_data}{data}
Provide data which should be formatted with collapsed whitespaces. Provide data which should be formatted with collapsed whitespaces.
Whitespace from preceeding and successive calls to Whitespace from preceeding and successive calls to
\method{add_flowing_data()} is considered as well when the whitespace \method{add_flowing_data()} is considered as well when the whitespace
@ -81,15 +79,15 @@ collapse is performed. The data which is passed to this method is
expected to be word-wrapped by the output device. Note that any expected to be word-wrapped by the output device. Note that any
word-wrapping still must be performed by the writer object due to the word-wrapping still must be performed by the writer object due to the
need to rely on device and font information. need to rely on device and font information.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{add_literal_data}{data} \begin{methoddesc}[formatter]{add_literal_data}{data}
Provide data which should be passed to the writer unchanged. Provide data which should be passed to the writer unchanged.
Whitespace, including newline and tab characters, are considered legal Whitespace, including newline and tab characters, are considered legal
in the value of \var{data}. in the value of \var{data}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{add_label_data}{format, counter} \begin{methoddesc}[formatter]{add_label_data}{format, counter}
Insert a label which should be placed to the left of the current left Insert a label which should be placed to the left of the current left
margin. This should be used for constructing bulleted or numbered margin. This should be used for constructing bulleted or numbered
lists. If the \var{format} value is a string, it is interpreted as a lists. If the \var{format} value is a string, it is interpreted as a
@ -111,74 +109,74 @@ lower case, respectively, and \character{I} and \character{i}
represent the counter value in Roman numerals, in upper and lower represent the counter value in Roman numerals, in upper and lower
case. Note that the alphabetic and roman transforms require that the case. Note that the alphabetic and roman transforms require that the
counter value be greater than zero. counter value be greater than zero.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{flush_softspace}{} \begin{methoddesc}[formatter]{flush_softspace}{}
Send any pending whitespace buffered from a previous call to Send any pending whitespace buffered from a previous call to
\method{add_flowing_data()} to the associated writer object. This \method{add_flowing_data()} to the associated writer object. This
should be called before any direct manipulation of the writer object. should be called before any direct manipulation of the writer object.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{push_alignment}{align} \begin{methoddesc}[formatter]{push_alignment}{align}
Push a new alignment setting onto the alignment stack. This may be Push a new alignment setting onto the alignment stack. This may be
\constant{AS_IS} if no change is desired. If the alignment value is \constant{AS_IS} if no change is desired. If the alignment value is
changed from the previous setting, the writer's \method{new_alignment()} changed from the previous setting, the writer's \method{new_alignment()}
method is called with the \var{align} value. method is called with the \var{align} value.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{pop_alignment}{} \begin{methoddesc}[formatter]{pop_alignment}{}
Restore the previous alignment. Restore the previous alignment.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{push_font}{\code{(}size, italic, bold, teletype\code{)}} \begin{methoddesc}[formatter]{push_font}{\code{(}size, italic, bold, teletype\code{)}}
Change some or all font properties of the writer object. Properties Change some or all font properties of the writer object. Properties
which are not set to \constant{AS_IS} are set to the values passed in which are not set to \constant{AS_IS} are set to the values passed in
while others are maintained at their current settings. The writer's while others are maintained at their current settings. The writer's
\method{new_font()} method is called with the fully resolved font \method{new_font()} method is called with the fully resolved font
specification. specification.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{pop_font}{} \begin{methoddesc}[formatter]{pop_font}{}
Restore the previous font. Restore the previous font.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{push_margin}{margin} \begin{methoddesc}[formatter]{push_margin}{margin}
Increase the number of left margin indentations by one, associating Increase the number of left margin indentations by one, associating
the logical tag \var{margin} with the new indentation. The initial the logical tag \var{margin} with the new indentation. The initial
margin level is \code{0}. Changed values of the logical tag must be margin level is \code{0}. Changed values of the logical tag must be
true values; false values other than \constant{AS_IS} are not true values; false values other than \constant{AS_IS} are not
sufficient to change the margin. sufficient to change the margin.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{pop_margin}{} \begin{methoddesc}[formatter]{pop_margin}{}
Restore the previous margin. Restore the previous margin.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{push_style}{*styles} \begin{methoddesc}[formatter]{push_style}{*styles}
Push any number of arbitrary style specifications. All styles are Push any number of arbitrary style specifications. All styles are
pushed onto the styles stack in order. A tuple representing the pushed onto the styles stack in order. A tuple representing the
entire stack, including \constant{AS_IS} values, is passed to the entire stack, including \constant{AS_IS} values, is passed to the
writer's \method{new_styles()} method. writer's \method{new_styles()} method.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{pop_style}{\optional{n\code{ = 1}}} \begin{methoddesc}[formatter]{pop_style}{\optional{n\code{ = 1}}}
Pop the last \var{n} style specifications passed to Pop the last \var{n} style specifications passed to
\method{push_style()}. A tuple representing the revised stack, \method{push_style()}. A tuple representing the revised stack,
including \constant{AS_IS} values, is passed to the writer's including \constant{AS_IS} values, is passed to the writer's
\method{new_styles()} method. \method{new_styles()} method.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{set_spacing}{spacing} \begin{methoddesc}[formatter]{set_spacing}{spacing}
Set the spacing style for the writer. Set the spacing style for the writer.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{assert_line_data}{\optional{flag\code{ = 1}}} \begin{methoddesc}[formatter]{assert_line_data}{\optional{flag\code{ = 1}}}
Inform the formatter that data has been added to the current paragraph Inform the formatter that data has been added to the current paragraph
out-of-band. This should be used when the writer has been manipulated out-of-band. This should be used when the writer has been manipulated
directly. The optional \var{flag} argument can be set to false if directly. The optional \var{flag} argument can be set to false if
the writer manipulations produced a hard line break at the end of the the writer manipulations produced a hard line break at the end of the
output. output.
\end{funcdesc} \end{methoddesc}
\subsection{Formatter Implementations} \subsection{Formatter Implementations}
@ -213,21 +211,20 @@ Note that while most applications can use the
\class{AbstractFormatter} class as a formatter, the writer must \class{AbstractFormatter} class as a formatter, the writer must
typically be provided by the application. typically be provided by the application.
\setindexsubitem{(writer method)}
\begin{funcdesc}{flush}{} \begin{methoddesc}[writer]{flush}{}
Flush any buffered output or device control events. Flush any buffered output or device control events.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{new_alignment}{align} \begin{methoddesc}[writer]{new_alignment}{align}
Set the alignment style. The \var{align} value can be any object, Set the alignment style. The \var{align} value can be any object,
but by convention is a string or \code{None}, where \code{None} but by convention is a string or \code{None}, where \code{None}
indicates that the writer's ``preferred'' alignment should be used. indicates that the writer's ``preferred'' alignment should be used.
Conventional \var{align} values are \code{'left'}, \code{'center'}, Conventional \var{align} values are \code{'left'}, \code{'center'},
\code{'right'}, and \code{'justify'}. \code{'right'}, and \code{'justify'}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{new_font}{font} \begin{methoddesc}[writer]{new_font}{font}
Set the font style. The value of \var{font} will be \code{None}, Set the font style. The value of \var{font} will be \code{None},
indicating that the device's default font should be used, or a tuple indicating that the device's default font should be used, or a tuple
of the form \code{(}\var{size}, \var{italic}, \var{bold}, of the form \code{(}\var{size}, \var{italic}, \var{bold},
@ -236,67 +233,67 @@ font that should be used; specific strings and their interpretation
must be defined by the application. The \var{italic}, \var{bold}, and must be defined by the application. The \var{italic}, \var{bold}, and
\var{teletype} values are boolean indicators specifying which of those \var{teletype} values are boolean indicators specifying which of those
font attributes should be used. font attributes should be used.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{new_margin}{margin, level} \begin{methoddesc}[writer]{new_margin}{margin, level}
Set the margin level to the integer \var{level} and the logical tag Set the margin level to the integer \var{level} and the logical tag
to \var{margin}. Interpretation of the logical tag is at the to \var{margin}. Interpretation of the logical tag is at the
writer's discretion; the only restriction on the value of the logical writer's discretion; the only restriction on the value of the logical
tag is that it not be a false value for non-zero values of tag is that it not be a false value for non-zero values of
\var{level}. \var{level}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{new_spacing}{spacing} \begin{methoddesc}[writer]{new_spacing}{spacing}
Set the spacing style to \var{spacing}. Set the spacing style to \var{spacing}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{new_styles}{styles} \begin{methoddesc}[writer]{new_styles}{styles}
Set additional styles. The \var{styles} value is a tuple of Set additional styles. The \var{styles} value is a tuple of
arbitrary values; the value \constant{AS_IS} should be ignored. The arbitrary values; the value \constant{AS_IS} should be ignored. The
\var{styles} tuple may be interpreted either as a set or as a stack \var{styles} tuple may be interpreted either as a set or as a stack
depending on the requirements of the application and writer depending on the requirements of the application and writer
implementation. implementation.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{send_line_break}{} \begin{methoddesc}[writer]{send_line_break}{}
Break the current line. Break the current line.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{send_paragraph}{blankline} \begin{methoddesc}[writer]{send_paragraph}{blankline}
Produce a paragraph separation of at least \var{blankline} blank Produce a paragraph separation of at least \var{blankline} blank
lines, or the equivelent. The \var{blankline} value will be an lines, or the equivelent. The \var{blankline} value will be an
integer. integer.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{send_hor_rule}{*args, **kw} \begin{methoddesc}[writer]{send_hor_rule}{*args, **kw}
Display a horizontal rule on the output device. The arguments to this Display a horizontal rule on the output device. The arguments to this
method are entirely application- and writer-specific, and should be method are entirely application- and writer-specific, and should be
interpreted with care. The method implementation may assume that a interpreted with care. The method implementation may assume that a
line break has already been issued via \method{send_line_break()}. line break has already been issued via \method{send_line_break()}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{send_flowing_data}{data} \begin{methoddesc}[writer]{send_flowing_data}{data}
Output character data which may be word-wrapped and re-flowed as Output character data which may be word-wrapped and re-flowed as
needed. Within any sequence of calls to this method, the writer may needed. Within any sequence of calls to this method, the writer may
assume that spans of multiple whitespace characters have been assume that spans of multiple whitespace characters have been
collapsed to single space characters. collapsed to single space characters.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{send_literal_data}{data} \begin{methoddesc}[writer]{send_literal_data}{data}
Output character data which has already been formatted Output character data which has already been formatted
for display. Generally, this should be interpreted to mean that line for display. Generally, this should be interpreted to mean that line
breaks indicated by newline characters should be preserved and no new breaks indicated by newline characters should be preserved and no new
line breaks should be introduced. The data may contain embedded line breaks should be introduced. The data may contain embedded
newline and tab characters, unlike data provided to the newline and tab characters, unlike data provided to the
\method{send_formatted_data()} interface. \method{send_formatted_data()} interface.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{send_label_data}{data} \begin{methoddesc}[writer]{send_label_data}{data}
Set \var{data} to the left of the current left margin, if possible. Set \var{data} to the left of the current left margin, if possible.
The value of \var{data} is not restricted; treatment of non-string The value of \var{data} is not restricted; treatment of non-string
values is entirely application- and writer-dependent. This method values is entirely application- and writer-dependent. This method
will only be called at the beginning of a line. will only be called at the beginning of a line.
\end{funcdesc} \end{methoddesc}
\subsection{Writer Implementations} \subsection{Writer Implementations}

31
Doc/lib/libhtmllib.tex
View File

@ -70,53 +70,50 @@ handlers for all HTML 2.0 and many HTML 3.0 and 3.2 elements.
In addition to tag methods, the \class{HTMLParser} class provides some In addition to tag methods, the \class{HTMLParser} class provides some
additional methods and instance variables for use within tag methods. additional methods and instance variables for use within tag methods.
\setindexsubitem{(HTMLParser attribute)} \begin{memberdesc}{formatter}
\begin{datadesc}{formatter}
This is the formatter instance associated with the parser. This is the formatter instance associated with the parser.
\end{datadesc} \end{memberdesc}
\begin{datadesc}{nofill} \begin{memberdesc}{nofill}
Boolean flag which should be true when whitespace should not be Boolean flag which should be true when whitespace should not be
collapsed, or false when it should be. In general, this should only collapsed, or false when it should be. In general, this should only
be true when character data is to be treated as ``preformatted'' text, be true when character data is to be treated as ``preformatted'' text,
as within a \code{<PRE>} element. The default value is false. This as within a \code{<PRE>} element. The default value is false. This
affects the operation of \method{handle_data()} and \method{save_end()}. affects the operation of \method{handle_data()} and \method{save_end()}.
\end{datadesc} \end{memberdesc}
\setindexsubitem{(HTMLParser method)}
\begin{funcdesc}{anchor_bgn}{href, name, type} \begin{methoddesc}{anchor_bgn}{href, name, type}
This method is called at the start of an anchor region. The arguments This method is called at the start of an anchor region. The arguments
correspond to the attributes of the \code{<A>} tag with the same correspond to the attributes of the \code{<A>} tag with the same
names. The default implementation maintains a list of hyperlinks names. The default implementation maintains a list of hyperlinks
(defined by the \code{href} attribute) within the document. The list (defined by the \code{href} attribute) within the document. The list
of hyperlinks is available as the data attribute \code{anchorlist}. of hyperlinks is available as the data attribute \code{anchorlist}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{anchor_end}{} \begin{methoddesc}{anchor_end}{}
This method is called at the end of an anchor region. The default This method is called at the end of an anchor region. The default
implementation adds a textual footnote marker using an index into the implementation adds a textual footnote marker using an index into the
list of hyperlinks created by \method{anchor_bgn()}. list of hyperlinks created by \method{anchor_bgn()}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{handle_image}{source, alt\optional{, ismap\optional{, align\optional{, width\optional{, height}}}}} \begin{methoddesc}{handle_image}{source, alt\optional{, ismap\optional{, align\optional{, width\optional{, height}}}}}
This method is called to handle images. The default implementation This method is called to handle images. The default implementation
simply passes the \var{alt} value to the \method{handle_data()} simply passes the \var{alt} value to the \method{handle_data()}
method. method.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{save_bgn}{} \begin{methoddesc}{save_bgn}{}
Begins saving character data in a buffer instead of sending it to the Begins saving character data in a buffer instead of sending it to the
formatter object. Retrieve the stored data via \method{save_end()}. formatter object. Retrieve the stored data via \method{save_end()}.
Use of the \method{save_bgn()} / \method{save_end()} pair may not be Use of the \method{save_bgn()} / \method{save_end()} pair may not be
nested. nested.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{save_end}{} \begin{methoddesc}{save_end}{}
Ends buffering character data and returns all data saved since the Ends buffering character data and returns all data saved since the
preceeding call to \method{save_bgn()}. If the \code{nofill} flag is preceeding call to \method{save_bgn()}. If the \code{nofill} flag is
false, whitespace is collapsed to single spaces. A call to this false, whitespace is collapsed to single spaces. A call to this
method without a preceeding call to \method{save_bgn()} will raise a method without a preceeding call to \method{save_bgn()} will raise a
\exception{TypeError} exception. \exception{TypeError} exception.
\end{funcdesc} \end{methoddesc}

19
Doc/lib/libpprint.tex
View File

@ -142,32 +142,31 @@ l/lib/python1.4/test', '/usr/local/lib/python1.4/sunos5', '/usr/local/lib/python
\class{PrettyPrinter} instances have the following methods: \class{PrettyPrinter} instances have the following methods:
\setindexsubitem{(PrettyPrinter method)}
\begin{funcdesc}{pformat}{object} \begin{methoddesc}{pformat}{object}
Return the formatted representation of \var{object}. This takes into Return the formatted representation of \var{object}. This takes into
account the options passed to the \class{PrettyPrinter} constructor. Account the options passed to the \class{PrettyPrinter} constructor.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{pprint}{object} \begin{methoddesc}{pprint}{object}
Print the formatted representation of \var{object} on the configured Print the formatted representation of \var{object} on the configured
stream, followed by a newline. stream, followed by a newline.
\end{funcdesc} \end{methoddesc}
The following methods provide the implementations for the The following methods provide the implementations for the
corresponding functions of the same names. Using these methods on an corresponding functions of the same names. Using these methods on an
instance is slightly more efficient since new \class{PrettyPrinter} instance is slightly more efficient since new \class{PrettyPrinter}
objects don't need to be created. objects don't need to be created.
\begin{funcdesc}{isreadable}{object} \begin{methoddesc}{isreadable}{object}
Determine if the formatted representation of the object is Determine if the formatted representation of the object is
``readable,'' or can be used to reconstruct the value using ``readable,'' or can be used to reconstruct the value using
\function{eval()}\bifuncindex{eval}. Note that this returns false for \function{eval()}\bifuncindex{eval}. Note that this returns false for
recursive objects. If the \var{depth} parameter of the recursive objects. If the \var{depth} parameter of the
\class{PrettyPrinter} is set and the object is deeper than allowed, \class{PrettyPrinter} is set and the object is deeper than allowed,
this returns false. this returns false.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{isrecursive}{object} \begin{methoddesc}{isrecursive}{object}
Determine if the object requires a recursive representation. Determine if the object requires a recursive representation.
\end{funcdesc} \end{methoddesc}

44
Doc/lib/libprofile.tex
View File

@ -1,7 +1,5 @@
\chapter{The Python Profiler} \chapter{The Python Profiler}
\label{profile} \label{profile}
\stmodindex{profile}
\stmodindex{pstats}
Copyright \copyright{} 1994, by InfoSeek Corporation, all rights reserved. Copyright \copyright{} 1994, by InfoSeek Corporation, all rights reserved.
@ -256,8 +254,9 @@ of algorithms to be directly compared to iterative implementations.
\section{Reference Manual} \section{Reference Manual}
\stmodindex{profile}
\label{module-profile}
\setindexsubitem{(in module profile)}
The primary entry point for the profiler is the global function The primary entry point for the profiler is the global function
\function{profile.run()}. It is typically used to create any profile \function{profile.run()}. It is typically used to create any profile
@ -269,7 +268,7 @@ Profiler Extensions, which includes discussion of how to derive
``better'' profilers from the classes presented, or reading the source ``better'' profilers from the classes presented, or reading the source
code for these modules. code for these modules.
\begin{funcdesc}{profile.run}{string\optional{, filename\optional{, ...}}} \begin{funcdesc}{run}{string\optional{, filename\optional{, ...}}}
This function takes a single argument that has can be passed to the This function takes a single argument that has can be passed to the
\keyword{exec} statement, and an optional file name. In all cases this \keyword{exec} statement, and an optional file name. In all cases this
@ -336,7 +335,8 @@ printed.
Analysis of the profiler data is done using this class from the Analysis of the profiler data is done using this class from the
\module{pstats} module: \module{pstats} module:
\setindexsubitem{(in module pstats)} % now switch modules....
\stmodindex{pstats}
\begin{classdesc}{Stats}{filename\optional{, ...}} \begin{classdesc}{Stats}{filename\optional{, ...}}
This class constructor creates an instance of a ``statistics object'' This class constructor creates an instance of a ``statistics object''
@ -361,7 +361,7 @@ need to be combined with data in an existing \class{Stats} object, the
\setindexsubitem{(Stats method)} \setindexsubitem{(Stats method)}
\begin{funcdesc}{strip_dirs}{} \begin{methoddesc}{strip_dirs}{}
This method for the \class{Stats} class removes all leading path This method for the \class{Stats} class removes all leading path
information from file names. It is very useful in reducing the size information from file names. It is very useful in reducing the size
of the printout to fit within (close to) 80 columns. This method of the printout to fit within (close to) 80 columns. This method
@ -372,19 +372,19 @@ initialization and loading. If \method{strip_dirs()} causes two
function names to be indistinguishable (i.e., they are on the same function names to be indistinguishable (i.e., they are on the same
line of the same filename, and have the same function name), then the line of the same filename, and have the same function name), then the
statistics for these two entries are accumulated into a single entry. statistics for these two entries are accumulated into a single entry.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{add}{filename\optional{, ...}} \begin{methoddesc}{add}{filename\optional{, ...}}
This method of the \class{Stats} class accumulates additional This method of the \class{Stats} class accumulates additional
profiling information into the current profiling object. Its profiling information into the current profiling object. Its
arguments should refer to filenames created by the corresponding arguments should refer to filenames created by the corresponding
version of \function{profile.run()}. Statistics for identically named version of \function{profile.run()}. Statistics for identically named
(re: file, line, name) functions are automatically accumulated into (re: file, line, name) functions are automatically accumulated into
single function statistics. single function statistics.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{sort_stats}{key\optional{, ...}} \begin{methoddesc}{sort_stats}{key\optional{, ...}}
This method modifies the \class{Stats} object by sorting it according This method modifies the \class{Stats} object by sorting it according
to the supplied criteria. The argument is typically a string to the supplied criteria. The argument is typically a string
identifying the basis of a sort (example: \code{"time"} or identifying the basis of a sort (example: \code{"time"} or
@ -430,18 +430,18 @@ interpreted as \code{"stdname"}, \code{"calls"}, \code{"time"}, and
\code{"cumulative"} respectively. If this old style format (numeric) \code{"cumulative"} respectively. If this old style format (numeric)
is used, only one sort key (the numeric key) will be used, and is used, only one sort key (the numeric key) will be used, and
additional arguments will be silently ignored. additional arguments will be silently ignored.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{reverse_order}{} \begin{methoddesc}{reverse_order}{}
This method for the \class{Stats} class reverses the ordering of the basic This method for the \class{Stats} class reverses the ordering of the basic
list within the object. This method is provided primarily for list within the object. This method is provided primarily for
compatibility with the old profiler. Its utility is questionable compatibility with the old profiler. Its utility is questionable
now that ascending vs descending order is properly selected based on now that ascending vs descending order is properly selected based on
the sort key of choice. the sort key of choice.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{print_stats}{restriction\optional{, ...}} \begin{methoddesc}{print_stats}{restriction\optional{, ...}}
This method for the \class{Stats} class prints out a report as described This method for the \class{Stats} class prints out a report as described
in the \function{profile.run()} definition. in the \function{profile.run()} definition.
@ -473,10 +473,10 @@ print_stats("foo:", .1)
would limit the list to all functions having file names \samp{.*foo:}, would limit the list to all functions having file names \samp{.*foo:},
and then proceed to only print the first 10\% of them. and then proceed to only print the first 10\% of them.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{print_callers}{restrictions\optional{, ...}} \begin{methoddesc}{print_callers}{restrictions\optional{, ...}}
This method for the \class{Stats} class prints a list of all functions This method for the \class{Stats} class prints a list of all functions
that called each function in the profiled database. The ordering is that called each function in the profiled database. The ordering is
identical to that provided by \method{print_stats()}, and the definition identical to that provided by \method{print_stats()}, and the definition
@ -484,16 +484,16 @@ of the restricting argument is also identical. For convenience, a
number is shown in parentheses after each caller to show how many number is shown in parentheses after each caller to show how many
times this specific call was made. A second non-parenthesized number times this specific call was made. A second non-parenthesized number
is the cumulative time spent in the function at the right. is the cumulative time spent in the function at the right.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{print_callees}{restrictions\optional{, ...}} \begin{methoddesc}{print_callees}{restrictions\optional{, ...}}
This method for the \class{Stats} class prints a list of all function This method for the \class{Stats} class prints a list of all function
that were called by the indicated function. Aside from this reversal that were called by the indicated function. Aside from this reversal
of direction of calls (re: called vs was called by), the arguments and of direction of calls (re: called vs was called by), the arguments and
ordering are identical to the \method{print_callers()} method. ordering are identical to the \method{print_callers()} method.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{ignore}{} \begin{methoddesc}{ignore}{}
This method of the \class{Stats} class is used to dispose of the value This method of the \class{Stats} class is used to dispose of the value
returned by earlier methods. All standard methods in this class returned by earlier methods. All standard methods in this class
return the instance that is being processed, so that the commands can return the instance that is being processed, so that the commands can
@ -503,7 +503,7 @@ be strung together. For example:
pstats.Stats('foofile').strip_dirs().sort_stats('cum') \ pstats.Stats('foofile').strip_dirs().sort_stats('cum') \
.print_stats().ignore() .print_stats().ignore()
\end{verbatim} \end{verbatim}
%
would perform all the indicated functions, but it would not return would perform all the indicated functions, but it would not return
the final reference to the \class{Stats} instance.% the final reference to the \class{Stats} instance.%
\footnote{ \footnote{
@ -511,7 +511,7 @@ This was once necessary, when Python would print any unused expression
result that was not \code{None}. The method is still defined for result that was not \code{None}. The method is still defined for
backward compatibility. backward compatibility.
} }
\end{funcdesc} \end{methoddesc}
\section{Limitations} \section{Limitations}

26
Doc/lib/libqueue.tex
View File

@ -37,34 +37,32 @@ other queue organizations (e.g. stack) but the inheritable interface
is not described here. See the source code for details. The public is not described here. See the source code for details. The public
methods are: methods are:
\setindexsubitem{(Queue method)} \begin{methoddesc}{qsize}{}
\begin{funcdesc}{qsize}{}
Returns the approximate size of the queue. Because of multithreading Returns the approximate size of the queue. Because of multithreading
semantics, this number is not reliable. semantics, this number is not reliable.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{empty}{} \begin{methoddesc}{empty}{}
Returns \code{1} if the queue is empty, \code{0} otherwise. Because Returns \code{1} if the queue is empty, \code{0} otherwise. Because
of multithreading semantics, this is not reliable. of multithreading semantics, this is not reliable.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{full}{} \begin{methoddesc}{full}{}
Returns \code{1} if the queue is full, \code{0} otherwise. Because of Returns \code{1} if the queue is full, \code{0} otherwise. Because of
multithreading semantics, this is not reliable. multithreading semantics, this is not reliable.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{put}{item} \begin{methoddesc}{put}{item}
Puts \var{item} into the queue. Puts \var{item} into the queue.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{get}{} \begin{methoddesc}{get}{}
Gets and returns an item from the queue, blocking if necessary until Gets and returns an item from the queue, blocking if necessary until
one is available. one is available.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{get_nowait}{} \begin{methoddesc}{get_nowait}{}
Gets and returns an item from the queue if one is immediately Gets and returns an item from the queue if one is immediately
available. Raises an \exception{Empty} exception if the queue is available. Raises an \exception{Empty} exception if the queue is
empty or if the queue's emptiness cannot be determined. empty or if the queue's emptiness cannot be determined.
\end{funcdesc} \end{methoddesc}

77
Doc/lib/libsgmllib.tex
View File

@ -38,37 +38,36 @@ spaces, tabs, and newlines are allowed between the trailing
\class{SGMLParser} instances have the following interface methods: \class{SGMLParser} instances have the following interface methods:
\setindexsubitem{(SGMLParser method)}
\begin{funcdesc}{reset}{} \begin{methoddesc}{reset}{}
Reset the instance. Loses all unprocessed data. This is called Reset the instance. Loses all unprocessed data. This is called
implicitly at instantiation time. implicitly at instantiation time.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{setnomoretags}{} \begin{methoddesc}{setnomoretags}{}
Stop processing tags. Treat all following input as literal input Stop processing tags. Treat all following input as literal input
(CDATA). (This is only provided so the HTML tag \code{<PLAINTEXT>} (CDATA). (This is only provided so the HTML tag \code{<PLAINTEXT>}
can be implemented.) can be implemented.)
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{setliteral}{} \begin{methoddesc}{setliteral}{}
Enter literal mode (CDATA mode). Enter literal mode (CDATA mode).
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{feed}{data} \begin{methoddesc}{feed}{data}
Feed some text to the parser. It is processed insofar as it consists Feed some text to the parser. It is processed insofar as it consists
of complete elements; incomplete data is buffered until more data is of complete elements; incomplete data is buffered until more data is
fed or \method{close()} is called. fed or \method{close()} is called.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{close}{} \begin{methoddesc}{close}{}
Force processing of all buffered data as if it were followed by an Force processing of all buffered data as if it were followed by an
end-of-file mark. This method may be redefined by a derived class to end-of-file mark. This method may be redefined by a derived class to
define additional processing at the end of the input, but the define additional processing at the end of the input, but the
redefined version should always call \method{close()}. redefined version should always call \method{close()}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{handle_starttag}{tag, method, attributes} \begin{methoddesc}{handle_starttag}{tag, method, attributes}
This method is called to handle start tags for which either a This method is called to handle start tags for which either a
\code{start_\var{tag}()} or \code{do_\var{tag}()} method has been \code{start_\var{tag}()} or \code{do_\var{tag}()} method has been
defined. The \var{tag} argument is the name of the tag converted to defined. The \var{tag} argument is the name of the tag converted to
@ -82,9 +81,9 @@ instance, for the tag \code{<A HREF="http://www.cwi.nl/">}, this
method would be called as \samp{unknown_starttag('a', [('href', method would be called as \samp{unknown_starttag('a', [('href',
'http://www.cwi.nl/')])}. The base implementation simply calls 'http://www.cwi.nl/')])}. The base implementation simply calls
\var{method} with \var{attributes} as the only argument. \var{method} with \var{attributes} as the only argument.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{handle_endtag}{tag, method} \begin{methoddesc}{handle_endtag}{tag, method}
This method is called to handle endtags for which an This method is called to handle endtags for which an
\code{end_\var{tag}()} method has been defined. The \var{tag} \code{end_\var{tag}()} method has been defined. The \var{tag}
argument is the name of the tag converted to lower case, and the argument is the name of the tag converted to lower case, and the
@ -93,15 +92,15 @@ support semantic interpretation of the end tag. If no
\code{end_\var{tag}()} method is defined for the closing element, \code{end_\var{tag}()} method is defined for the closing element,
this handler is not called. The base implementation simply calls this handler is not called. The base implementation simply calls
\var{method}. \var{method}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{handle_data}{data} \begin{methoddesc}{handle_data}{data}
This method is called to process arbitrary data. It is intended to be This method is called to process arbitrary data. It is intended to be
overridden by a derived class; the base class implementation does overridden by a derived class; the base class implementation does
nothing. nothing.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{handle_charref}{ref} \begin{methoddesc}{handle_charref}{ref}
This method is called to process a character reference of the form This method is called to process a character reference of the form
\samp{\&\#\var{ref};}. In the base implementation, \var{ref} must \samp{\&\#\var{ref};}. In the base implementation, \var{ref} must
be a decimal number in the be a decimal number in the
@ -111,9 +110,9 @@ method \method{handle_data()} with the character as argument. If
\code{unknown_charref(\var{ref})} is called to handle the error. A \code{unknown_charref(\var{ref})} is called to handle the error. A
subclass must override this method to provide support for named subclass must override this method to provide support for named
character entities. character entities.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{handle_entityref}{ref} \begin{methoddesc}{handle_entityref}{ref}
This method is called to process a general entity reference of the This method is called to process a general entity reference of the
form \samp{\&\var{ref};} where \var{ref} is an general entity form \samp{\&\var{ref};} where \var{ref} is an general entity
reference. It looks for \var{ref} in the instance (or class) reference. It looks for \var{ref} in the instance (or class)
@ -124,46 +123,46 @@ with the translation; otherwise, it calls the method
\code{unknown_entityref(\var{ref})}. The default \member{entitydefs} \code{unknown_entityref(\var{ref})}. The default \member{entitydefs}
defines translations for \code{\&amp;}, \code{\&apos}, \code{\&gt;}, defines translations for \code{\&amp;}, \code{\&apos}, \code{\&gt;},
\code{\&lt;}, and \code{\&quot;}. \code{\&lt;}, and \code{\&quot;}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{handle_comment}{comment} \begin{methoddesc}{handle_comment}{comment}
This method is called when a comment is encountered. The This method is called when a comment is encountered. The
\var{comment} argument is a string containing the text between the \var{comment} argument is a string containing the text between the
\samp{<!--} and \samp{-->} delimiters, but not the delimiters \samp{<!--} and \samp{-->} delimiters, but not the delimiters
themselves. For example, the comment \samp{<!--text-->} will themselves. For example, the comment \samp{<!--text-->} will
cause this method to be called with the argument \code{'text'}. The cause this method to be called with the argument \code{'text'}. The
default method does nothing. default method does nothing.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{report_unbalanced}{tag} \begin{methoddesc}{report_unbalanced}{tag}
This method is called when an end tag is found which does not This method is called when an end tag is found which does not
correspond to any open element. correspond to any open element.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{unknown_starttag}{tag, attributes} \begin{methoddesc}{unknown_starttag}{tag, attributes}
This method is called to process an unknown start tag. It is intended This method is called to process an unknown start tag. It is intended
to be overridden by a derived class; the base class implementation to be overridden by a derived class; the base class implementation
does nothing. does nothing.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{unknown_endtag}{tag} \begin{methoddesc}{unknown_endtag}{tag}
This method is called to process an unknown end tag. It is intended This method is called to process an unknown end tag. It is intended
to be overridden by a derived class; the base class implementation to be overridden by a derived class; the base class implementation
does nothing. does nothing.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{unknown_charref}{ref} \begin{methoddesc}{unknown_charref}{ref}
This method is called to process unresolvable numeric character This method is called to process unresolvable numeric character
references. Refer to \method{handle_charref()} to determine what is references. Refer to \method{handle_charref()} to determine what is
handled by default. It is intended to be overridden by a derived handled by default. It is intended to be overridden by a derived
class; the base class implementation does nothing. class; the base class implementation does nothing.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{unknown_entityref}{ref} \begin{methoddesc}{unknown_entityref}{ref}
This method is called to process an unknown entity reference. It is This method is called to process an unknown entity reference. It is
intended to be overridden by a derived class; the base class intended to be overridden by a derived class; the base class
implementation does nothing. implementation does nothing.
\end{funcdesc} \end{methoddesc}
Apart from overriding or extending the methods listed above, derived Apart from overriding or extending the methods listed above, derived
classes may also define methods of the following form to define classes may also define methods of the following form to define
@ -171,22 +170,22 @@ processing of specific tags. Tag names in the input stream are case
independent; the \var{tag} occurring in method names must be in lower independent; the \var{tag} occurring in method names must be in lower
case: case:
\begin{funcdescni}{start_\var{tag}}{attributes} \begin{methoddescni}{start_\var{tag}}{attributes}
This method is called to process an opening tag \var{tag}. It has This method is called to process an opening tag \var{tag}. It has
preference over \code{do_\var{tag}()}. The \var{attributes} preference over \code{do_\var{tag}()}. The \var{attributes}
argument has the same meaning as described for argument has the same meaning as described for
\method{handle_starttag()} above. \method{handle_starttag()} above.
\end{funcdescni} \end{methoddescni}
\begin{funcdescni}{do_\var{tag}}{attributes} \begin{methoddescni}{do_\var{tag}}{attributes}
This method is called to process an opening tag \var{tag} that does This method is called to process an opening tag \var{tag} that does
not come with a matching closing tag. The \var{attributes} argument not come with a matching closing tag. The \var{attributes} argument
has the same meaning as described for \method{handle_starttag()} above. has the same meaning as described for \method{handle_starttag()} above.
\end{funcdescni} \end{methoddescni}
\begin{funcdescni}{end_\var{tag}}{} \begin{methoddescni}{end_\var{tag}}{}
This method is called to process a closing tag \var{tag}. This method is called to process a closing tag \var{tag}.
\end{funcdescni} \end{methoddescni}
Note that the parser maintains a stack of open elements for which no Note that the parser maintains a stack of open elements for which no
end tag has been found yet. Only tags processed by end tag has been found yet. Only tags processed by

20
Doc/lib/libstrio.tex
View File

@ -3,15 +3,21 @@
\stmodindex{StringIO} \stmodindex{StringIO}
This module implements a file-like class, \code{StringIO}, This module implements a file-like class, \class{StringIO},
that reads and writes a string buffer (also known as \emph{memory that reads and writes a string buffer (also known as \emph{memory
files}). See the description on file objects for operations. files}). See the description on file objects for operations.
When a \code{StringIO} object is created, it can be initialized \begin{classdesc}{StringIO}{\optional{buffer}}
When a \class{StringIO} object is created, it can be initialized
to an existing string by passing the string to the constructor. to an existing string by passing the string to the constructor.
If no string is given, the \code{StringIO} will start empty. If no string is given, the \class{StringIO} will start empty.
\end{classdesc}
The method \code{getvalue()} can be called to retrieve the entire \begin{methoddesc}{getvalue}{}
contents of the ``file'' at any time before the \code{StringIO} Retrieve the entire contents of the ``file'' at any time before the
object's \code{close()} method is called. Calling \code{close()} will \class{StringIO} object's \method{close()} method is called.
free the memory buffer. \end{methoddesc}
\begin{methoddesc}{close}{}
Free the memory buffer.
\end{methoddesc}

66
Doc/lib/libtypes.tex
View File

@ -707,30 +707,28 @@ device or writing a file opened for reading.
Files have the following methods: Files have the following methods:
\setindexsubitem{(file method)} \begin{methoddesc}[file]{close}{}
\begin{funcdesc}{close}{}
Close the file. A closed file cannot be read or written anymore. Close the file. A closed file cannot be read or written anymore.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{flush}{} \begin{methoddesc}[file]{flush}{}
Flush the internal buffer, like \code{stdio}'s \code{fflush()}. Flush the internal buffer, like \code{stdio}'s \code{fflush()}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{isatty}{} \begin{methoddesc}[file]{isatty}{}
Return \code{1} if the file is connected to a tty(-like) device, else Return \code{1} if the file is connected to a tty(-like) device, else
\code{0}. \code{0}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{fileno}{} \begin{methoddesc}[file]{fileno}{}
Return the integer ``file descriptor'' that is used by the underlying Return the integer ``file descriptor'' that is used by the underlying
implementation to request I/O operations from the operating system. implementation to request I/O operations from the operating system.
This can be useful for other, lower level interfaces that use file This can be useful for other, lower level interfaces that use file
descriptors, e.g. module \code{fcntl} or \code{os.read()} and friends. descriptors, e.g. module \code{fcntl} or \code{os.read()} and friends.
\refbimodindex{fcntl} \refbimodindex{fcntl}
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{read}{\optional{size}} \begin{methoddesc}[file]{read}{\optional{size}}
Read at most \var{size} bytes from the file (less if the read hits Read at most \var{size} bytes from the file (less if the read hits
\EOF{} or no more data is immediately available on a pipe, tty or \EOF{} or no more data is immediately available on a pipe, tty or
similar device). If the \var{size} argument is negative or omitted, similar device). If the \var{size} argument is negative or omitted,
@ -738,9 +736,9 @@ descriptors, e.g. module \code{fcntl} or \code{os.read()} and friends.
object. An empty string is returned when \EOF{} is encountered object. An empty string is returned when \EOF{} is encountered
immediately. (For certain files, like ttys, it makes sense to immediately. (For certain files, like ttys, it makes sense to
continue reading after an \EOF{} is hit.) continue reading after an \EOF{} is hit.)
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{readline}{\optional{size}} \begin{methoddesc}[file]{readline}{\optional{size}}
Read one entire line from the file. A trailing newline character is Read one entire line from the file. A trailing newline character is
kept in the string% kept in the string%
\footnote{The advantage of leaving the newline on is that an empty string \footnote{The advantage of leaving the newline on is that an empty string
@ -757,71 +755,71 @@ descriptors, e.g. module \code{fcntl} or \code{os.read()} and friends.
immediately. Note: unlike \code{stdio}'s \code{fgets()}, the returned immediately. Note: unlike \code{stdio}'s \code{fgets()}, the returned
string contains null characters (\code{'\e 0'}) if they occurred in the string contains null characters (\code{'\e 0'}) if they occurred in the
input. input.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{readlines}{\optional{sizehint}} \begin{methoddesc}[file]{readlines}{\optional{sizehint}}
Read until \EOF{} using \code{readline()} and return a list containing Read until \EOF{} using \code{readline()} and return a list containing
the lines thus read. If the optional \var{sizehint} argument is the lines thus read. If the optional \var{sizehint} argument is
present, instead of reading up to \EOF{}, whole lines totalling present, instead of reading up to \EOF{}, whole lines totalling
approximately \var{sizehint} bytes (possibly after rounding up to an approximately \var{sizehint} bytes (possibly after rounding up to an
internal buffer size) are read. internal buffer size) are read.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{seek}{offset, whence} \begin{methoddesc}[file]{seek}{offset, whence}
Set the file's current position, like \code{stdio}'s \code{fseek()}. Set the file's current position, like \code{stdio}'s \code{fseek()}.
The \var{whence} argument is optional and defaults to \code{0} The \var{whence} argument is optional and defaults to \code{0}
(absolute file positioning); other values are \code{1} (seek (absolute file positioning); other values are \code{1} (seek
relative to the current position) and \code{2} (seek relative to the relative to the current position) and \code{2} (seek relative to the
file's end). There is no return value. file's end). There is no return value.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{tell}{} \begin{methoddesc}[file]{tell}{}
Return the file's current position, like \code{stdio}'s \code{ftell()}. Return the file's current position, like \code{stdio}'s \code{ftell()}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{truncate}{\optional{size}} \begin{methoddesc}[file]{truncate}{\optional{size}}
Truncate the file's size. If the optional size argument present, the Truncate the file's size. If the optional size argument present, the
file is truncated to (at most) that size. The size defaults to the file is truncated to (at most) that size. The size defaults to the
current position. Availability of this function depends on the current position. Availability of this function depends on the
operating system version (e.g., not all \UNIX{} versions support this operating system version (e.g., not all \UNIX{} versions support this
operation). operation).
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{write}{str} \begin{methoddesc}[file]{write}{str}
Write a string to the file. There is no return value. Note: due to Write a string to the file. There is no return value. Note: due to
buffering, the string may not actually show up in the file until buffering, the string may not actually show up in the file until
the \code{flush()} or \code{close()} method is called. the \code{flush()} or \code{close()} method is called.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{writelines}{list} \begin{methoddesc}[file]{writelines}{list}
Write a list of strings to the file. There is no return value. Write a list of strings to the file. There is no return value.
(The name is intended to match \code{readlines}; \code{writelines} (The name is intended to match \code{readlines}; \code{writelines}
does not add line separators.) does not add line separators.)
\end{funcdesc} \end{methoddesc}
File objects also offer the following attributes: File objects also offer the following attributes:
\setindexsubitem{(file attribute)} \setindexsubitem{(file attribute)}
\begin{datadesc}{closed} \begin{memberdesc}[file]{closed}
Boolean indicating the current state of the file object. This is a Boolean indicating the current state of the file object. This is a
read-only attribute; the \method{close()} method changes the value. read-only attribute; the \method{close()} method changes the value.
\end{datadesc} \end{memberdesc}
\begin{datadesc}{mode} \begin{memberdesc}[file]{mode}
The I/O mode for the file. If the file was created using the The I/O mode for the file. If the file was created using the
\function{open()} built-in function, this will be the value of the \function{open()} built-in function, this will be the value of the
\var{mode} parameter. This is a read-only attribute. \var{mode} parameter. This is a read-only attribute.
\end{datadesc} \end{memberdesc}
\begin{datadesc}{name} \begin{memberdesc}[file]{name}
If the file object was created using \function{open()}, the name of If the file object was created using \function{open()}, the name of
the file. Otherwise, some string that indicates the source of the the file. Otherwise, some string that indicates the source of the
file object, of the form \samp{<\mbox{\ldots}>}. This is a read-only file object, of the form \samp{<\mbox{\ldots}>}. This is a read-only
attribute. attribute.
\end{datadesc} \end{memberdesc}
\begin{datadesc}{softspace} \begin{memberdesc}[file]{softspace}
Boolean that indicates whether a space character needs to be printed Boolean that indicates whether a space character needs to be printed
before another value when using the \keyword{print} statement. before another value when using the \keyword{print} statement.
Classes that are trying to simulate a file object should also have a Classes that are trying to simulate a file object should also have a
@ -829,7 +827,7 @@ writable \code{softspace} attribute, which should be initialized to
zero. This will be automatic for classes implemented in Python; types zero. This will be automatic for classes implemented in Python; types
implemented in \C{} will have to provide a writable \code{softspace} implemented in \C{} will have to provide a writable \code{softspace}
attribute. attribute.
\end{datadesc} \end{memberdesc}
\subsubsection{Internal Objects} \subsubsection{Internal Objects}

125
Doc/libformatter.tex
View File

@ -37,6 +37,7 @@ initialized.
One data element is defined at the module level: One data element is defined at the module level:
\begin{datadesc}{AS_IS} \begin{datadesc}{AS_IS}
Value which can be used in the font specification passed to the Value which can be used in the font specification passed to the
\code{push_font()} method described below, or as the new value to any \code{push_font()} method described below, or as the new value to any
@ -47,33 +48,30 @@ be called without having to track whether the property was changed.
The following attributes are defined for formatter instance objects: The following attributes are defined for formatter instance objects:
\setindexsubitem{(formatter attribute)}
\begin{datadesc}{writer} \begin{memberdesc}[formatter]{writer}
The writer instance with which the formatter interacts. The writer instance with which the formatter interacts.
\end{datadesc} \end{memberdesc}
\setindexsubitem{(formatter method)} \begin{methoddesc}[formatter]{end_paragraph}{blanklines}
\begin{funcdesc}{end_paragraph}{blanklines}
Close any open paragraphs and insert at least \var{blanklines} Close any open paragraphs and insert at least \var{blanklines}
before the next paragraph. before the next paragraph.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{add_line_break}{} \begin{methoddesc}[formatter]{add_line_break}{}
Add a hard line break if one does not already exist. This does not Add a hard line break if one does not already exist. This does not
break the logical paragraph. break the logical paragraph.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{add_hor_rule}{*args, **kw} \begin{methoddesc}[formatter]{add_hor_rule}{*args, **kw}
Insert a horizontal rule in the output. A hard break is inserted if Insert a horizontal rule in the output. A hard break is inserted if
there is data in the current paragraph, but the logical paragraph is there is data in the current paragraph, but the logical paragraph is
not broken. The arguments and keywords are passed on to the writer's not broken. The arguments and keywords are passed on to the writer's
\method{send_line_break()} method. \method{send_line_break()} method.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{add_flowing_data}{data} \begin{methoddesc}[formatter]{add_flowing_data}{data}
Provide data which should be formatted with collapsed whitespaces. Provide data which should be formatted with collapsed whitespaces.
Whitespace from preceeding and successive calls to Whitespace from preceeding and successive calls to
\method{add_flowing_data()} is considered as well when the whitespace \method{add_flowing_data()} is considered as well when the whitespace
@ -81,15 +79,15 @@ collapse is performed. The data which is passed to this method is
expected to be word-wrapped by the output device. Note that any expected to be word-wrapped by the output device. Note that any
word-wrapping still must be performed by the writer object due to the word-wrapping still must be performed by the writer object due to the
need to rely on device and font information. need to rely on device and font information.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{add_literal_data}{data} \begin{methoddesc}[formatter]{add_literal_data}{data}
Provide data which should be passed to the writer unchanged. Provide data which should be passed to the writer unchanged.
Whitespace, including newline and tab characters, are considered legal Whitespace, including newline and tab characters, are considered legal
in the value of \var{data}. in the value of \var{data}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{add_label_data}{format, counter} \begin{methoddesc}[formatter]{add_label_data}{format, counter}
Insert a label which should be placed to the left of the current left Insert a label which should be placed to the left of the current left
margin. This should be used for constructing bulleted or numbered margin. This should be used for constructing bulleted or numbered
lists. If the \var{format} value is a string, it is interpreted as a lists. If the \var{format} value is a string, it is interpreted as a
@ -111,74 +109,74 @@ lower case, respectively, and \character{I} and \character{i}
represent the counter value in Roman numerals, in upper and lower represent the counter value in Roman numerals, in upper and lower
case. Note that the alphabetic and roman transforms require that the case. Note that the alphabetic and roman transforms require that the
counter value be greater than zero. counter value be greater than zero.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{flush_softspace}{} \begin{methoddesc}[formatter]{flush_softspace}{}
Send any pending whitespace buffered from a previous call to Send any pending whitespace buffered from a previous call to
\method{add_flowing_data()} to the associated writer object. This \method{add_flowing_data()} to the associated writer object. This
should be called before any direct manipulation of the writer object. should be called before any direct manipulation of the writer object.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{push_alignment}{align} \begin{methoddesc}[formatter]{push_alignment}{align}
Push a new alignment setting onto the alignment stack. This may be Push a new alignment setting onto the alignment stack. This may be
\constant{AS_IS} if no change is desired. If the alignment value is \constant{AS_IS} if no change is desired. If the alignment value is
changed from the previous setting, the writer's \method{new_alignment()} changed from the previous setting, the writer's \method{new_alignment()}
method is called with the \var{align} value. method is called with the \var{align} value.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{pop_alignment}{} \begin{methoddesc}[formatter]{pop_alignment}{}
Restore the previous alignment. Restore the previous alignment.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{push_font}{\code{(}size, italic, bold, teletype\code{)}} \begin{methoddesc}[formatter]{push_font}{\code{(}size, italic, bold, teletype\code{)}}
Change some or all font properties of the writer object. Properties Change some or all font properties of the writer object. Properties
which are not set to \constant{AS_IS} are set to the values passed in which are not set to \constant{AS_IS} are set to the values passed in
while others are maintained at their current settings. The writer's while others are maintained at their current settings. The writer's
\method{new_font()} method is called with the fully resolved font \method{new_font()} method is called with the fully resolved font
specification. specification.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{pop_font}{} \begin{methoddesc}[formatter]{pop_font}{}
Restore the previous font. Restore the previous font.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{push_margin}{margin} \begin{methoddesc}[formatter]{push_margin}{margin}
Increase the number of left margin indentations by one, associating Increase the number of left margin indentations by one, associating
the logical tag \var{margin} with the new indentation. The initial the logical tag \var{margin} with the new indentation. The initial
margin level is \code{0}. Changed values of the logical tag must be margin level is \code{0}. Changed values of the logical tag must be
true values; false values other than \constant{AS_IS} are not true values; false values other than \constant{AS_IS} are not
sufficient to change the margin. sufficient to change the margin.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{pop_margin}{} \begin{methoddesc}[formatter]{pop_margin}{}
Restore the previous margin. Restore the previous margin.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{push_style}{*styles} \begin{methoddesc}[formatter]{push_style}{*styles}
Push any number of arbitrary style specifications. All styles are Push any number of arbitrary style specifications. All styles are
pushed onto the styles stack in order. A tuple representing the pushed onto the styles stack in order. A tuple representing the
entire stack, including \constant{AS_IS} values, is passed to the entire stack, including \constant{AS_IS} values, is passed to the
writer's \method{new_styles()} method. writer's \method{new_styles()} method.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{pop_style}{\optional{n\code{ = 1}}} \begin{methoddesc}[formatter]{pop_style}{\optional{n\code{ = 1}}}
Pop the last \var{n} style specifications passed to Pop the last \var{n} style specifications passed to
\method{push_style()}. A tuple representing the revised stack, \method{push_style()}. A tuple representing the revised stack,
including \constant{AS_IS} values, is passed to the writer's including \constant{AS_IS} values, is passed to the writer's
\method{new_styles()} method. \method{new_styles()} method.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{set_spacing}{spacing} \begin{methoddesc}[formatter]{set_spacing}{spacing}
Set the spacing style for the writer. Set the spacing style for the writer.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{assert_line_data}{\optional{flag\code{ = 1}}} \begin{methoddesc}[formatter]{assert_line_data}{\optional{flag\code{ = 1}}}
Inform the formatter that data has been added to the current paragraph Inform the formatter that data has been added to the current paragraph
out-of-band. This should be used when the writer has been manipulated out-of-band. This should be used when the writer has been manipulated
directly. The optional \var{flag} argument can be set to false if directly. The optional \var{flag} argument can be set to false if
the writer manipulations produced a hard line break at the end of the the writer manipulations produced a hard line break at the end of the
output. output.
\end{funcdesc} \end{methoddesc}
\subsection{Formatter Implementations} \subsection{Formatter Implementations}
@ -213,21 +211,20 @@ Note that while most applications can use the
\class{AbstractFormatter} class as a formatter, the writer must \class{AbstractFormatter} class as a formatter, the writer must
typically be provided by the application. typically be provided by the application.
\setindexsubitem{(writer method)}
\begin{funcdesc}{flush}{} \begin{methoddesc}[writer]{flush}{}
Flush any buffered output or device control events. Flush any buffered output or device control events.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{new_alignment}{align} \begin{methoddesc}[writer]{new_alignment}{align}
Set the alignment style. The \var{align} value can be any object, Set the alignment style. The \var{align} value can be any object,
but by convention is a string or \code{None}, where \code{None} but by convention is a string or \code{None}, where \code{None}
indicates that the writer's ``preferred'' alignment should be used. indicates that the writer's ``preferred'' alignment should be used.
Conventional \var{align} values are \code{'left'}, \code{'center'}, Conventional \var{align} values are \code{'left'}, \code{'center'},
\code{'right'}, and \code{'justify'}. \code{'right'}, and \code{'justify'}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{new_font}{font} \begin{methoddesc}[writer]{new_font}{font}
Set the font style. The value of \var{font} will be \code{None}, Set the font style. The value of \var{font} will be \code{None},
indicating that the device's default font should be used, or a tuple indicating that the device's default font should be used, or a tuple
of the form \code{(}\var{size}, \var{italic}, \var{bold}, of the form \code{(}\var{size}, \var{italic}, \var{bold},
@ -236,67 +233,67 @@ font that should be used; specific strings and their interpretation
must be defined by the application. The \var{italic}, \var{bold}, and must be defined by the application. The \var{italic}, \var{bold}, and
\var{teletype} values are boolean indicators specifying which of those \var{teletype} values are boolean indicators specifying which of those
font attributes should be used. font attributes should be used.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{new_margin}{margin, level} \begin{methoddesc}[writer]{new_margin}{margin, level}
Set the margin level to the integer \var{level} and the logical tag Set the margin level to the integer \var{level} and the logical tag
to \var{margin}. Interpretation of the logical tag is at the to \var{margin}. Interpretation of the logical tag is at the
writer's discretion; the only restriction on the value of the logical writer's discretion; the only restriction on the value of the logical
tag is that it not be a false value for non-zero values of tag is that it not be a false value for non-zero values of
\var{level}. \var{level}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{new_spacing}{spacing} \begin{methoddesc}[writer]{new_spacing}{spacing}
Set the spacing style to \var{spacing}. Set the spacing style to \var{spacing}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{new_styles}{styles} \begin{methoddesc}[writer]{new_styles}{styles}
Set additional styles. The \var{styles} value is a tuple of Set additional styles. The \var{styles} value is a tuple of
arbitrary values; the value \constant{AS_IS} should be ignored. The arbitrary values; the value \constant{AS_IS} should be ignored. The
\var{styles} tuple may be interpreted either as a set or as a stack \var{styles} tuple may be interpreted either as a set or as a stack
depending on the requirements of the application and writer depending on the requirements of the application and writer
implementation. implementation.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{send_line_break}{} \begin{methoddesc}[writer]{send_line_break}{}
Break the current line. Break the current line.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{send_paragraph}{blankline} \begin{methoddesc}[writer]{send_paragraph}{blankline}
Produce a paragraph separation of at least \var{blankline} blank Produce a paragraph separation of at least \var{blankline} blank
lines, or the equivelent. The \var{blankline} value will be an lines, or the equivelent. The \var{blankline} value will be an
integer. integer.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{send_hor_rule}{*args, **kw} \begin{methoddesc}[writer]{send_hor_rule}{*args, **kw}
Display a horizontal rule on the output device. The arguments to this Display a horizontal rule on the output device. The arguments to this
method are entirely application- and writer-specific, and should be method are entirely application- and writer-specific, and should be
interpreted with care. The method implementation may assume that a interpreted with care. The method implementation may assume that a
line break has already been issued via \method{send_line_break()}. line break has already been issued via \method{send_line_break()}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{send_flowing_data}{data} \begin{methoddesc}[writer]{send_flowing_data}{data}
Output character data which may be word-wrapped and re-flowed as Output character data which may be word-wrapped and re-flowed as
needed. Within any sequence of calls to this method, the writer may needed. Within any sequence of calls to this method, the writer may
assume that spans of multiple whitespace characters have been assume that spans of multiple whitespace characters have been
collapsed to single space characters. collapsed to single space characters.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{send_literal_data}{data} \begin{methoddesc}[writer]{send_literal_data}{data}
Output character data which has already been formatted Output character data which has already been formatted
for display. Generally, this should be interpreted to mean that line for display. Generally, this should be interpreted to mean that line
breaks indicated by newline characters should be preserved and no new breaks indicated by newline characters should be preserved and no new
line breaks should be introduced. The data may contain embedded line breaks should be introduced. The data may contain embedded
newline and tab characters, unlike data provided to the newline and tab characters, unlike data provided to the
\method{send_formatted_data()} interface. \method{send_formatted_data()} interface.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{send_label_data}{data} \begin{methoddesc}[writer]{send_label_data}{data}
Set \var{data} to the left of the current left margin, if possible. Set \var{data} to the left of the current left margin, if possible.
The value of \var{data} is not restricted; treatment of non-string The value of \var{data} is not restricted; treatment of non-string
values is entirely application- and writer-dependent. This method values is entirely application- and writer-dependent. This method
will only be called at the beginning of a line. will only be called at the beginning of a line.
\end{funcdesc} \end{methoddesc}
\subsection{Writer Implementations} \subsection{Writer Implementations}

31
Doc/libhtmllib.tex
View File

@ -70,53 +70,50 @@ handlers for all HTML 2.0 and many HTML 3.0 and 3.2 elements.
In addition to tag methods, the \class{HTMLParser} class provides some In addition to tag methods, the \class{HTMLParser} class provides some
additional methods and instance variables for use within tag methods. additional methods and instance variables for use within tag methods.
\setindexsubitem{(HTMLParser attribute)} \begin{memberdesc}{formatter}
\begin{datadesc}{formatter}
This is the formatter instance associated with the parser. This is the formatter instance associated with the parser.
\end{datadesc} \end{memberdesc}
\begin{datadesc}{nofill} \begin{memberdesc}{nofill}
Boolean flag which should be true when whitespace should not be Boolean flag which should be true when whitespace should not be
collapsed, or false when it should be. In general, this should only collapsed, or false when it should be. In general, this should only
be true when character data is to be treated as ``preformatted'' text, be true when character data is to be treated as ``preformatted'' text,
as within a \code{<PRE>} element. The default value is false. This as within a \code{<PRE>} element. The default value is false. This
affects the operation of \method{handle_data()} and \method{save_end()}. affects the operation of \method{handle_data()} and \method{save_end()}.
\end{datadesc} \end{memberdesc}
\setindexsubitem{(HTMLParser method)}
\begin{funcdesc}{anchor_bgn}{href, name, type} \begin{methoddesc}{anchor_bgn}{href, name, type}
This method is called at the start of an anchor region. The arguments This method is called at the start of an anchor region. The arguments
correspond to the attributes of the \code{<A>} tag with the same correspond to the attributes of the \code{<A>} tag with the same
names. The default implementation maintains a list of hyperlinks names. The default implementation maintains a list of hyperlinks
(defined by the \code{href} attribute) within the document. The list (defined by the \code{href} attribute) within the document. The list
of hyperlinks is available as the data attribute \code{anchorlist}. of hyperlinks is available as the data attribute \code{anchorlist}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{anchor_end}{} \begin{methoddesc}{anchor_end}{}
This method is called at the end of an anchor region. The default This method is called at the end of an anchor region. The default
implementation adds a textual footnote marker using an index into the implementation adds a textual footnote marker using an index into the
list of hyperlinks created by \method{anchor_bgn()}. list of hyperlinks created by \method{anchor_bgn()}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{handle_image}{source, alt\optional{, ismap\optional{, align\optional{, width\optional{, height}}}}} \begin{methoddesc}{handle_image}{source, alt\optional{, ismap\optional{, align\optional{, width\optional{, height}}}}}
This method is called to handle images. The default implementation This method is called to handle images. The default implementation
simply passes the \var{alt} value to the \method{handle_data()} simply passes the \var{alt} value to the \method{handle_data()}
method. method.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{save_bgn}{} \begin{methoddesc}{save_bgn}{}
Begins saving character data in a buffer instead of sending it to the Begins saving character data in a buffer instead of sending it to the
formatter object. Retrieve the stored data via \method{save_end()}. formatter object. Retrieve the stored data via \method{save_end()}.
Use of the \method{save_bgn()} / \method{save_end()} pair may not be Use of the \method{save_bgn()} / \method{save_end()} pair may not be
nested. nested.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{save_end}{} \begin{methoddesc}{save_end}{}
Ends buffering character data and returns all data saved since the Ends buffering character data and returns all data saved since the
preceeding call to \method{save_bgn()}. If the \code{nofill} flag is preceeding call to \method{save_bgn()}. If the \code{nofill} flag is
false, whitespace is collapsed to single spaces. A call to this false, whitespace is collapsed to single spaces. A call to this
method without a preceeding call to \method{save_bgn()} will raise a method without a preceeding call to \method{save_bgn()} will raise a
\exception{TypeError} exception. \exception{TypeError} exception.
\end{funcdesc} \end{methoddesc}

19
Doc/libpprint.tex
View File

@ -142,32 +142,31 @@ l/lib/python1.4/test', '/usr/local/lib/python1.4/sunos5', '/usr/local/lib/python
\class{PrettyPrinter} instances have the following methods: \class{PrettyPrinter} instances have the following methods:
\setindexsubitem{(PrettyPrinter method)}
\begin{funcdesc}{pformat}{object} \begin{methoddesc}{pformat}{object}
Return the formatted representation of \var{object}. This takes into Return the formatted representation of \var{object}. This takes into
account the options passed to the \class{PrettyPrinter} constructor. Account the options passed to the \class{PrettyPrinter} constructor.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{pprint}{object} \begin{methoddesc}{pprint}{object}
Print the formatted representation of \var{object} on the configured Print the formatted representation of \var{object} on the configured
stream, followed by a newline. stream, followed by a newline.
\end{funcdesc} \end{methoddesc}
The following methods provide the implementations for the The following methods provide the implementations for the
corresponding functions of the same names. Using these methods on an corresponding functions of the same names. Using these methods on an
instance is slightly more efficient since new \class{PrettyPrinter} instance is slightly more efficient since new \class{PrettyPrinter}
objects don't need to be created. objects don't need to be created.
\begin{funcdesc}{isreadable}{object} \begin{methoddesc}{isreadable}{object}
Determine if the formatted representation of the object is Determine if the formatted representation of the object is
``readable,'' or can be used to reconstruct the value using ``readable,'' or can be used to reconstruct the value using
\function{eval()}\bifuncindex{eval}. Note that this returns false for \function{eval()}\bifuncindex{eval}. Note that this returns false for
recursive objects. If the \var{depth} parameter of the recursive objects. If the \var{depth} parameter of the
\class{PrettyPrinter} is set and the object is deeper than allowed, \class{PrettyPrinter} is set and the object is deeper than allowed,
this returns false. this returns false.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{isrecursive}{object} \begin{methoddesc}{isrecursive}{object}
Determine if the object requires a recursive representation. Determine if the object requires a recursive representation.
\end{funcdesc} \end{methoddesc}

44
Doc/libprofile.tex
View File

@ -1,7 +1,5 @@
\chapter{The Python Profiler} \chapter{The Python Profiler}
\label{profile} \label{profile}
\stmodindex{profile}
\stmodindex{pstats}
Copyright \copyright{} 1994, by InfoSeek Corporation, all rights reserved. Copyright \copyright{} 1994, by InfoSeek Corporation, all rights reserved.
@ -256,8 +254,9 @@ of algorithms to be directly compared to iterative implementations.
\section{Reference Manual} \section{Reference Manual}
\stmodindex{profile}
\label{module-profile}
\setindexsubitem{(in module profile)}
The primary entry point for the profiler is the global function The primary entry point for the profiler is the global function
\function{profile.run()}. It is typically used to create any profile \function{profile.run()}. It is typically used to create any profile
@ -269,7 +268,7 @@ Profiler Extensions, which includes discussion of how to derive
``better'' profilers from the classes presented, or reading the source ``better'' profilers from the classes presented, or reading the source
code for these modules. code for these modules.
\begin{funcdesc}{profile.run}{string\optional{, filename\optional{, ...}}} \begin{funcdesc}{run}{string\optional{, filename\optional{, ...}}}
This function takes a single argument that has can be passed to the This function takes a single argument that has can be passed to the
\keyword{exec} statement, and an optional file name. In all cases this \keyword{exec} statement, and an optional file name. In all cases this
@ -336,7 +335,8 @@ printed.
Analysis of the profiler data is done using this class from the Analysis of the profiler data is done using this class from the
\module{pstats} module: \module{pstats} module:
\setindexsubitem{(in module pstats)} % now switch modules....
\stmodindex{pstats}
\begin{classdesc}{Stats}{filename\optional{, ...}} \begin{classdesc}{Stats}{filename\optional{, ...}}
This class constructor creates an instance of a ``statistics object'' This class constructor creates an instance of a ``statistics object''
@ -361,7 +361,7 @@ need to be combined with data in an existing \class{Stats} object, the
\setindexsubitem{(Stats method)} \setindexsubitem{(Stats method)}
\begin{funcdesc}{strip_dirs}{} \begin{methoddesc}{strip_dirs}{}
This method for the \class{Stats} class removes all leading path This method for the \class{Stats} class removes all leading path
information from file names. It is very useful in reducing the size information from file names. It is very useful in reducing the size
of the printout to fit within (close to) 80 columns. This method of the printout to fit within (close to) 80 columns. This method
@ -372,19 +372,19 @@ initialization and loading. If \method{strip_dirs()} causes two
function names to be indistinguishable (i.e., they are on the same function names to be indistinguishable (i.e., they are on the same
line of the same filename, and have the same function name), then the line of the same filename, and have the same function name), then the
statistics for these two entries are accumulated into a single entry. statistics for these two entries are accumulated into a single entry.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{add}{filename\optional{, ...}} \begin{methoddesc}{add}{filename\optional{, ...}}
This method of the \class{Stats} class accumulates additional This method of the \class{Stats} class accumulates additional
profiling information into the current profiling object. Its profiling information into the current profiling object. Its
arguments should refer to filenames created by the corresponding arguments should refer to filenames created by the corresponding
version of \function{profile.run()}. Statistics for identically named version of \function{profile.run()}. Statistics for identically named
(re: file, line, name) functions are automatically accumulated into (re: file, line, name) functions are automatically accumulated into
single function statistics. single function statistics.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{sort_stats}{key\optional{, ...}} \begin{methoddesc}{sort_stats}{key\optional{, ...}}
This method modifies the \class{Stats} object by sorting it according This method modifies the \class{Stats} object by sorting it according
to the supplied criteria. The argument is typically a string to the supplied criteria. The argument is typically a string
identifying the basis of a sort (example: \code{"time"} or identifying the basis of a sort (example: \code{"time"} or
@ -430,18 +430,18 @@ interpreted as \code{"stdname"}, \code{"calls"}, \code{"time"}, and
\code{"cumulative"} respectively. If this old style format (numeric) \code{"cumulative"} respectively. If this old style format (numeric)
is used, only one sort key (the numeric key) will be used, and is used, only one sort key (the numeric key) will be used, and
additional arguments will be silently ignored. additional arguments will be silently ignored.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{reverse_order}{} \begin{methoddesc}{reverse_order}{}
This method for the \class{Stats} class reverses the ordering of the basic This method for the \class{Stats} class reverses the ordering of the basic
list within the object. This method is provided primarily for list within the object. This method is provided primarily for
compatibility with the old profiler. Its utility is questionable compatibility with the old profiler. Its utility is questionable
now that ascending vs descending order is properly selected based on now that ascending vs descending order is properly selected based on
the sort key of choice. the sort key of choice.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{print_stats}{restriction\optional{, ...}} \begin{methoddesc}{print_stats}{restriction\optional{, ...}}
This method for the \class{Stats} class prints out a report as described This method for the \class{Stats} class prints out a report as described
in the \function{profile.run()} definition. in the \function{profile.run()} definition.
@ -473,10 +473,10 @@ print_stats("foo:", .1)
would limit the list to all functions having file names \samp{.*foo:}, would limit the list to all functions having file names \samp{.*foo:},
and then proceed to only print the first 10\% of them. and then proceed to only print the first 10\% of them.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{print_callers}{restrictions\optional{, ...}} \begin{methoddesc}{print_callers}{restrictions\optional{, ...}}
This method for the \class{Stats} class prints a list of all functions This method for the \class{Stats} class prints a list of all functions
that called each function in the profiled database. The ordering is that called each function in the profiled database. The ordering is
identical to that provided by \method{print_stats()}, and the definition identical to that provided by \method{print_stats()}, and the definition
@ -484,16 +484,16 @@ of the restricting argument is also identical. For convenience, a
number is shown in parentheses after each caller to show how many number is shown in parentheses after each caller to show how many
times this specific call was made. A second non-parenthesized number times this specific call was made. A second non-parenthesized number
is the cumulative time spent in the function at the right. is the cumulative time spent in the function at the right.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{print_callees}{restrictions\optional{, ...}} \begin{methoddesc}{print_callees}{restrictions\optional{, ...}}
This method for the \class{Stats} class prints a list of all function This method for the \class{Stats} class prints a list of all function
that were called by the indicated function. Aside from this reversal that were called by the indicated function. Aside from this reversal
of direction of calls (re: called vs was called by), the arguments and of direction of calls (re: called vs was called by), the arguments and
ordering are identical to the \method{print_callers()} method. ordering are identical to the \method{print_callers()} method.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{ignore}{} \begin{methoddesc}{ignore}{}
This method of the \class{Stats} class is used to dispose of the value This method of the \class{Stats} class is used to dispose of the value
returned by earlier methods. All standard methods in this class returned by earlier methods. All standard methods in this class
return the instance that is being processed, so that the commands can return the instance that is being processed, so that the commands can
@ -503,7 +503,7 @@ be strung together. For example:
pstats.Stats('foofile').strip_dirs().sort_stats('cum') \ pstats.Stats('foofile').strip_dirs().sort_stats('cum') \
.print_stats().ignore() .print_stats().ignore()
\end{verbatim} \end{verbatim}
%
would perform all the indicated functions, but it would not return would perform all the indicated functions, but it would not return
the final reference to the \class{Stats} instance.% the final reference to the \class{Stats} instance.%
\footnote{ \footnote{
@ -511,7 +511,7 @@ This was once necessary, when Python would print any unused expression
result that was not \code{None}. The method is still defined for result that was not \code{None}. The method is still defined for
backward compatibility. backward compatibility.
} }
\end{funcdesc} \end{methoddesc}
\section{Limitations} \section{Limitations}

26
Doc/libqueue.tex
View File

@ -37,34 +37,32 @@ other queue organizations (e.g. stack) but the inheritable interface
is not described here. See the source code for details. The public is not described here. See the source code for details. The public
methods are: methods are:
\setindexsubitem{(Queue method)} \begin{methoddesc}{qsize}{}
\begin{funcdesc}{qsize}{}
Returns the approximate size of the queue. Because of multithreading Returns the approximate size of the queue. Because of multithreading
semantics, this number is not reliable. semantics, this number is not reliable.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{empty}{} \begin{methoddesc}{empty}{}
Returns \code{1} if the queue is empty, \code{0} otherwise. Because Returns \code{1} if the queue is empty, \code{0} otherwise. Because
of multithreading semantics, this is not reliable. of multithreading semantics, this is not reliable.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{full}{} \begin{methoddesc}{full}{}
Returns \code{1} if the queue is full, \code{0} otherwise. Because of Returns \code{1} if the queue is full, \code{0} otherwise. Because of
multithreading semantics, this is not reliable. multithreading semantics, this is not reliable.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{put}{item} \begin{methoddesc}{put}{item}
Puts \var{item} into the queue. Puts \var{item} into the queue.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{get}{} \begin{methoddesc}{get}{}
Gets and returns an item from the queue, blocking if necessary until Gets and returns an item from the queue, blocking if necessary until
one is available. one is available.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{get_nowait}{} \begin{methoddesc}{get_nowait}{}
Gets and returns an item from the queue if one is immediately Gets and returns an item from the queue if one is immediately
available. Raises an \exception{Empty} exception if the queue is available. Raises an \exception{Empty} exception if the queue is
empty or if the queue's emptiness cannot be determined. empty or if the queue's emptiness cannot be determined.
\end{funcdesc} \end{methoddesc}

77
Doc/libsgmllib.tex
View File

@ -38,37 +38,36 @@ spaces, tabs, and newlines are allowed between the trailing
\class{SGMLParser} instances have the following interface methods: \class{SGMLParser} instances have the following interface methods:
\setindexsubitem{(SGMLParser method)}
\begin{funcdesc}{reset}{} \begin{methoddesc}{reset}{}
Reset the instance. Loses all unprocessed data. This is called Reset the instance. Loses all unprocessed data. This is called
implicitly at instantiation time. implicitly at instantiation time.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{setnomoretags}{} \begin{methoddesc}{setnomoretags}{}
Stop processing tags. Treat all following input as literal input Stop processing tags. Treat all following input as literal input
(CDATA). (This is only provided so the HTML tag \code{<PLAINTEXT>} (CDATA). (This is only provided so the HTML tag \code{<PLAINTEXT>}
can be implemented.) can be implemented.)
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{setliteral}{} \begin{methoddesc}{setliteral}{}
Enter literal mode (CDATA mode). Enter literal mode (CDATA mode).
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{feed}{data} \begin{methoddesc}{feed}{data}
Feed some text to the parser. It is processed insofar as it consists Feed some text to the parser. It is processed insofar as it consists
of complete elements; incomplete data is buffered until more data is of complete elements; incomplete data is buffered until more data is
fed or \method{close()} is called. fed or \method{close()} is called.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{close}{} \begin{methoddesc}{close}{}
Force processing of all buffered data as if it were followed by an Force processing of all buffered data as if it were followed by an
end-of-file mark. This method may be redefined by a derived class to end-of-file mark. This method may be redefined by a derived class to
define additional processing at the end of the input, but the define additional processing at the end of the input, but the
redefined version should always call \method{close()}. redefined version should always call \method{close()}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{handle_starttag}{tag, method, attributes} \begin{methoddesc}{handle_starttag}{tag, method, attributes}
This method is called to handle start tags for which either a This method is called to handle start tags for which either a
\code{start_\var{tag}()} or \code{do_\var{tag}()} method has been \code{start_\var{tag}()} or \code{do_\var{tag}()} method has been
defined. The \var{tag} argument is the name of the tag converted to defined. The \var{tag} argument is the name of the tag converted to
@ -82,9 +81,9 @@ instance, for the tag \code{<A HREF="http://www.cwi.nl/">}, this
method would be called as \samp{unknown_starttag('a', [('href', method would be called as \samp{unknown_starttag('a', [('href',
'http://www.cwi.nl/')])}. The base implementation simply calls 'http://www.cwi.nl/')])}. The base implementation simply calls
\var{method} with \var{attributes} as the only argument. \var{method} with \var{attributes} as the only argument.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{handle_endtag}{tag, method} \begin{methoddesc}{handle_endtag}{tag, method}
This method is called to handle endtags for which an This method is called to handle endtags for which an
\code{end_\var{tag}()} method has been defined. The \var{tag} \code{end_\var{tag}()} method has been defined. The \var{tag}
argument is the name of the tag converted to lower case, and the argument is the name of the tag converted to lower case, and the
@ -93,15 +92,15 @@ support semantic interpretation of the end tag. If no
\code{end_\var{tag}()} method is defined for the closing element, \code{end_\var{tag}()} method is defined for the closing element,
this handler is not called. The base implementation simply calls this handler is not called. The base implementation simply calls
\var{method}. \var{method}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{handle_data}{data} \begin{methoddesc}{handle_data}{data}
This method is called to process arbitrary data. It is intended to be This method is called to process arbitrary data. It is intended to be
overridden by a derived class; the base class implementation does overridden by a derived class; the base class implementation does
nothing. nothing.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{handle_charref}{ref} \begin{methoddesc}{handle_charref}{ref}
This method is called to process a character reference of the form This method is called to process a character reference of the form
\samp{\&\#\var{ref};}. In the base implementation, \var{ref} must \samp{\&\#\var{ref};}. In the base implementation, \var{ref} must
be a decimal number in the be a decimal number in the
@ -111,9 +110,9 @@ method \method{handle_data()} with the character as argument. If
\code{unknown_charref(\var{ref})} is called to handle the error. A \code{unknown_charref(\var{ref})} is called to handle the error. A
subclass must override this method to provide support for named subclass must override this method to provide support for named
character entities. character entities.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{handle_entityref}{ref} \begin{methoddesc}{handle_entityref}{ref}
This method is called to process a general entity reference of the This method is called to process a general entity reference of the
form \samp{\&\var{ref};} where \var{ref} is an general entity form \samp{\&\var{ref};} where \var{ref} is an general entity
reference. It looks for \var{ref} in the instance (or class) reference. It looks for \var{ref} in the instance (or class)
@ -124,46 +123,46 @@ with the translation; otherwise, it calls the method
\code{unknown_entityref(\var{ref})}. The default \member{entitydefs} \code{unknown_entityref(\var{ref})}. The default \member{entitydefs}
defines translations for \code{\&amp;}, \code{\&apos}, \code{\&gt;}, defines translations for \code{\&amp;}, \code{\&apos}, \code{\&gt;},
\code{\&lt;}, and \code{\&quot;}. \code{\&lt;}, and \code{\&quot;}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{handle_comment}{comment} \begin{methoddesc}{handle_comment}{comment}
This method is called when a comment is encountered. The This method is called when a comment is encountered. The
\var{comment} argument is a string containing the text between the \var{comment} argument is a string containing the text between the
\samp{<!--} and \samp{-->} delimiters, but not the delimiters \samp{<!--} and \samp{-->} delimiters, but not the delimiters
themselves. For example, the comment \samp{<!--text-->} will themselves. For example, the comment \samp{<!--text-->} will
cause this method to be called with the argument \code{'text'}. The cause this method to be called with the argument \code{'text'}. The
default method does nothing. default method does nothing.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{report_unbalanced}{tag} \begin{methoddesc}{report_unbalanced}{tag}
This method is called when an end tag is found which does not This method is called when an end tag is found which does not
correspond to any open element. correspond to any open element.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{unknown_starttag}{tag, attributes} \begin{methoddesc}{unknown_starttag}{tag, attributes}
This method is called to process an unknown start tag. It is intended This method is called to process an unknown start tag. It is intended
to be overridden by a derived class; the base class implementation to be overridden by a derived class; the base class implementation
does nothing. does nothing.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{unknown_endtag}{tag} \begin{methoddesc}{unknown_endtag}{tag}
This method is called to process an unknown end tag. It is intended This method is called to process an unknown end tag. It is intended
to be overridden by a derived class; the base class implementation to be overridden by a derived class; the base class implementation
does nothing. does nothing.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{unknown_charref}{ref} \begin{methoddesc}{unknown_charref}{ref}
This method is called to process unresolvable numeric character This method is called to process unresolvable numeric character
references. Refer to \method{handle_charref()} to determine what is references. Refer to \method{handle_charref()} to determine what is
handled by default. It is intended to be overridden by a derived handled by default. It is intended to be overridden by a derived
class; the base class implementation does nothing. class; the base class implementation does nothing.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{unknown_entityref}{ref} \begin{methoddesc}{unknown_entityref}{ref}
This method is called to process an unknown entity reference. It is This method is called to process an unknown entity reference. It is
intended to be overridden by a derived class; the base class intended to be overridden by a derived class; the base class
implementation does nothing. implementation does nothing.
\end{funcdesc} \end{methoddesc}
Apart from overriding or extending the methods listed above, derived Apart from overriding or extending the methods listed above, derived
classes may also define methods of the following form to define classes may also define methods of the following form to define
@ -171,22 +170,22 @@ processing of specific tags. Tag names in the input stream are case
independent; the \var{tag} occurring in method names must be in lower independent; the \var{tag} occurring in method names must be in lower
case: case:
\begin{funcdescni}{start_\var{tag}}{attributes} \begin{methoddescni}{start_\var{tag}}{attributes}
This method is called to process an opening tag \var{tag}. It has This method is called to process an opening tag \var{tag}. It has
preference over \code{do_\var{tag}()}. The \var{attributes} preference over \code{do_\var{tag}()}. The \var{attributes}
argument has the same meaning as described for argument has the same meaning as described for
\method{handle_starttag()} above. \method{handle_starttag()} above.
\end{funcdescni} \end{methoddescni}
\begin{funcdescni}{do_\var{tag}}{attributes} \begin{methoddescni}{do_\var{tag}}{attributes}
This method is called to process an opening tag \var{tag} that does This method is called to process an opening tag \var{tag} that does
not come with a matching closing tag. The \var{attributes} argument not come with a matching closing tag. The \var{attributes} argument
has the same meaning as described for \method{handle_starttag()} above. has the same meaning as described for \method{handle_starttag()} above.
\end{funcdescni} \end{methoddescni}
\begin{funcdescni}{end_\var{tag}}{} \begin{methoddescni}{end_\var{tag}}{}
This method is called to process a closing tag \var{tag}. This method is called to process a closing tag \var{tag}.
\end{funcdescni} \end{methoddescni}
Note that the parser maintains a stack of open elements for which no Note that the parser maintains a stack of open elements for which no
end tag has been found yet. Only tags processed by end tag has been found yet. Only tags processed by

20
Doc/libstrio.tex
View File

@ -3,15 +3,21 @@
\stmodindex{StringIO} \stmodindex{StringIO}
This module implements a file-like class, \code{StringIO}, This module implements a file-like class, \class{StringIO},
that reads and writes a string buffer (also known as \emph{memory that reads and writes a string buffer (also known as \emph{memory
files}). See the description on file objects for operations. files}). See the description on file objects for operations.
When a \code{StringIO} object is created, it can be initialized \begin{classdesc}{StringIO}{\optional{buffer}}
When a \class{StringIO} object is created, it can be initialized
to an existing string by passing the string to the constructor. to an existing string by passing the string to the constructor.
If no string is given, the \code{StringIO} will start empty. If no string is given, the \class{StringIO} will start empty.
\end{classdesc}
The method \code{getvalue()} can be called to retrieve the entire \begin{methoddesc}{getvalue}{}
contents of the ``file'' at any time before the \code{StringIO} Retrieve the entire contents of the ``file'' at any time before the
object's \code{close()} method is called. Calling \code{close()} will \class{StringIO} object's \method{close()} method is called.
free the memory buffer. \end{methoddesc}
\begin{methoddesc}{close}{}
Free the memory buffer.
\end{methoddesc}

66
Doc/libtypes.tex
View File

@ -707,30 +707,28 @@ device or writing a file opened for reading.
Files have the following methods: Files have the following methods:
\setindexsubitem{(file method)} \begin{methoddesc}[file]{close}{}
\begin{funcdesc}{close}{}
Close the file. A closed file cannot be read or written anymore. Close the file. A closed file cannot be read or written anymore.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{flush}{} \begin{methoddesc}[file]{flush}{}
Flush the internal buffer, like \code{stdio}'s \code{fflush()}. Flush the internal buffer, like \code{stdio}'s \code{fflush()}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{isatty}{} \begin{methoddesc}[file]{isatty}{}
Return \code{1} if the file is connected to a tty(-like) device, else Return \code{1} if the file is connected to a tty(-like) device, else
\code{0}. \code{0}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{fileno}{} \begin{methoddesc}[file]{fileno}{}
Return the integer ``file descriptor'' that is used by the underlying Return the integer ``file descriptor'' that is used by the underlying
implementation to request I/O operations from the operating system. implementation to request I/O operations from the operating system.
This can be useful for other, lower level interfaces that use file This can be useful for other, lower level interfaces that use file
descriptors, e.g. module \code{fcntl} or \code{os.read()} and friends. descriptors, e.g. module \code{fcntl} or \code{os.read()} and friends.
\refbimodindex{fcntl} \refbimodindex{fcntl}
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{read}{\optional{size}} \begin{methoddesc}[file]{read}{\optional{size}}
Read at most \var{size} bytes from the file (less if the read hits Read at most \var{size} bytes from the file (less if the read hits
\EOF{} or no more data is immediately available on a pipe, tty or \EOF{} or no more data is immediately available on a pipe, tty or
similar device). If the \var{size} argument is negative or omitted, similar device). If the \var{size} argument is negative or omitted,
@ -738,9 +736,9 @@ descriptors, e.g. module \code{fcntl} or \code{os.read()} and friends.
object. An empty string is returned when \EOF{} is encountered object. An empty string is returned when \EOF{} is encountered
immediately. (For certain files, like ttys, it makes sense to immediately. (For certain files, like ttys, it makes sense to
continue reading after an \EOF{} is hit.) continue reading after an \EOF{} is hit.)
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{readline}{\optional{size}} \begin{methoddesc}[file]{readline}{\optional{size}}
Read one entire line from the file. A trailing newline character is Read one entire line from the file. A trailing newline character is
kept in the string% kept in the string%
\footnote{The advantage of leaving the newline on is that an empty string \footnote{The advantage of leaving the newline on is that an empty string
@ -757,71 +755,71 @@ descriptors, e.g. module \code{fcntl} or \code{os.read()} and friends.
immediately. Note: unlike \code{stdio}'s \code{fgets()}, the returned immediately. Note: unlike \code{stdio}'s \code{fgets()}, the returned
string contains null characters (\code{'\e 0'}) if they occurred in the string contains null characters (\code{'\e 0'}) if they occurred in the
input. input.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{readlines}{\optional{sizehint}} \begin{methoddesc}[file]{readlines}{\optional{sizehint}}
Read until \EOF{} using \code{readline()} and return a list containing Read until \EOF{} using \code{readline()} and return a list containing
the lines thus read. If the optional \var{sizehint} argument is the lines thus read. If the optional \var{sizehint} argument is
present, instead of reading up to \EOF{}, whole lines totalling present, instead of reading up to \EOF{}, whole lines totalling
approximately \var{sizehint} bytes (possibly after rounding up to an approximately \var{sizehint} bytes (possibly after rounding up to an
internal buffer size) are read. internal buffer size) are read.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{seek}{offset, whence} \begin{methoddesc}[file]{seek}{offset, whence}
Set the file's current position, like \code{stdio}'s \code{fseek()}. Set the file's current position, like \code{stdio}'s \code{fseek()}.
The \var{whence} argument is optional and defaults to \code{0} The \var{whence} argument is optional and defaults to \code{0}
(absolute file positioning); other values are \code{1} (seek (absolute file positioning); other values are \code{1} (seek
relative to the current position) and \code{2} (seek relative to the relative to the current position) and \code{2} (seek relative to the
file's end). There is no return value. file's end). There is no return value.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{tell}{} \begin{methoddesc}[file]{tell}{}
Return the file's current position, like \code{stdio}'s \code{ftell()}. Return the file's current position, like \code{stdio}'s \code{ftell()}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{truncate}{\optional{size}} \begin{methoddesc}[file]{truncate}{\optional{size}}
Truncate the file's size. If the optional size argument present, the Truncate the file's size. If the optional size argument present, the
file is truncated to (at most) that size. The size defaults to the file is truncated to (at most) that size. The size defaults to the
current position. Availability of this function depends on the current position. Availability of this function depends on the
operating system version (e.g., not all \UNIX{} versions support this operating system version (e.g., not all \UNIX{} versions support this
operation). operation).
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{write}{str} \begin{methoddesc}[file]{write}{str}
Write a string to the file. There is no return value. Note: due to Write a string to the file. There is no return value. Note: due to
buffering, the string may not actually show up in the file until buffering, the string may not actually show up in the file until
the \code{flush()} or \code{close()} method is called. the \code{flush()} or \code{close()} method is called.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{writelines}{list} \begin{methoddesc}[file]{writelines}{list}
Write a list of strings to the file. There is no return value. Write a list of strings to the file. There is no return value.
(The name is intended to match \code{readlines}; \code{writelines} (The name is intended to match \code{readlines}; \code{writelines}
does not add line separators.) does not add line separators.)
\end{funcdesc} \end{methoddesc}
File objects also offer the following attributes: File objects also offer the following attributes:
\setindexsubitem{(file attribute)} \setindexsubitem{(file attribute)}
\begin{datadesc}{closed} \begin{memberdesc}[file]{closed}
Boolean indicating the current state of the file object. This is a Boolean indicating the current state of the file object. This is a
read-only attribute; the \method{close()} method changes the value. read-only attribute; the \method{close()} method changes the value.
\end{datadesc} \end{memberdesc}
\begin{datadesc}{mode} \begin{memberdesc}[file]{mode}
The I/O mode for the file. If the file was created using the The I/O mode for the file. If the file was created using the
\function{open()} built-in function, this will be the value of the \function{open()} built-in function, this will be the value of the
\var{mode} parameter. This is a read-only attribute. \var{mode} parameter. This is a read-only attribute.
\end{datadesc} \end{memberdesc}
\begin{datadesc}{name} \begin{memberdesc}[file]{name}
If the file object was created using \function{open()}, the name of If the file object was created using \function{open()}, the name of
the file. Otherwise, some string that indicates the source of the the file. Otherwise, some string that indicates the source of the
file object, of the form \samp{<\mbox{\ldots}>}. This is a read-only file object, of the form \samp{<\mbox{\ldots}>}. This is a read-only
attribute. attribute.
\end{datadesc} \end{memberdesc}
\begin{datadesc}{softspace} \begin{memberdesc}[file]{softspace}
Boolean that indicates whether a space character needs to be printed Boolean that indicates whether a space character needs to be printed
before another value when using the \keyword{print} statement. before another value when using the \keyword{print} statement.
Classes that are trying to simulate a file object should also have a Classes that are trying to simulate a file object should also have a
@ -829,7 +827,7 @@ writable \code{softspace} attribute, which should be initialized to
zero. This will be automatic for classes implemented in Python; types zero. This will be automatic for classes implemented in Python; types
implemented in \C{} will have to provide a writable \code{softspace} implemented in \C{} will have to provide a writable \code{softspace}
attribute. attribute.
\end{datadesc} \end{memberdesc}
\subsubsection{Internal Objects} \subsubsection{Internal Objects}