<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<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>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<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>
<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>
<!--End of Navigation Panel-->
<H2><A NAME=
"SECTION00131110000000000000000"></A><A NAME=
"nntp-objects"></A>
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
<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>
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><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>
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
<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>
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><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>
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><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>
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>,
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><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>
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>.
<span class=
"versionnote">New in version
2.4.
</span>
<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>
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.
This elides the response code from the server. If the response code is
needed, use
<tt class=
"method">descriptions()
</tt>.
<span class=
"versionnote">New in version
2.4.
</span>
<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>
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><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>
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><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>
Send a
"<tt class="samp
">STAT</tt>" command, where
<var>id
</var> is the message id (enclosed
in
"<tt class="character
"><</tt>" and
"<tt class="character
">></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
"><</tt>" and
"<tt class="character
">></tt>").
<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>
Send a
"<tt class="samp
">NEXT</tt>" command. Return as for
<tt class=
"method">stat()
</tt>.
<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>
Send a
"<tt class="samp
">LAST</tt>" command. Return as for
<tt class=
"method">stat()
</tt>.
<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>
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><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>
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><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>
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><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>
Send a
"<tt class="samp
">SLAVE</tt>" command. Return the server's
<var>response
</var>.
<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>
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
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><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>
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><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>
Send an
"<tt class="samp
">IHAVE</tt>" command.
<var>id
</var> is a message id (enclosed in
"<tt class="character
"><</tt>" and
"<tt class="character
">></tt>").
If the response is not an error, treat
<var>file
</var> exactly as for the
<tt class=
"method">post()
</tt> method.
<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>
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
<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>
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
RFC2980 says ``It is suggested that this extension be deprecated''. Use
<tt class=
"method">descriptions()
</tt> or
<tt class=
"method">description()
</tt> instead.
<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>
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
<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>
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><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>
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.
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<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>
<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>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.