mirrors/cpython
0
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2024-11-26 19:34:19 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
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:
\begin{datadesc}{AS_IS}
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
@ -47,33 +48,30 @@ be called without having to track whether the property was changed.
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.
\end{datadesc}
\end{memberdesc}
\setindexsubitem{(formatter method)}
\begin{funcdesc}{end_paragraph}{blanklines}
\begin{methoddesc}[formatter]{end_paragraph}{blanklines}
Close any open paragraphs and insert at least \var{blanklines}
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
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
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
\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.
Whitespace from preceeding and successive calls to
\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
word-wrapping still must be performed by the writer object due to the
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.
Whitespace, including newline and tab characters, are considered legal
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
margin. This should be used for constructing bulleted or numbered
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
case. Note that the alphabetic and roman transforms require that the
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
\method{add_flowing_data()} to the associated writer object. This
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
\constant{AS_IS} if no change is desired. If the alignment value is
changed from the previous setting, the writer's \method{new_alignment()}
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.
\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
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
\method{new_font()} method is called with the fully resolved font
specification.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{pop_font}{}
\begin{methoddesc}[formatter]{pop_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
the logical tag \var{margin} with the new indentation. The initial
margin level is \code{0}. Changed values of the logical tag must be
true values; false values other than \constant{AS_IS} are not
sufficient to change the margin.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{pop_margin}{}
\begin{methoddesc}[formatter]{pop_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
pushed onto the styles stack in order. A tuple representing the
entire stack, including \constant{AS_IS} values, is passed to the
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
\method{push_style()}. A tuple representing the revised stack,
including \constant{AS_IS} values, is passed to the writer's
\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.
\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
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
the writer manipulations produced a hard line break at the end of the
output.
\end{funcdesc}
\end{methoddesc}
\subsection{Formatter Implementations}
@ -213,21 +211,20 @@ Note that while most applications can use the
\class{AbstractFormatter} class as a formatter, the writer must
typically be provided by the application.
\setindexsubitem{(writer method)}
\begin{funcdesc}{flush}{}
\begin{methoddesc}[writer]{flush}{}
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,
but by convention is a string or \code{None}, where \code{None}
indicates that the writer's ``preferred'' alignment should be used.
Conventional \var{align} values are \code{'left'}, \code{'center'},
\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},
indicating that the device's default font should be used, or a tuple
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
\var{teletype} values are boolean indicators specifying which of those
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
to \var{margin}. Interpretation of the logical tag is at the
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
\var{level}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{new_spacing}{spacing}
\begin{methoddesc}[writer]{new_spacing}{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
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
depending on the requirements of the application and writer
implementation.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{send_line_break}{}
\begin{methoddesc}[writer]{send_line_break}{}
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
lines, or the equivelent. The \var{blankline} value will be an
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
method are entirely application- and writer-specific, and should be
interpreted with care. The method implementation may assume that a
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
needed. Within any sequence of calls to this method, the writer may
assume that spans of multiple whitespace characters have been
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
for display. Generally, this should be interpreted to mean that line
breaks indicated by newline characters should be preserved and no new
line breaks should be introduced. The data may contain embedded
newline and tab characters, unlike data provided to the
\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.
The value of \var{data} is not restricted; treatment of non-string
values is entirely application- and writer-dependent. This method
will only be called at the beginning of a line.
\end{funcdesc}
\end{methoddesc}
\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
additional methods and instance variables for use within tag methods.
\setindexsubitem{(HTMLParser attribute)}
\begin{datadesc}{formatter}
\begin{memberdesc}{formatter}
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
collapsed, or false when it should be. In general, this should only
be true when character data is to be treated as ``preformatted'' text,
as within a \code{<PRE>} element. The default value is false. This
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
correspond to the attributes of the \code{<A>} tag with the same
names. The default implementation maintains a list of hyperlinks
(defined by the \code{href} attribute) within the document. The list
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
implementation adds a textual footnote marker using an index into the
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
simply passes the \var{alt} value to the \method{handle_data()}
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
formatter object. Retrieve the stored data via \method{save_end()}.
Use of the \method{save_bgn()} / \method{save_end()} pair may not be
nested.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{save_end}{}
\begin{methoddesc}{save_end}{}
Ends buffering character data and returns all data saved since the
preceeding call to \method{save_bgn()}. If the \code{nofill} flag is
false, whitespace is collapsed to single spaces. A call to this
method without a preceeding call to \method{save_bgn()} will raise a
\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:
\setindexsubitem{(PrettyPrinter method)}
\begin{funcdesc}{pformat}{object}
\begin{methoddesc}{pformat}{object}
Return the formatted representation of \var{object}. This takes into
account the options passed to the \class{PrettyPrinter} constructor.
\end{funcdesc}
Account the options passed to the \class{PrettyPrinter} constructor.
\end{methoddesc}
\begin{funcdesc}{pprint}{object}
\begin{methoddesc}{pprint}{object}
Print the formatted representation of \var{object} on the configured
stream, followed by a newline.
\end{funcdesc}
\end{methoddesc}
The following methods provide the implementations for the
corresponding functions of the same names. Using these methods on an
instance is slightly more efficient since new \class{PrettyPrinter}
objects don't need to be created.
\begin{funcdesc}{isreadable}{object}
\begin{methoddesc}{isreadable}{object}
Determine if the formatted representation of the object is
``readable,'' or can be used to reconstruct the value using
\function{eval()}\bifuncindex{eval}. Note that this returns false for
recursive objects. If the \var{depth} parameter of the
\class{PrettyPrinter} is set and the object is deeper than allowed,
this returns false.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{isrecursive}{object}
\begin{methoddesc}{isrecursive}{object}
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}
\label{profile}
\stmodindex{profile}
\stmodindex{pstats}
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}
\stmodindex{profile}
\label{module-profile}
\setindexsubitem{(in module profile)}
The primary entry point for the profiler is the global function
\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
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
\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
\module{pstats} module:
\setindexsubitem{(in module pstats)}
% now switch modules....
\stmodindex{pstats}
\begin{classdesc}{Stats}{filename\optional{, ...}}
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)}
\begin{funcdesc}{strip_dirs}{}
\begin{methoddesc}{strip_dirs}{}
This method for the \class{Stats} class removes all leading path
information from file names. It is very useful in reducing the size
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
line of the same filename, and have the same function name), then the
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
profiling information into the current profiling object. Its
arguments should refer to filenames created by the corresponding
version of \function{profile.run()}. Statistics for identically named
(re: file, line, name) functions are automatically accumulated into
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
to the supplied criteria. The argument is typically a string
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)
is used, only one sort key (the numeric key) will be used, and
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
list within the object. This method is provided primarily for
compatibility with the old profiler. Its utility is questionable
now that ascending vs descending order is properly selected based on
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
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:},
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
that called each function in the profiled database. The ordering is
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
times this specific call was made. A second non-parenthesized number
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
that were called by the indicated function. Aside from this reversal
of direction of calls (re: called vs was called by), the arguments and
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
returned by earlier methods. All standard methods in this class
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') \
.print_stats().ignore()
\end{verbatim}
%
would perform all the indicated functions, but it would not return
the final reference to the \class{Stats} instance.%
\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
backward compatibility.
}
\end{funcdesc}
\end{methoddesc}
\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
methods are:
\setindexsubitem{(Queue method)}
\begin{funcdesc}{qsize}{}
\begin{methoddesc}{qsize}{}
Returns the approximate size of the queue. Because of multithreading
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
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
multithreading semantics, this is not reliable.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{put}{item}
\begin{methoddesc}{put}{item}
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
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
available. Raises an \exception{Empty} exception if the queue is
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:
\setindexsubitem{(SGMLParser method)}
\begin{funcdesc}{reset}{}
\begin{methoddesc}{reset}{}
Reset the instance. Loses all unprocessed data. This is called
implicitly at instantiation time.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setnomoretags}{}
\begin{methoddesc}{setnomoretags}{}
Stop processing tags. Treat all following input as literal input
(CDATA). (This is only provided so the HTML tag \code{<PLAINTEXT>}
can be implemented.)
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setliteral}{}
\begin{methoddesc}{setliteral}{}
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
of complete elements; incomplete data is buffered until more data is
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
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
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
\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
@ -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',
'http://www.cwi.nl/')])}. The base implementation simply calls
\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
\code{end_\var{tag}()} method has been defined. The \var{tag}
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,
this handler is not called. The base implementation simply calls
\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
overridden by a derived class; the base class implementation does
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
\samp{\&\#\var{ref};}. In the base implementation, \var{ref} must
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
subclass must override this method to provide support for named
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
form \samp{\&\var{ref};} where \var{ref} is an general entity
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}
defines translations for \code{\&amp;}, \code{\&apos}, \code{\&gt;},
\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
\var{comment} argument is a string containing the text between the
\samp{<!--} and \samp{-->} delimiters, but not the delimiters
themselves. For example, the comment \samp{<!--text-->} will
cause this method to be called with the argument \code{'text'}. The
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
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
to be overridden by a derived class; the base class implementation
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
to be overridden by a derived class; the base class implementation
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
references. Refer to \method{handle_charref()} to determine what is
handled by default. It is intended to be overridden by a derived
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
intended to be overridden by a derived class; the base class
implementation does nothing.
\end{funcdesc}
\end{methoddesc}
Apart from overriding or extending the methods listed above, derived
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
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
preference over \code{do_\var{tag}()}. The \var{attributes}
argument has the same meaning as described for
\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
not come with a matching closing tag. The \var{attributes} argument
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}.
\end{funcdescni}
\end{methoddescni}
Note that the parser maintains a stack of open elements for which no
end tag has been found yet. Only tags processed by

