[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / html / python / lib / nntp-objects.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="prev" href="module-nntplib.html" />
<link rel="parent" href="module-nntplib.html" />
<link rel="next" href="module-smtplib.html" />
<meta name='aesop' content='information' />
<title>11.11.1 NNTP Objects </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="11.11 nntplib  "
  href="module-nntplib.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="11.11 nntplib  "
  href="module-nntplib.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="11.12 smtplib  "
  href="module-smtplib.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-nntplib.html">11.11 nntplib  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-nntplib.html">11.11 nntplib  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-smtplib.html">11.12 smtplib  </A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION00131110000000000000000"></A><A NAME="nntp-objects"></A>
<BR>
11.11.1 NNTP Objects 
</H2>

<P>
NNTP instances have the following methods.  The <var>response</var> that is
returned as the first item in the return tuple of almost all methods
is the server's response: a string beginning with a three-digit code.
If the server's response indicates an error, the method raises one of
the above exceptions.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3462' xml:id='l2h-3462' class="method">getwelcome</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the welcome message sent by the server in reply to the initial
connection.  (This message sometimes contains disclaimers or help
information that may be relevant to the user.)
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3463' xml:id='l2h-3463' class="method">set_debuglevel</tt></b>(</nobr></td>
  <td><var>level</var>)</td></tr></table></dt>
<dd>
Set the instance's debugging level.  This controls the amount of
debugging output printed.  The default, <code>0</code>, produces no debugging
output.  A value of <code>1</code> produces a moderate amount of debugging
output, generally a single line per request or response.  A value of
<code>2</code> or higher produces the maximum amount of debugging output,
logging each line sent and received on the connection (including
message text).
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3464' xml:id='l2h-3464' class="method">newgroups</tt></b>(</nobr></td>
  <td><var>date, time, </var><big>[</big><var>file</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Send a "<tt class="samp">NEWGROUPS</tt>" command.  The <var>date</var> argument should be a
string of the form <code>'<var>yy</var><var>mm</var><var>dd</var>'</code> indicating the
date, and <var>time</var> should be a string of the form
<code>'<var>hh</var><var>mm</var><var>ss</var>'</code> indicating the time.  Return a pair
<code>(<var>response</var>, <var>groups</var>)</code> where <var>groups</var> is a list of
group names that are new since the given date and time.
If the <var>file</var> parameter is supplied, then the output of the 
"<tt class="samp">NEWGROUPS</tt>" command is stored in a file.  If <var>file</var> is a string, 
then the method will open a file object with that name, write to it 
then close it.  If <var>file</var> is a file object, then it will start
calling <tt class="method">write()</tt> on it to store the lines of the command output.
If <var>file</var> is supplied, then the returned <var>list</var> is an empty list.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3465' xml:id='l2h-3465' class="method">newnews</tt></b>(</nobr></td>
  <td><var>group, date, time, </var><big>[</big><var>file</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Send a "<tt class="samp">NEWNEWS</tt>" command.  Here, <var>group</var> is a group name or
<code>'*'</code>, and <var>date</var> and <var>time</var> have the same meaning as for
<tt class="method">newgroups()</tt>.  Return a pair <code>(<var>response</var>,
<var>articles</var>)</code> where <var>articles</var> is a list of message ids.
If the <var>file</var> parameter is supplied, then the output of the 
"<tt class="samp">NEWNEWS</tt>" command is stored in a file.  If <var>file</var> is a string, 
then the method will open a file object with that name, write to it 
then close it.  If <var>file</var> is a file object, then it will start
calling <tt class="method">write()</tt> on it to store the lines of the command output.
If <var>file</var> is supplied, then the returned <var>list</var> is an empty list.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3466' xml:id='l2h-3466' class="method">list</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>file</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Send a "<tt class="samp">LIST</tt>" command.  Return a pair <code>(<var>response</var>,
<var>list</var>)</code> where <var>list</var> is a list of tuples.  Each tuple has the
form <code>(<var>group</var>, <var>last</var>, <var>first</var>, <var>flag</var>)</code>, where
<var>group</var> is a group name, <var>last</var> and <var>first</var> are the last
and first article numbers (as strings), and <var>flag</var> is
<code>'y'</code> if posting is allowed, <code>'n'</code> if not, and <code>'m'</code> if
the newsgroup is moderated.  (Note the ordering: <var>last</var>,
<var>first</var>.)
If the <var>file</var> parameter is supplied, then the output of the 
"<tt class="samp">LIST</tt>" command is stored in a file.  If <var>file</var> is a string, 
then the method will open a file object with that name, write to it 
then close it.  If <var>file</var> is a file object, then it will start
calling <tt class="method">write()</tt> on it to store the lines of the command output.
If <var>file</var> is supplied, then the returned <var>list</var> is an empty list.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3467' xml:id='l2h-3467' class="method">descriptions</tt></b>(</nobr></td>
  <td><var>grouppattern</var>)</td></tr></table></dt>
