home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / pyhtmldoc / n / nntp_objec next >
Text File  |  1996-11-14  |  7KB  |  120 lines
  1. <TITLE>NNTP Objects -- Python library reference</TITLE>
  2. Prev: <A HREF="../n/nntplib" TYPE="Prev">nntplib</A>  
  3. Up: <A HREF="../n/nntplib" TYPE="Up">nntplib</A>  
  4. Top: <A HREF="../t/top" TYPE="Top">Top</A>  
  5. <H2>10.6.1. NNTP Objects</H2>
  6. NNTP instances have the following methods.  The <VAR>response</VAR> that is
  7. returned as the first item in the return tuple of almost all methods
  8. is the server's response: a string beginning with a three-digit code.
  9. If the server's response indicates an error, the method raises one of
  10. the above exceptions.
  11. <P>
  12. <DL><DT><B>getwelcome</B> () -- Method on NNTP object<DD>
  13. Return the welcome message sent by the server in reply to the initial
  14. connection.  (This message sometimes contains disclaimers or help
  15. information that may be relevant to the user.)
  16. </DL>
  17. <DL><DT><B>set_debuglevel</B> (<VAR>level</VAR>) -- Method on NNTP object<DD>
  18. Set the instance's debugging level.  This controls the amount of
  19. debugging output printed.  The default, 0, produces no debugging
  20. output.  A value of 1 produces a moderate amount of debugging output,
  21. generally a single line per request or response.  A value of 2 or
  22. higher produces the maximum amount of debugging output, logging each
  23. line sent and received on the connection (including message text).
  24. </DL>
  25. <DL><DT><B>newgroups</B> (<VAR>date</VAR>, <VAR>time</VAR>) -- Method on NNTP object<DD>
  26. Send a `<SAMP>NEWGROUPS</SAMP>' command.  The <VAR>date</VAR> argument should be a
  27. string of the form <CODE>"<VAR>yy</VAR><VAR>mm</VAR><VAR>dd</VAR>"</CODE> indicating the
  28. date, and <VAR>time</VAR> should be a string of the form
  29. <CODE>"<VAR>hh</VAR><VAR>mm</VAR><VAR>ss</VAR>"</CODE> indicating the time.  Return a pair
  30. <CODE>(<VAR>response</VAR>, <VAR>groups</VAR>)</CODE> where <VAR>groups</VAR> is a list of
  31. group names that are new since the given date and time.
  32. </DL>
  33. <DL><DT><B>newnews</B> (<VAR>group</VAR>, <VAR>date</VAR>, <VAR>time</VAR>) -- Method on NNTP object<DD>
  34. Send a `<SAMP>NEWNEWS</SAMP>' command.  Here, <VAR>group</VAR> is a group name or
  35. <CODE>"*"</CODE>, and <VAR>date</VAR> and <VAR>time</VAR> have the same meaning as for
  36. <CODE>newgroups()</CODE>.  Return a pair <CODE>(<VAR>response</VAR>,
  37. <VAR>articles</VAR>)</CODE> where <VAR>articles</VAR> is a list of article ids.
  38. </DL>
  39. <DL><DT><B>list</B> () -- Method on NNTP object<DD>
  40. Send a `<SAMP>LIST</SAMP>' command.  Return a pair <CODE>(<VAR>response</VAR>,
  41. <VAR>list</VAR>)</CODE> where <VAR>list</VAR> is a list of tuples.  Each tuple has the
  42. form <CODE>(<VAR>group</VAR>, <VAR>last</VAR>, <VAR>first</VAR>, <VAR>flag</VAR>)</CODE>, where
  43. <VAR>group</VAR> is a group name, <VAR>last</VAR> and <VAR>first</VAR> are the last
  44. and first article numbers (as strings), and <VAR>flag</VAR> is <CODE>'y'</CODE>
  45. if posting is allowed, <CODE>'n'</CODE> if not, and <CODE>'m'</CODE> if the
  46. newsgroup is moderated.  (Note the ordering: <VAR>last</VAR>, <VAR>first</VAR>.)
  47. </DL>
  48. <DL><DT><B>group</B> (<VAR>name</VAR>) -- Method on NNTP object<DD>
  49. Send a `<SAMP>GROUP</SAMP>' command, where <VAR>name</VAR> is the group name.
  50. Return a tuple <CODE>(<VAR>response</VAR>, <VAR>count</VAR>, <VAR>first</VAR>,
  51. <VAR>last</VAR>, <VAR>name</VAR>)</CODE> where <VAR>count</VAR> is the (estimated) number
  52. of articles in the group, <VAR>first</VAR> is the first article number in
  53. the group, <VAR>last</VAR> is the last article number in the group, and
  54. <VAR>name</VAR> is the group name.  The numbers are returned as strings.
  55. </DL>
  56. <DL><DT><B>help</B> () -- Method on NNTP object<DD>
  57. Send a `<SAMP>HELP</SAMP>' command.  Return a pair <CODE>(<VAR>response</VAR>,
  58. <VAR>list</VAR>)</CODE> where <VAR>list</VAR> is a list of help strings.
  59. </DL>
  60. <DL><DT><B>stat</B> (<VAR>id</VAR>) -- Method on NNTP object<DD>
  61. Send a `<SAMP>STAT</SAMP>' command, where <VAR>id</VAR> is the message id (enclosed
  62. in `<SAMP><</SAMP>' and `<SAMP>></SAMP>') or an article number (as a string).
  63. Return a triple <CODE>(varresponse, <VAR>number</VAR>, <VAR>id</VAR>)</CODE> where
  64. <VAR>number</VAR> is the article number (as a string) and <VAR>id</VAR> is the
  65. article id  (enclosed in `<SAMP><</SAMP>' and `<SAMP>></SAMP>').
  66. </DL>
  67. <DL><DT><B>next</B> () -- Method on NNTP object<DD>
  68. Send a `<SAMP>NEXT</SAMP>' command.  Return as for <CODE>stat()</CODE>.
  69. </DL>
  70. <DL><DT><B>last</B> () -- Method on NNTP object<DD>
  71. Send a `<SAMP>LAST</SAMP>' command.  Return as for <CODE>stat()</CODE>.
  72. </DL>
  73. <DL><DT><B>head</B> (<VAR>id</VAR>) -- Method on NNTP object<DD>
  74. Send a `<SAMP>HEAD</SAMP>' command, where <VAR>id</VAR> has the same meaning as for
  75. <CODE>stat()</CODE>.  Return a pair <CODE>(<VAR>response</VAR>, <VAR>list</VAR>)</CODE>
  76. where <VAR>list</VAR> is a list of the article's headers (an uninterpreted
  77. list of lines, without trailing newlines).
  78. </DL>
  79. <DL><DT><B>body</B> (<VAR>id</VAR>) -- Method on NNTP object<DD>
  80. Send a `<SAMP>BODY</SAMP>' command, where <VAR>id</VAR> has the same meaning as for
  81. <CODE>stat()</CODE>.  Return a pair <CODE>(<VAR>response</VAR>, <VAR>list</VAR>)</CODE>
  82. where <VAR>list</VAR> is a list of the article's body text (an
  83. uninterpreted list of lines, without trailing newlines).
  84. </DL>
  85. <DL><DT><B>article</B> (<VAR>id</VAR>) -- Method on NNTP object<DD>
  86. Send a `<SAMP>ARTICLE</SAMP>' command, where <VAR>id</VAR> has the same meaning as
  87. for <CODE>stat()</CODE>.  Return a pair <CODE>(<VAR>response</VAR>, <VAR>list</VAR>)</CODE>
  88. where <VAR>list</VAR> is a list of the article's header and body text (an
  89. uninterpreted list of lines, without trailing newlines).
  90. </DL>
  91. <DL><DT><B>slave</B> () -- Method on NNTP object<DD>
  92. Send a `<SAMP>SLAVE</SAMP>' command.  Return the server's <VAR>response</VAR>.
  93. </DL>
  94. <DL><DT><B>xhdr</B> (<VAR>header</VAR>, <VAR>string</VAR>) -- Method on NNTP object<DD>
  95. Send an `<SAMP>XHDR</SAMP>' command.  This command is not defined in the RFC
  96. but is a common extension.  The <VAR>header</VAR> argument is a header
  97. keyword, e.g. <CODE>"subject"</CODE>.  The <VAR>string</VAR> argument should have
  98. the form <CODE>"<VAR>first</VAR>-<VAR>last</VAR>"</CODE> where <VAR>first</VAR> and
  99. <VAR>last</VAR> are the first and last article numbers to search.  Return a
  100. pair <CODE>(<VAR>response</VAR>, <VAR>list</VAR>)</CODE>, where <VAR>list</VAR> is a list of
  101. pairs <CODE>(<VAR>id</VAR>, <VAR>text</VAR>)</CODE>, where <VAR>id</VAR> is an article id
  102. (as a string) and <VAR>text</VAR> is the text of the requested header for
  103. that article.
  104. </DL>
  105. <DL><DT><B>post</B> (<VAR>file</VAR>) -- Method on NNTP object<DD>
  106. Post an article using the `<SAMP>POST</SAMP>' command.  The <VAR>file</VAR>
  107. argument is an open file object which is read until EOF using its
  108. <CODE>readline()</CODE> method.  It should be a well-formed news article,
  109. including the required headers.  The <CODE>post()</CODE> method
  110. automatically escapes lines beginning with `<SAMP>.</SAMP>'.
  111. </DL>
  112. <DL><DT><B>ihave</B> (<VAR>id</VAR>, <VAR>file</VAR>) -- Method on NNTP object<DD>
  113. Send an `<SAMP>IHAVE</SAMP>' command.  If the response is not an error, treat
  114. <VAR>file</VAR> exactly as for the <CODE>post()</CODE> method.
  115. </DL>
  116. <DL><DT><B>quit</B> () -- Method on NNTP object<DD>
  117. Send a `<SAMP>QUIT</SAMP>' command and close the connection.  Once this method
  118. has been called, no other methods of the NNTP object should be called.
  119. </DL>
  120.