20
Doc/lib/libstrio.tex
View File

@ -3,15 +3,21 @@
\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
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.
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
contents of the ``file'' at any time before the \code{StringIO}
object's \code{close()} method is called. Calling \code{close()} will
free the memory buffer.
\begin{methoddesc}{getvalue}{}
Retrieve the entire contents of the ``file'' at any time before the
\class{StringIO} object's \method{close()} method is called.
\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:
\setindexsubitem{(file method)}
\begin{funcdesc}{close}{}
\begin{methoddesc}[file]{close}{}
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()}.
\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
\code{0}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{fileno}{}
\begin{methoddesc}[file]{fileno}{}
Return the integer ``file descriptor'' that is used by the underlying
implementation to request I/O operations from the operating system.
This can be useful for other, lower level interfaces that use file
descriptors, e.g. module \code{fcntl} or \code{os.read()} and friends.
\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
\EOF{} or no more data is immediately available on a pipe, tty or
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
immediately. (For certain files, like ttys, it makes sense to
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
kept in the 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
string contains null characters (\code{'\e 0'}) if they occurred in the
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
the lines thus read. If the optional \var{sizehint} argument is
present, instead of reading up to \EOF{}, whole lines totalling
approximately \var{sizehint} bytes (possibly after rounding up to an
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()}.
The \var{whence} argument is optional and defaults to \code{0}
(absolute file positioning); other values are \code{1} (seek
relative to the current position) and \code{2} (seek relative to the
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()}.
\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
file is truncated to (at most) that size. The size defaults to the
current position. Availability of this function depends on the
operating system version (e.g., not all \UNIX{} versions support this
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
buffering, the string may not actually show up in the file until
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.
(The name is intended to match \code{readlines}; \code{writelines}
does not add line separators.)
\end{funcdesc}
\end{methoddesc}
File objects also offer the following attributes:
\setindexsubitem{(file attribute)}
\begin{datadesc}{closed}
\begin{memberdesc}[file]{closed}
Boolean indicating the current state of the file object. This is a
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
\function{open()} built-in function, this will be the value of the
\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
the file. Otherwise, some string that indicates the source of the
file object, of the form \samp{<\mbox{\ldots}>}. This is a read-only
attribute.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{softspace}
\begin{memberdesc}[file]{softspace}
Boolean that indicates whether a space character needs to be printed
before another value when using the \keyword{print} statement.
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
implemented in \C{} will have to provide a writable \code{softspace}
attribute.
\end{datadesc}
\end{memberdesc}
\subsubsection{Internal Objects}

125
Doc/libformatter.tex
View File

@ -37,6 +37,7 @@ initialized.
One data element is defined at the module level:
\begin{datadesc}{AS_IS}
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
@ -47,33 +48,30 @@ be called without having to track whether the property was changed.
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.
\end{datadesc}
\end{memberdesc}
\setindexsubitem{(formatter method)}
\begin{funcdesc}{end_paragraph}{blanklines}
\begin{methoddesc}[formatter]{end_paragraph}{blanklines}
Close any open paragraphs and insert at least \var{blanklines}
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
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
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
\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.
Whitespace from preceeding and successive calls to
\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
word-wrapping still must be performed by the writer object due to the
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.
Whitespace, including newline and tab characters, are considered legal
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
margin. This should be used for constructing bulleted or numbered
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
case. Note that the alphabetic and roman transforms require that the
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
\method{add_flowing_data()} to the associated writer object. This
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
\constant{AS_IS} if no change is desired. If the alignment value is
changed from the previous setting, the writer's \method{new_alignment()}
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.
\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
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
\method{new_font()} method is called with the fully resolved font
specification.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{pop_font}{}
\begin{methoddesc}[formatter]{pop_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
the logical tag \var{margin} with the new indentation. The initial
margin level is \code{0}. Changed values of the logical tag must be
true values; false values other than \constant{AS_IS} are not
sufficient to change the margin.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{pop_margin}{}
\begin{methoddesc}[formatter]{pop_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
pushed onto the styles stack in order. A tuple representing the
entire stack, including \constant{AS_IS} values, is passed to the
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
\method{push_style()}. A tuple representing the revised stack,
including \constant{AS_IS} values, is passed to the writer's
\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.
\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
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
the writer manipulations produced a hard line break at the end of the
output.
\end{funcdesc}
\end{methoddesc}
\subsection{Formatter Implementations}
@ -213,21 +211,20 @@ Note that while most applications can use the
\class{AbstractFormatter} class as a formatter, the writer must
typically be provided by the application.
\setindexsubitem{(writer method)}
\begin{funcdesc}{flush}{}
\begin{methoddesc}[writer]{flush}{}
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,
but by convention is a string or \code{None}, where \code{None}
indicates that the writer's ``preferred'' alignment should be used.
Conventional \var{align} values are \code{'left'}, \code{'center'},
\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},
indicating that the device's default font should be used, or a tuple
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
\var{teletype} values are boolean indicators specifying which of those
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
to \var{margin}. Interpretation of the logical tag is at the
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
\var{level}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{new_spacing}{spacing}
\begin{methoddesc}[writer]{new_spacing}{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
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
depending on the requirements of the application and writer
implementation.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{send_line_break}{}
\begin{methoddesc}[writer]{send_line_break}{}
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
lines, or the equivelent. The \var{blankline} value will be an
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
method are entirely application- and writer-specific, and should be
interpreted with care. The method implementation may assume that a
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
needed. Within any sequence of calls to this method, the writer may
assume that spans of multiple whitespace characters have been
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
for display. Generally, this should be interpreted to mean that line
breaks indicated by newline characters should be preserved and no new
line breaks should be introduced. The data may contain embedded
newline and tab characters, unlike data provided to the
\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.
The value of \var{data} is not restricted; treatment of non-string
values is entirely application- and writer-dependent. This method
will only be called at the beginning of a line.
\end{funcdesc}
\end{methoddesc}
\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
additional methods and instance variables for use within tag methods.
\setindexsubitem{(HTMLParser attribute)}
\begin{datadesc}{formatter}
\begin{memberdesc}{formatter}
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
collapsed, or false when it should be. In general, this should only
be true when character data is to be treated as ``preformatted'' text,
as within a \code{<PRE>} element. The default value is false. This
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
correspond to the attributes of the \code{<A>} tag with the same
names. The default implementation maintains a list of hyperlinks
(defined by the \code{href} attribute) within the document. The list
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
implementation adds a textual footnote marker using an index into the
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
simply passes the \var{alt} value to the \method{handle_data()}
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
formatter object. Retrieve the stored data via \method{save_end()}.
Use of the \method{save_bgn()} / \method{save_end()} pair may not be
nested.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{save_end}{}
\begin{methoddesc}{save_end}{}
Ends buffering character data and returns all data saved since the
preceeding call to \method{save_bgn()}. If the \code{nofill} flag is
false, whitespace is collapsed to single spaces. A call to this
method without a preceeding call to \method{save_bgn()} will raise a
\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:
\setindexsubitem{(PrettyPrinter method)}
\begin{funcdesc}{pformat}{object}
\begin{methoddesc}{pformat}{object}
Return the formatted representation of \var{object}. This takes into
account the options passed to the \class{PrettyPrinter} constructor.
\end{funcdesc}
Account the options passed to the \class{PrettyPrinter} constructor.
\end{methoddesc}
\begin{funcdesc}{pprint}{object}
\begin{methoddesc}{pprint}{object}
Print the formatted representation of \var{object} on the configured
stream, followed by a newline.
\end{funcdesc}
\end{methoddesc}
The following methods provide the implementations for the
corresponding functions of the same names. Using these methods on an
instance is slightly more efficient since new \class{PrettyPrinter}
objects don't need to be created.
\begin{funcdesc}{isreadable}{object}
\begin{methoddesc}{isreadable}{object}
Determine if the formatted representation of the object is
``readable,'' or can be used to reconstruct the value using
\function{eval()}\bifuncindex{eval}. Note that this returns false for
recursive objects. If the \var{depth} parameter of the
\class{PrettyPrinter} is set and the object is deeper than allowed,
this returns false.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{isrecursive}{object}
\begin{methoddesc}{isrecursive}{object}
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}
\label{profile}
\stmodindex{profile}
\stmodindex{pstats}
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}
\stmodindex{profile}
\label{module-profile}
\setindexsubitem{(in module profile)}
The primary entry point for the profiler is the global function
\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
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
\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
\module{pstats} module:
\setindexsubitem{(in module pstats)}
% now switch modules....
\stmodindex{pstats}
\begin{classdesc}{Stats}{filename\optional{, ...}}
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)}
\begin{funcdesc}{strip_dirs}{}
\begin{methoddesc}{strip_dirs}{}
This method for the \class{Stats} class removes all leading path
information from file names. It is very useful in reducing the size
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
line of the same filename, and have the same function name), then the
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
profiling information into the current profiling object. Its
arguments should refer to filenames created by the corresponding
version of \function{profile.run()}. Statistics for identically named
(re: file, line, name) functions are automatically accumulated into
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
to the supplied criteria. The argument is typically a string
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)
is used, only one sort key (the numeric key) will be used, and
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
list within the object. This method is provided primarily for
compatibility with the old profiler. Its utility is questionable
now that ascending vs descending order is properly selected based on
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
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:},
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
that called each function in the profiled database. The ordering is
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
times this specific call was made. A second non-parenthesized number
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
that were called by the indicated function. Aside from this reversal
of direction of calls (re: called vs was called by), the arguments and
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
returned by earlier methods. All standard methods in this class
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') \
.print_stats().ignore()
\end{verbatim}
%
would perform all the indicated functions, but it would not return
the final reference to the \class{Stats} instance.%
\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
backward compatibility.
}
\end{funcdesc}
\end{methoddesc}
\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
methods are:
\setindexsubitem{(Queue method)}
\begin{funcdesc}{qsize}{}
\begin{methoddesc}{qsize}{}
Returns the approximate size of the queue. Because of multithreading
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
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
multithreading semantics, this is not reliable.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{put}{item}
\begin{methoddesc}{put}{item}
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
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
available. Raises an \exception{Empty} exception if the queue is
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:
\setindexsubitem{(SGMLParser method)}
\begin{funcdesc}{reset}{}
\begin{methoddesc}{reset}{}
Reset the instance. Loses all unprocessed data. This is called
implicitly at instantiation time.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setnomoretags}{}
\begin{methoddesc}{setnomoretags}{}
Stop processing tags. Treat all following input as literal input
(CDATA). (This is only provided so the HTML tag \code{<PLAINTEXT>}
can be implemented.)
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setliteral}{}
\begin{methoddesc}{setliteral}{}
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
of complete elements; incomplete data is buffered until more data is
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
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
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
\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
@ -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',
'http://www.cwi.nl/')])}. The base implementation simply calls
\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
\code{end_\var{tag}()} method has been defined. The \var{tag}
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,
this handler is not called. The base implementation simply calls
\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
overridden by a derived class; the base class implementation does
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
\samp{\&\#\var{ref};}. In the base implementation, \var{ref} must
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
subclass must override this method to provide support for named
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
form \samp{\&\var{ref};} where \var{ref} is an general entity
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}
defines translations for \code{\&amp;}, \code{\&apos}, \code{\&gt;},
\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
\var{comment} argument is a string containing the text between the
\samp{<!--} and \samp{-->} delimiters, but not the delimiters
themselves. For example, the comment \samp{<!--text-->} will
cause this method to be called with the argument \code{'text'}. The
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
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
to be overridden by a derived class; the base class implementation
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
to be overridden by a derived class; the base class implementation
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
references. Refer to \method{handle_charref()} to determine what is
handled by default. It is intended to be overridden by a derived
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
intended to be overridden by a derived class; the base class
implementation does nothing.
\end{funcdesc}
\end{methoddesc}
Apart from overriding or extending the methods listed above, derived
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
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
preference over \code{do_\var{tag}()}. The \var{attributes}
argument has the same meaning as described for
\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
not come with a matching closing tag. The \var{attributes} argument
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}.
\end{funcdescni}
\end{methoddescni}
Note that the parser maintains a stack of open elements for which no
end tag has been found yet. Only tags processed by