<dd>
Send a "<tt class="samp">LIST NEWSGROUPS</tt>" command, where <var>grouppattern</var> is a wildmat
string as specified in RFC2980 (it's essentially the same as DOS or UNIX
shell wildcard strings).  Return a pair <code>(<var>response</var>,
<var>list</var>)</code>, where <var>list</var> is a list of tuples containing
<code>(<var>name</var>, <var>title</var>)</code>.

<P>

<span class="versionnote">New in version 2.4.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3468' xml:id='l2h-3468' class="method">description</tt></b>(</nobr></td>
  <td><var>group</var>)</td></tr></table></dt>
<dd>
Get a description for a single group <var>group</var>.  If more than one group
matches (if 'group' is a real wildmat string), return the first match.  
If no group matches, return an empty string.

<P>
This elides the response code from the server.  If the response code is
needed, use <tt class="method">descriptions()</tt>.

<P>

<span class="versionnote">New in version 2.4.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3469' xml:id='l2h-3469' class="method">group</tt></b>(</nobr></td>
  <td><var>name</var>)</td></tr></table></dt>
<dd>
Send a "<tt class="samp">GROUP</tt>" command, where <var>name</var> is the group name.
Return a tuple <code>(<var>response</var>, <var>count</var>, <var>first</var>,
<var>last</var>, <var>name</var>)</code> where <var>count</var> is the (estimated) number
of articles in the group, <var>first</var> is the first article number in
the group, <var>last</var> is the last article number in the group, and
<var>name</var> is the group name.  The numbers are returned as strings.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3470' xml:id='l2h-3470' class="method">help</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>file</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Send a "<tt class="samp">HELP</tt>" command.  Return a pair <code>(<var>response</var>,
<var>list</var>)</code> where <var>list</var> is a list of help strings.
If the <var>file</var> parameter is supplied, then the output of the 
"<tt class="samp">HELP</tt>" command is stored in a file.  If <var>file</var> is a string, 
then the method will open a file object with that name, write to it 
then close it.  If <var>file</var> is a file object, then it will start
calling <tt class="method">write()</tt> on it to store the lines of the command output.
If <var>file</var> is supplied, then the returned <var>list</var> is an empty list.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3471' xml:id='l2h-3471' class="method">stat</tt></b>(</nobr></td>
  <td><var>id</var>)</td></tr></table></dt>
<dd>
Send a "<tt class="samp">STAT</tt>" command, where <var>id</var> is the message id (enclosed
in "<tt class="character">&lt;</tt>" and "<tt class="character">&gt;</tt>") or an article number (as a string).
Return a triple <code>(<var>response</var>, <var>number</var>, <var>id</var>)</code> where
<var>number</var> is the article number (as a string) and <var>id</var> is the
message id  (enclosed in "<tt class="character">&lt;</tt>" and "<tt class="character">&gt;</tt>").
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3472' xml:id='l2h-3472' class="method">next</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Send a "<tt class="samp">NEXT</tt>" command.  Return as for <tt class="method">stat()</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3473' xml:id='l2h-3473' class="method">last</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Send a "<tt class="samp">LAST</tt>" command.  Return as for <tt class="method">stat()</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3474' xml:id='l2h-3474' class="method">head</tt></b>(</nobr></td>
  <td><var>id</var>)</td></tr></table></dt>
<dd>
Send a "<tt class="samp">HEAD</tt>" command, where <var>id</var> has the same meaning as for
<tt class="method">stat()</tt>.  Return a tuple
<code>(<var>response</var>, <var>number</var>, <var>id</var>, <var>list</var>)</code>
where the first three are the same as for <tt class="method">stat()</tt>,
and <var>list</var> is a list of the article's headers (an uninterpreted
list of lines, without trailing newlines).
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3475' xml:id='l2h-3475' class="method">body</tt></b>(</nobr></td>
  <td><var>id,</var><big>[</big><var>file</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Send a "<tt class="samp">BODY</tt>" command, where <var>id</var> has the same meaning as for
<tt class="method">stat()</tt>.  If the <var>file</var> parameter is supplied, then
the body is stored in a file.  If <var>file</var> is a string, then
the method will open a file object with that name, write to it then close it.
If <var>file</var> is a file object, then it will start calling
<tt class="method">write()</tt> on it to store the lines of the body.
Return as for <tt class="method">head()</tt>.  If <var>file</var> is supplied, then
the returned <var>list</var> is an empty list.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3476' xml:id='l2h-3476' class="method">article</tt></b>(</nobr></td>
  <td><var>id</var>)</td></tr></table></dt>
