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

Fixed description of similarity between m[name] and m.getheader(name), 

reported by Samuel L. Bayer.

Use methoddesc instead of funcdesc, etc.
This commit is contained in:
Fred Drake 1998-04-04 06:19:30 +00:00
parent d275de985a
commit e14dde2117
2 changed files with 52 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
Doc/lib/librfc822.tex
View File

@ -62,41 +62,42 @@ switch dates. Not enough to worry about for common use.
\end{funcdesc} \end{funcdesc}
\subsection{Message Objects} \subsection{Message Objects}
\label{message-objects}
A \class{Message} instance has the following methods: A \class{Message} instance has the following methods:
\begin{funcdesc}{rewindbody}{} \begin{methoddesc}{rewindbody}{}
Seek to the start of the message body. This only works if the file Seek to the start of the message body. This only works if the file
object is seekable. object is seekable.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{getallmatchingheaders}{name} \begin{methoddesc}{getallmatchingheaders}{name}
Return a list of lines consisting of all headers matching Return a list of lines consisting of all headers matching
\var{name}, if any. Each physical line, whether it is a continuation \var{name}, if any. Each physical line, whether it is a continuation
line or not, is a separate list item. Return the empty list if no line or not, is a separate list item. Return the empty list if no
header matches \var{name}. header matches \var{name}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{getfirstmatchingheader}{name} \begin{methoddesc}{getfirstmatchingheader}{name}
Return a list of lines comprising the first header matching Return a list of lines comprising the first header matching
\var{name}, and its continuation line(s), if any. Return \code{None} \var{name}, and its continuation line(s), if any. Return \code{None}
if there is no header matching \var{name}. if there is no header matching \var{name}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{getrawheader}{name} \begin{methoddesc}{getrawheader}{name}
Return a single string consisting of the text after the colon in the Return a single string consisting of the text after the colon in the
first header matching \var{name}. This includes leading whitespace, first header matching \var{name}. This includes leading whitespace,
the trailing linefeed, and internal linefeeds and whitespace if there the trailing linefeed, and internal linefeeds and whitespace if there
any continuation line(s) were present. Return \code{None} if there is any continuation line(s) were present. Return \code{None} if there is
no header matching \var{name}. no header matching \var{name}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{getheader}{name} \begin{methoddesc}{getheader}{name}
Like \code{getrawheader(\var{name})}, but strip leading and trailing Like \code{getrawheader(\var{name})}, but strip leading and trailing
whitespace. Internal whitespace is not stripped. whitespace. Internal whitespace is not stripped.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{getaddr}{name} \begin{methoddesc}{getaddr}{name}
Return a pair \code{(\var{full name}, \var{email address})} parsed Return a pair \code{(\var{full name}, \var{email address})} parsed
from the string returned by \code{getheader(\var{name})}. If no from the string returned by \code{getheader(\var{name})}. If no
header matching \var{name} exists, return \code{(None, None)}; header matching \var{name} exists, return \code{(None, None)};
@ -110,9 +111,9 @@ Example: If \var{m}'s first \code{From} header contains the string
If the header contained If the header contained
\code{'Jack Jansen <jack@cwi.nl>'} instead, it would yield the \code{'Jack Jansen <jack@cwi.nl>'} instead, it would yield the
exact same result. exact same result.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{getaddrlist}{name} \begin{methoddesc}{getaddrlist}{name}
This is similar to \code{getaddr(\var{list})}, but parses a header This is similar to \code{getaddr(\var{list})}, but parses a header
containing a list of email addresses (e.g. a \code{To} header) and containing a list of email addresses (e.g. a \code{To} header) and
returns a list of \code{(\var{full name}, \var{email address})} pairs returns a list of \code{(\var{full name}, \var{email address})} pairs
@ -121,9 +122,9 @@ header matching \var{name}, return an empty list.
XXX The current version of this function is not really correct. It XXX The current version of this function is not really correct. It
yields bogus results if a full name contains a comma. yields bogus results if a full name contains a comma.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{getdate}{name} \begin{methoddesc}{getdate}{name}
Retrieve a header using \method{getheader()} and parse it into a 9-tuple Retrieve a header using \method{getheader()} and parse it into a 9-tuple
compatible with \function{time.mktime()}. If there is no header matching compatible with \function{time.mktime()}. If there is no header matching
\var{name}, or it is unparsable, return \code{None}. \var{name}, or it is unparsable, return \code{None}.
@ -132,32 +133,33 @@ Date parsing appears to be a black art, and not all mailers adhere to
the standard. While it has been tested and found correct on a large the standard. While it has been tested and found correct on a large
collection of email from many sources, it is still possible that this collection of email from many sources, it is still possible that this
function may occasionally yield an incorrect result. function may occasionally yield an incorrect result.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{getdate_tz}{name} \begin{methoddesc}{getdate_tz}{name}
Retrieve a header using \method{getheader()} and parse it into a Retrieve a header using \method{getheader()} and parse it into a
10-tuple; the first 9 elements will make a tuple compatible with 10-tuple; the first 9 elements will make a tuple compatible with
\function{time.mktime()}, and the 10th is a number giving the offset \function{time.mktime()}, and the 10th is a number giving the offset
of the date's timezone from UTC. Similarly to \method{getdate()}, if of the date's timezone from UTC. Similarly to \method{getdate()}, if
there is no header matching \var{name}, or it is unparsable, return there is no header matching \var{name}, or it is unparsable, return
\code{None}. \code{None}.
\end{funcdesc} \end{methoddesc}
\class{Message} instances also support a read-only mapping interface. \class{Message} instances also support a read-only mapping interface.
In particular: \code{\var{m}[name]} is the same as In particular: \code{\var{m}[name]} is like
\code{\var{m}.getheader(name)}; and \code{len(\var{m})}, \code{\var{m}.getheader(name)} but raises \exception{KeyError} if
there is no matching header; and \code{len(\var{m})},
\code{\var{m}.has_key(name)}, \code{\var{m}.keys()}, \code{\var{m}.has_key(name)}, \code{\var{m}.keys()},
\code{\var{m}.values()} and \code{\var{m}.items()} act as expected \code{\var{m}.values()} and \code{\var{m}.items()} act as expected
(and consistently). (and consistently).
Finally, \class{Message} instances have two public instance variables: Finally, \class{Message} instances have two public instance variables:
\begin{datadesc}{headers} \begin{memberdesc}{headers}
A list containing the entire set of header lines, in the order in A list containing the entire set of header lines, in the order in
which they were read. Each line contains a trailing newline. The which they were read. Each line contains a trailing newline. The
blank line terminating the headers is not contained in the list. blank line terminating the headers is not contained in the list.
\end{datadesc} \end{memberdesc}
\begin{datadesc}{fp} \begin{memberdesc}{fp}
The file object passed at instantiation time. The file object passed at instantiation time.
\end{datadesc} \end{memberdesc}