20
Doc/libstrio.tex
View File

@ -3,15 +3,21 @@
\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
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.
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
contents of the ``file'' at any time before the \code{StringIO}
object's \code{close()} method is called. Calling \code{close()} will
free the memory buffer.
\begin{methoddesc}{getvalue}{}
Retrieve the entire contents of the ``file'' at any time before the
\class{StringIO} object's \method{close()} method is called.
\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:
\setindexsubitem{(file method)}
\begin{funcdesc}{close}{}
\begin{methoddesc}[file]{close}{}
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()}.
\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
\code{0}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{fileno}{}
\begin{methoddesc}[file]{fileno}{}
Return the integer ``file descriptor'' that is used by the underlying
implementation to request I/O operations from the operating system.
This can be useful for other, lower level interfaces that use file
descriptors, e.g. module \code{fcntl} or \code{os.read()} and friends.
\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
\EOF{} or no more data is immediately available on a pipe, tty or
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
immediately. (For certain files, like ttys, it makes sense to
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
kept in the 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
string contains null characters (\code{'\e 0'}) if they occurred in the
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
the lines thus read. If the optional \var{sizehint} argument is
present, instead of reading up to \EOF{}, whole lines totalling
approximately \var{sizehint} bytes (possibly after rounding up to an
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()}.
The \var{whence} argument is optional and defaults to \code{0}
(absolute file positioning); other values are \code{1} (seek
relative to the current position) and \code{2} (seek relative to the
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()}.
\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
file is truncated to (at most) that size. The size defaults to the
current position. Availability of this function depends on the
operating system version (e.g., not all \UNIX{} versions support this
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
buffering, the string may not actually show up in the file until
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.
(The name is intended to match \code{readlines}; \code{writelines}
does not add line separators.)
\end{funcdesc}
\end{methoddesc}
File objects also offer the following attributes:
\setindexsubitem{(file attribute)}
\begin{datadesc}{closed}
\begin{memberdesc}[file]{closed}
Boolean indicating the current state of the file object. This is a
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
\function{open()} built-in function, this will be the value of the
\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
the file. Otherwise, some string that indicates the source of the
file object, of the form \samp{<\mbox{\ldots}>}. This is a read-only
attribute.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{softspace}
\begin{memberdesc}[file]{softspace}
Boolean that indicates whether a space character needs to be printed
before another value when using the \keyword{print} statement.
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
implemented in \C{} will have to provide a writable \code{softspace}
attribute.
\end{datadesc}
\end{memberdesc}
\subsubsection{Internal Objects}