<dd>
Send an "<tt class="samp">ARTICLE</tt>" command, where <var>id</var> has the same meaning as
for <tt class="method">stat()</tt>.  Return as for <tt class="method">head()</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3477' xml:id='l2h-3477' class="method">slave</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Send a "<tt class="samp">SLAVE</tt>" command.  Return the server's <var>response</var>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3478' xml:id='l2h-3478' class="method">xhdr</tt></b>(</nobr></td>
  <td><var>header, string, </var><big>[</big><var>file</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Send an "<tt class="samp">XHDR</tt>" command.  This command is not defined in the RFC
but is a common extension.  The <var>header</var> argument is a header
keyword, e.g. <code>'subject'</code>.  The <var>string</var> argument should have
the form <code>'<var>first</var>-<var>last</var>'</code> where <var>first</var> and
<var>last</var> are the first and last article numbers to search.  Return a
pair <code>(<var>response</var>, <var>list</var>)</code>, where <var>list</var> is a list of
pairs <code>(<var>id</var>, <var>text</var>)</code>, where <var>id</var> is an article number
(as a string) and <var>text</var> is the text of the requested header for
that article.
If the <var>file</var> parameter is supplied, then the output of the 
"<tt class="samp">XHDR</tt>" command is stored in a file.  If <var>file</var> is a string, 
then the method will open a file object with that name, write to it 
then close it.  If <var>file</var> is a file object, then it will start
calling <tt class="method">write()</tt> on it to store the lines of the command output.
If <var>file</var> is supplied, then the returned <var>list</var> is an empty list.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3479' xml:id='l2h-3479' class="method">post</tt></b>(</nobr></td>
  <td><var>file</var>)</td></tr></table></dt>
<dd>
Post an article using the "<tt class="samp">POST</tt>" command.  The <var>file</var>
argument is an open file object which is read until EOF using its
<tt class="method">readline()</tt> method.  It should be a well-formed news article,
including the required headers.  The <tt class="method">post()</tt> method
automatically escapes lines beginning with "<tt class="samp">.</tt>".
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3480' xml:id='l2h-3480' class="method">ihave</tt></b>(</nobr></td>
  <td><var>id, file</var>)</td></tr></table></dt>
<dd>
Send an "<tt class="samp">IHAVE</tt>" command. <var>id</var> is a message id (enclosed in 
"<tt class="character">&lt;</tt>" and "<tt class="character">&gt;</tt>").
If the response is not an error, treat
<var>file</var> exactly as for the <tt class="method">post()</tt> method.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3481' xml:id='l2h-3481' class="method">date</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return a triple <code>(<var>response</var>, <var>date</var>, <var>time</var>)</code>,
containing the current date and time in a form suitable for the
<tt class="method">newnews()</tt> and <tt class="method">newgroups()</tt> methods.
This is an optional NNTP extension, and may not be supported by all
servers.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3482' xml:id='l2h-3482' class="method">xgtitle</tt></b>(</nobr></td>
  <td><var>name, </var><big>[</big><var>file</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Process an "<tt class="samp">XGTITLE</tt>" command, returning a pair <code>(<var>response</var>,
<var>list</var>)</code>, where <var>list</var> is a list of tuples containing
<code>(<var>name</var>, <var>title</var>)</code>.
If the <var>file</var> parameter is supplied, then the output of the 
"<tt class="samp">XGTITLE</tt>" command is stored in a file.  If <var>file</var> is a string, 
then the method will open a file object with that name, write to it 
then close it.  If <var>file</var> is a file object, then it will start
calling <tt class="method">write()</tt> on it to store the lines of the command output.
If <var>file</var> is supplied, then the returned <var>list</var> is an empty list.
This is an optional NNTP extension, and may not be supported by all
servers.

<P>
RFC2980 says ``It is suggested that this extension be deprecated''.  Use
<tt class="method">descriptions()</tt> or <tt class="method">description()</tt> instead.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3483' xml:id='l2h-3483' class="method">xover</tt></b>(</nobr></td>
  <td><var>start, end, </var><big>[</big><var>file</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Return a pair <code>(<var>resp</var>, <var>list</var>)</code>.  <var>list</var> is a list
of tuples, one for each article in the range delimited by the <var>start</var>
and <var>end</var> article numbers.  Each tuple is of the form
<code>(<var>article number</var>, <var>subject</var>, <var>poster</var>, <var>date</var>,
<var>id</var>, <var>references</var>, <var>size</var>, <var>lines</var>)</code>.
If the <var>file</var> parameter is supplied, then the output of the 
"<tt class="samp">XOVER</tt>" command is stored in a file.  If <var>file</var> is a string, 
then the method will open a file object with that name, write to it 
then close it.  If <var>file</var> is a file object, then it will start
calling <tt class="method">write()</tt> on it to store the lines of the command output.
If <var>file</var> is supplied, then the returned <var>list</var> is an empty list.
This is an optional NNTP extension, and may not be supported by all
servers.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3484' xml:id='l2h-3484' class="method">xpath</tt></b>(</nobr></td>
  <td><var>id</var>)</td></tr></table></dt>
<dd>
Return a pair <code>(<var>resp</var>, <var>path</var>)</code>, where <var>path</var> is the
directory path to the article with message ID <var>id</var>.  This is an
optional NNTP extension, and may not be supported by all servers.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3485' xml:id='l2h-3485' class="method">quit</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Send a "<tt class="samp">QUIT</tt>" command and close the connection.  Once this method
has been called, no other methods of the NNTP object should be called.
</dl>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="11.11 nntplib  "
  href="module-nntplib.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="11.11 nntplib  "
  href="module-nntplib.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="11.12 smtplib  "
  href="module-smtplib.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-nntplib.html">11.11 nntplib  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-nntplib.html">11.11 nntplib  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-smtplib.html">11.12 smtplib  </A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>