50
Doc/librfc822.tex
View File

@ -62,41 +62,42 @@ switch dates. Not enough to worry about for common use.
\end{funcdesc} \end{funcdesc}
\subsection{Message Objects} \subsection{Message Objects}
\label{message-objects}
A \class{Message} instance has the following methods: A \class{Message} instance has the following methods:
\begin{funcdesc}{rewindbody}{} \begin{methoddesc}{rewindbody}{}
Seek to the start of the message body. This only works if the file Seek to the start of the message body. This only works if the file
object is seekable. object is seekable.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{getallmatchingheaders}{name} \begin{methoddesc}{getallmatchingheaders}{name}
Return a list of lines consisting of all headers matching Return a list of lines consisting of all headers matching
\var{name}, if any. Each physical line, whether it is a continuation \var{name}, if any. Each physical line, whether it is a continuation
line or not, is a separate list item. Return the empty list if no line or not, is a separate list item. Return the empty list if no
header matches \var{name}. header matches \var{name}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{getfirstmatchingheader}{name} \begin{methoddesc}{getfirstmatchingheader}{name}
Return a list of lines comprising the first header matching Return a list of lines comprising the first header matching
\var{name}, and its continuation line(s), if any. Return \code{None} \var{name}, and its continuation line(s), if any. Return \code{None}
if there is no header matching \var{name}. if there is no header matching \var{name}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{getrawheader}{name} \begin{methoddesc}{getrawheader}{name}
Return a single string consisting of the text after the colon in the Return a single string consisting of the text after the colon in the
first header matching \var{name}. This includes leading whitespace, first header matching \var{name}. This includes leading whitespace,
the trailing linefeed, and internal linefeeds and whitespace if there the trailing linefeed, and internal linefeeds and whitespace if there
any continuation line(s) were present. Return \code{None} if there is any continuation line(s) were present. Return \code{None} if there is
no header matching \var{name}. no header matching \var{name}.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{getheader}{name} \begin{methoddesc}{getheader}{name}
Like \code{getrawheader(\var{name})}, but strip leading and trailing Like \code{getrawheader(\var{name})}, but strip leading and trailing
whitespace. Internal whitespace is not stripped. whitespace. Internal whitespace is not stripped.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{getaddr}{name} \begin{methoddesc}{getaddr}{name}
Return a pair \code{(\var{full name}, \var{email address})} parsed Return a pair \code{(\var{full name}, \var{email address})} parsed
from the string returned by \code{getheader(\var{name})}. If no from the string returned by \code{getheader(\var{name})}. If no
header matching \var{name} exists, return \code{(None, None)}; header matching \var{name} exists, return \code{(None, None)};
@ -110,9 +111,9 @@ Example: If \var{m}'s first \code{From} header contains the string
If the header contained If the header contained
\code{'Jack Jansen <jack@cwi.nl>'} instead, it would yield the \code{'Jack Jansen <jack@cwi.nl>'} instead, it would yield the
exact same result. exact same result.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{getaddrlist}{name} \begin{methoddesc}{getaddrlist}{name}
This is similar to \code{getaddr(\var{list})}, but parses a header This is similar to \code{getaddr(\var{list})}, but parses a header
containing a list of email addresses (e.g. a \code{To} header) and containing a list of email addresses (e.g. a \code{To} header) and
returns a list of \code{(\var{full name}, \var{email address})} pairs returns a list of \code{(\var{full name}, \var{email address})} pairs
@ -121,9 +122,9 @@ header matching \var{name}, return an empty list.
XXX The current version of this function is not really correct. It XXX The current version of this function is not really correct. It
yields bogus results if a full name contains a comma. yields bogus results if a full name contains a comma.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{getdate}{name} \begin{methoddesc}{getdate}{name}
Retrieve a header using \method{getheader()} and parse it into a 9-tuple Retrieve a header using \method{getheader()} and parse it into a 9-tuple
compatible with \function{time.mktime()}. If there is no header matching compatible with \function{time.mktime()}. If there is no header matching
\var{name}, or it is unparsable, return \code{None}. \var{name}, or it is unparsable, return \code{None}.
@ -132,32 +133,33 @@ Date parsing appears to be a black art, and not all mailers adhere to
the standard. While it has been tested and found correct on a large the standard. While it has been tested and found correct on a large
collection of email from many sources, it is still possible that this collection of email from many sources, it is still possible that this
function may occasionally yield an incorrect result. function may occasionally yield an incorrect result.
\end{funcdesc} \end{methoddesc}
\begin{funcdesc}{getdate_tz}{name} \begin{methoddesc}{getdate_tz}{name}
Retrieve a header using \method{getheader()} and parse it into a Retrieve a header using \method{getheader()} and parse it into a
10-tuple; the first 9 elements will make a tuple compatible with 10-tuple; the first 9 elements will make a tuple compatible with
\function{time.mktime()}, and the 10th is a number giving the offset \function{time.mktime()}, and the 10th is a number giving the offset
of the date's timezone from UTC. Similarly to \method{getdate()}, if of the date's timezone from UTC. Similarly to \method{getdate()}, if
there is no header matching \var{name}, or it is unparsable, return there is no header matching \var{name}, or it is unparsable, return
\code{None}. \code{None}.
\end{funcdesc} \end{methoddesc}
\class{Message} instances also support a read-only mapping interface. \class{Message} instances also support a read-only mapping interface.
In particular: \code{\var{m}[name]} is the same as In particular: \code{\var{m}[name]} is like
\code{\var{m}.getheader(name)}; and \code{len(\var{m})}, \code{\var{m}.getheader(name)} but raises \exception{KeyError} if
there is no matching header; and \code{len(\var{m})},
\code{\var{m}.has_key(name)}, \code{\var{m}.keys()}, \code{\var{m}.has_key(name)}, \code{\var{m}.keys()},
\code{\var{m}.values()} and \code{\var{m}.items()} act as expected \code{\var{m}.values()} and \code{\var{m}.items()} act as expected
(and consistently). (and consistently).
Finally, \class{Message} instances have two public instance variables: Finally, \class{Message} instances have two public instance variables:
\begin{datadesc}{headers} \begin{memberdesc}{headers}
A list containing the entire set of header lines, in the order in A list containing the entire set of header lines, in the order in
which they were read. Each line contains a trailing newline. The which they were read. Each line contains a trailing newline. The
blank line terminating the headers is not contained in the list. blank line terminating the headers is not contained in the list.
\end{datadesc} \end{memberdesc}
\begin{datadesc}{fp} \begin{memberdesc}{fp}
The file object passed at instantiation time. The file object passed at instantiation time.
\end{datadesc} \end{memberdesc}