mirror of https://github.com/python/cpython
139 lines
5.0 KiB
TeX
139 lines
5.0 KiB
TeX
% Template for a library manual section.
|
|
% PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE
|
|
|
|
|
|
% ==== 1. ====
|
|
% Choose one of the following section headers and index entries;
|
|
% \section generates the section header, \declmodule produces the
|
|
% appropriate index entry for this module. Note that these should
|
|
% only be used for the defining entry for the module. Other
|
|
% references to the module should use \refbimodindex, \refstmodindex,
|
|
% \refexmodindex or \refmodindex, as appropriate.
|
|
|
|
\section{Built-in Module \module{spam}} % If implemented in C, in
|
|
\declaremodule{builtin}{spam} % standard library
|
|
|
|
\section{Standard Module \module{spam}} % If implemented in Python, in
|
|
\declaremodule{standard}{spam} % standard library
|
|
|
|
\section{Extension Module \module{spam}}% If implemented in C, but not
|
|
\declaremodule{extension}{spam} % in standard library
|
|
|
|
\section{Module \module{spam}} % If implemented in Python, but not
|
|
\declaremodule{}{spam} % in standard library
|
|
|
|
|
|
\modulesynopsis{This is a one-line descrition, for the chapter header.}
|
|
|
|
|
|
% ==== 2. ====
|
|
% Give a short overview of what the module does.
|
|
% If it is platform specific, mention this.
|
|
% Mention other important restrictions or general operating principles.
|
|
% For example:
|
|
|
|
The \module{spam} module defines operations for handling cans of Spam.
|
|
It knows the four generally available Spam varieties and understands
|
|
both can sizes.
|
|
|
|
Because spamification requires \UNIX{} process management, the module
|
|
is only available on genuine \UNIX{} systems.
|
|
|
|
|
|
% ==== 3. ====
|
|
% List the public functions defined by the module. Begin with a
|
|
% standard phrase. You may also list the exceptions and other data
|
|
% items defined in the module, insofar as they are important for the
|
|
% user.
|
|
|
|
The \module{spam} module defines the following functions:
|
|
|
|
% ---- 3.1. ----
|
|
% For each function, use a ``funcdesc'' block. This has exactly two
|
|
% parameters (each parameters is contained in a set of curly braces):
|
|
% the first parameter is the function name (this automatically
|
|
% generates an index entry); the second parameter is the function's
|
|
% argument list. If there are no arguments, use an empty pair of
|
|
% curly braces. If there is more than one argument, separate the
|
|
% arguments with backslash-comma. Optional parts of the parameter
|
|
% list are contained in \optional{...} (this generates a set of square
|
|
% brackets around its parameter). Arguments are automatically set in
|
|
% italics in the parameter list. Each argument should be mentioned at
|
|
% least once in the description; each usage (even inside \code{...})
|
|
% should be enclosed in \var{...}.
|
|
|
|
\begin{funcdesc}{open}{filename\optional{, mode\optional{, buffersize}}}
|
|
Open the file \var{filename} as a can of Spam. The optional
|
|
\var{mode} and \var{buffersize} arguments specify the read-write mode
|
|
(\code{'r'} (default) or \code{'w'}) and the buffer size (default:
|
|
system dependent).
|
|
\end{funcdesc}
|
|
|
|
% ---- 3.2. ----
|
|
% Data items are described using a ``datadesc'' block. This has only
|
|
% one parameter: the item's name.
|
|
|
|
\begin{datadesc}{cansize}
|
|
The default can size, in ounces. Legal values are 7 and 12. The
|
|
default varies per supermarket. This variable should not be changed
|
|
once the \function{open()} function has been called.
|
|
\end{datadesc}
|
|
|
|
% --- 3.3. ---
|
|
% Exceptions are described using a ``excdesc'' block. This has only
|
|
% one parameter: the exception name.
|
|
|
|
\begin{excdesc}{error}
|
|
Exception raised when an operation fails for a Spam specific reason.
|
|
The exception argument is a string describing the reason of the
|
|
failure.
|
|
\end{excdesc}
|
|
|
|
% ---- 3.4. ----
|
|
% Other standard environments:
|
|
%
|
|
% classdesc - Python classes; same arguments are funcdesc
|
|
% methoddesc - methods, like funcdesc but has an optional parameter
|
|
% to give the type name: \begin{methoddesc}[mytype]{name}{args}
|
|
% By default, the type name will be the name of the
|
|
% last class defined using classdesc. The type name
|
|
% is required if the type is implemented in C (because
|
|
% there's no classdesc) or if the class isn't directly
|
|
% documented (if it's private).
|
|
% memberdesc - data members, like datadesc, but with an optional
|
|
% type name like methoddesc.
|
|
|
|
|
|
% ==== 4. ====
|
|
% Now is probably a good time for a complete example. (Alternatively,
|
|
% an example giving the flavor of the module may be given before the
|
|
% detailed list of functions.)
|
|
|
|
Example:
|
|
|
|
\begin{verbatim}
|
|
>>> import spam
|
|
>>> can = spam.open('/etc/passwd')
|
|
>>> can.empty()
|
|
>>> can.close()
|
|
\end{verbatim}
|
|
% Note that there is no trailing ">>> " prompt shown.
|
|
|
|
% ==== 5. ====
|
|
% If your module defines new object types (for a built-in module) or
|
|
% classes (for a module written in Python), you should list the
|
|
% methods and instance variables (if any) of each type or class in a
|
|
% separate subsection.
|
|
|
|
\subsection{Spam Objects}
|
|
\label{spam-objects}
|
|
% This label is generally useful for referencing this section, but is
|
|
% also used to give a filename when generating HTML.
|
|
|
|
Spam objects, as returned by \function{open()} above, have the
|
|
following methods:
|
|
|
|
\begin{methoddesc}[spam]{empty}{}
|
|
Empty the can into the trash.
|
|
\end{methoddesc}
|