diff options
| -rw-r--r-- | Doc/lib.tex | 12 | ||||
| -rw-r--r-- | Doc/lib/lib.tex | 12 | ||||
| -rw-r--r-- | Doc/lib/libftplib.tex | 200 | ||||
| -rw-r--r-- | Doc/lib/libgopherlib.tex | 26 | ||||
| -rw-r--r-- | Doc/lib/libmimetools.tex | 92 | ||||
| -rw-r--r-- | Doc/lib/libnntplib.tex | 48 | ||||
| -rw-r--r-- | Doc/lib/libprofile.tex | 2 | ||||
| -rw-r--r-- | Doc/libftplib.tex | 200 | ||||
| -rw-r--r-- | Doc/libgopherlib.tex | 26 | ||||
| -rw-r--r-- | Doc/libmimetools.tex | 92 | ||||
| -rw-r--r-- | Doc/libnntplib.tex | 48 | ||||
| -rw-r--r-- | Doc/libprofile.tex | 2 |
12 files changed, 738 insertions, 22 deletions
diff --git a/Doc/lib.tex b/Doc/lib.tex index 4194dbf..3a25342 100644 --- a/Doc/lib.tex +++ b/Doc/lib.tex @@ -98,16 +98,16 @@ language. \input{libwww} % WWW EXTENSIONS \input{libcgi} +\input{liburllib} +\input{libhttplib} \input{libftplib} \input{libgopherlib} -\input{libhtmllib} -\input{libhttplib} -\input{libmimetools} \input{libnntplib} -\input{librfc822} -\input{libsgmllib} -\input{liburllib} \input{liburlparse} +\input{libhtmllib} +\input{libsgmllib} +\input{librfc822} +\input{libmimetools} \input{libmm} % MULTIMEDIA EXTENSIONS \input{libaudioop} diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 4194dbf..3a25342 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -98,16 +98,16 @@ language. \input{libwww} % WWW EXTENSIONS \input{libcgi} +\input{liburllib} +\input{libhttplib} \input{libftplib} \input{libgopherlib} -\input{libhtmllib} -\input{libhttplib} -\input{libmimetools} \input{libnntplib} -\input{librfc822} -\input{libsgmllib} -\input{liburllib} \input{liburlparse} +\input{libhtmllib} +\input{libsgmllib} +\input{librfc822} +\input{libmimetools} \input{libmm} % MULTIMEDIA EXTENSIONS \input{libaudioop} diff --git a/Doc/lib/libftplib.tex b/Doc/lib/libftplib.tex index f5f7ef3..f78805c 100644 --- a/Doc/lib/libftplib.tex +++ b/Doc/lib/libftplib.tex @@ -3,4 +3,202 @@ \renewcommand{\indexsubitem}{(in module ftplib)} -To be provided. +This module defines the class \code{FTP} and a few related items. The +\code{FTP} class implements the client side of the FTP protocol. You +can use this to write Python programs that perform a variety of +automated FTP jobs, such as mirroring other ftp servers. It is also +used bu the module \code{urllib} to handle URLs that use FTP. For +more information on FTP (File Transfer Protocol), see Internet RFC +959. + +Here's a sample session using the \code{ftplib} module: + +\begin{verbatim} +>>> from ftplib import FTP +>>> ftp = FTP('ftp.cwi.nl') # connect to host, default port +>>> ftp.login() # default user anonymous, passwd user@hostname +>>> ftp.retrlines('LIST') # list directory contents +total 24418 +drwxrwsr-x 5 ftp-usr pdmaint 1536 Mar 20 09:48 . +dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 .. +-rw-r--r-- 1 ftp-usr pdmaint 5305 Mar 20 09:48 INDEX + . + . + . +>>> ftp.quit() +\end{verbatim} + +The module defines the following items: + +\begin{funcdesc}{FTP}{\optional{host\optional{\, user\, passwd\, acct}}} +Return a new instance of the \code{FTP} class. When +\var{host} is given, the method call \code{connect(\var{host})} is +made. When \var{user} is given, additionally the method call +\code{login(\var{user}, \var{passwd}, \var{acct})} is made (where +\var{passwd} and \var{acct} default to the empty string when not given). +\end{funcdesc} + +\begin{datadesc}{all_errors} +The set of all exceptions (as a tuple) that methods of \code{FTP} +instances may raise as a result of problems with the FTP connection +(as opposed to programming errors made by the caller). This set +includes the four exceptions listed below as well as +\code{socket.error} and \code{IOError}. +\end{datadesc} + +\begin{excdesc}{error_reply} +Exception raised when an unexpected reply is received from the server. +\end{excdesc} + +\begin{excdesc}{error_temp} +Exception raised when an error code in the range 400--499 is received. +\end{excdesc} + +\begin{excdesc}{error_perm} +Exception raised when an error code in the range 500--599 is received. +\end{excdesc} + +\begin{excdesc}{error_proto} +Exception raised when a reply is received from the server that does +not begin with a digit in the range 1--5. +\end{excdesc} + +\subsection{FTP Objects} + +FTP instances have the following methods: + +\renewcommand{\indexsubitem}{(FTP object method)} + +\begin{funcdesc}{set_debuglevel}{level} +Set the instance's debugging level. This controls the amount of +debugging output printed. The default, 0, produces no debugging +output. A value of 1 produces a moderate amount of debugging output, +generally a single line per request. A value of 2 or higher produces +the maximum amount of debugging output, logging each line sent and +received on the control connection. +\end{funcdesc} + +\begin{funcdesc}{connect}{host\optional{\, port}} +Connect to the given host and port. The default port number is 21, as +specified by the FTP protocol specification. It is rarely needed to +specify a different port number. This function should be called only +once for each instance; it should not be called at all if a host was +given when the instance was created. All other methods can only be +used after a connection has been made. +\end{funcdesc} + +\begin{funcdesc}{getwelcome}{} +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.) +\end{funcdesc} + +\begin{funcdesc}{login}{\optional{user\optional{\, passwd\optional{\, acct}}}} +Log in as the given \var{user}. The \var{passwd} and \var{acct} +parameters are optional and default to the empty string. If no +\var{user} is specified, it defaults to \samp{anonymous}. If +\var{user} is \code{anonymous}, the default \var{passwd} is +\samp{\var{realuser}@\var{host}} where \var{realuser} is the real user +name (glanced from the \samp{LOGNAME} or \samp{USER} environment +variable) and \var{host} is the hostname as returned by +\code{socket.gethostname()}. This function should be called only +once for each instance, after a connection has been established; it +should not be called at all if a host and user were given when the +instance was created. Most FTP commands are only allowed after the +client has logged in. +\end{funcdesc} + +\begin{funcdesc}{abort}{} +Abort a file transfer that is in progress. Using this does not always +work, but it's worth a try. +\end{funcdesc} + +\begin{funcdesc}{sendcmd}{command} +Send a simple command string to the server and return the response +string. +\end{funcdesc} + +\begin{funcdesc}{voidcmd}{command} +Send a simple command string to the server and handle the response. +Return nothing if a response code in the range 200--299 is received. +Raise an exception otherwise. +\end{funcdesc} + +\begin{funcdesc}{retrbinary}{command\, callback\, maxblocksize} +Retrieve a file in binary transfer mode. \var{command} should be an +appropriate \samp{RETR} command, i.e.\ \code{"RETR \var{filename}"}. +The \var{callback} function is called for each block of data received, +with a single string argument giving the data block. +The \var{maxblocksize} argument specifies the maximum block size +(which may not be the actual size of the data blocks passed to +\var{callback}). +\end{funcdesc} + +\begin{funcdesc}{retrlines}{command\optional{\, callback}} +Retrieve a file or directory listing in \ASCII{} transfer mode. +var{command} should be an appropriate \samp{RETR} command (see +\code{retrbinary()} or a \samp{LIST} command (usually just the string +\code{"LIST"}). The \var{callback} function is called for each line, +with the trailing CRLF stripped. The default \var{callback} prints +the line to \code{sys.stdout}. +\end{funcdesc} + +\begin{funcdesc}{storbinary}{command\, file\, blocksize} +Store a file in binary transfer mode. \var{command} should be an +appropriate \samp{STOR} command, i.e.\ \code{"STOR \var{filename}"}. +\var{file} is an open file object which is read until EOF using its +\code{read()} method in blocks of size \var{blocksize} to provide the +data to be stored. +\end{funcdesc} + +\begin{funcdesc}{storlines}{command\, file} +Store a file in \ASCII{} transfer mode. \var{command} should be an +appropriate \samp{STOR} command (see \code{storbinary()}). Lines are +read until EOF from the open file object \var{file} using its +\code{readline()} method to privide the data to be stored. +\end{funcdesc} + +\begin{funcdesc}{nlst}{argument\optional{\, \ldots}} +Return a list of files as returned by the \samp{NLST} command. The +optional var{argument} is a directory to list (default is the current +server directory). Multiple arguments can be used to pass +non-standard options to the \samp{NLST} command. +\end{funcdesc} + +\begin{funcdesc}{dir}{argument\optional{\, \ldots}} +Return a directory listing as returned by the \samp{LIST} command, as +a list of lines. The optional var{argument} is a directory to list +(default is the current server directory). Multiple arguments can be +used to pass non-standard options to the \samp{LIST} command. If the +last argument is a function, it is used as a \var{callback} function +as for \code{retrlines()}. +\end{funcdesc} + +\begin{funcdesc}{rename}{fromname\, toname} +Rename file \var{fromname} on the server to \var{toname}. +\end{funcdesc} + +\begin{funcdesc}{cwd}{pathname} +Set the current directory on the server. +\end{funcdesc} + +\begin{funcdesc}{mkd}{pathname} +Create a new directory on the server. +\end{funcdesc} + +\begin{funcdesc}{pwd}{} +Return the pathname of the current directory on the server. +\end{funcdesc} + +\begin{funcdesc}{quit}{} +Send a \samp{QUIT} command to the server and close the connection. +This is the ``polite'' way to close a connection, but it may raise an +exception of the server reponds with an error to the \code{QUIT} +command. +\end{funcdesc} + +\begin{funcdesc}{close}{} +Close the connection unilaterally. This should not be applied to an +already closed connection (e.g.\ after a successful call to +\code{quit()}. +\end{funcdesc} diff --git a/Doc/lib/libgopherlib.tex b/Doc/lib/libgopherlib.tex index eb50fdd..e94e1f9 100644 --- a/Doc/lib/libgopherlib.tex +++ b/Doc/lib/libgopherlib.tex @@ -3,4 +3,28 @@ \renewcommand{\indexsubitem}{(in module gopherlib)} -To be provided. +This module provides a minimal implementation of client side of the +the Gopher protocol. It is used by the module \code{urllib} to handle +URLs that use the Gopher protocol. + +The module defines the following functions: + +\begin{funcdesc}{send_selector}{selector\, host\optional{\, port}} +Send a \var{selector} string to the gopher server at \var{host} and +\var{port} (default 70). Return an open file object from which the +returned document can be read. +\end{funcdesc} + +\begin{funcdesc}{send_query}{selector\, query\, host\optional{\, port}} +Send a \var{selector} string and a \var{query} string to a gopher +server at \var{host} and \var{port} (default 70). Return an open file +object from which the returned document can be read. +\end{funcdesc} + +Note that the data returned by the Gopher server can be of any type, +depending on the first character of the selector string. If the data +is text (first character of the selector is \samp{0}), lines are +terminated by CRLF, and the data is terminated by a line consisting of +a single \samp{.}, and a leading \samp{.} should be stripped from +lines that begin with \samp{..}. Directory listings (first charactger +of the selector is \samp{1}) are transferred using the same protocol. diff --git a/Doc/lib/libmimetools.tex b/Doc/lib/libmimetools.tex index 361e0d0..03f9247 100644 --- a/Doc/lib/libmimetools.tex +++ b/Doc/lib/libmimetools.tex @@ -3,4 +3,94 @@ \renewcommand{\indexsubitem}{(in module mimetools)} -To be provided. +This module defines a subclass of the class \code{rfc822.Message} and +a number of utility functions that are useful for the manipulation for +MIME style multipart or encoded message. + +It defines the following items: + +\begin{funcdesc}{Message}{fp} +Return a new instance of the \code{mimetools.Message} class. This is +a subclass of the \code{rfc822.Message} class, with some additional +methods (see below). +\end{funcdesc} + +\begin{funcdesc}{choose_boundary}{} +Return a unique string that has a high likelihood of being usable as a +part boundary. The string has the form +\code{"\var{hostipaddr}.\var{uid}.\var{pid}.\var{timestamp}.\var{random}"}. +\end{funcdesc} + +\begin{funcdesc}{decode}{input\, output\, encoding} +Read data encoded using the allowed MIME \var{encoding} from open file +object \var{input} and write the decoded data to open file object +\var{output}. Valid values for \var{encoding} include +\code{"base64"}, \code{"quoted-printable"} and \code{"uuencode"}. +\end{funcdesc} + +\begin{funcdesc}{encode}{input\, output\, encoding} +Read data from open file object \var{input} and write it encoded using +the allowed MIME \var{encoding} to open file object \var{output}. +Valid values for \var{encoding} are the same as for \code{decode()}. +\end{funcdesc} + +\begin{funcdesc}{copyliteral}{input\, output} +Read lines until EOF from open file \var{input} and write them to open +file \var{output}. +\end{funcdesc} + +\begin{funcdesc}{copybinary}{input\, output} +Read blocks until EOF from open file \var{input} and write them to open +file \var{output}. The block size is currently fixed at 8192. +\end{funcdesc} + + +\subsection{Additional Methods of \sectcode{Message} objects} +\nodename{mimetools.Message Methods} + +The \code{mimetools.Message} class defines the following methods in +addition to the \code{rfc822.Message} class: + +\renewcommand{\indexsubitem}{(mimetool.Message method)} + +\begin{funcdesc}{getplist}{} +Return the parameter list of the \code{Content-type} header. This is +a list if strings. For parameters of the form +\samp{\var{key}=\var{value}}, \var{key} is converted to lower case but +\var{value} is not. For example, if the message contains the header +\samp{Content-type: text/html; spam=1; Spam=2; Spam} then +\code{getplist()} will return the Python list \code{['spam=1', +'spam=2', 'Spam']}. +\end{funcdesc} + +\begin{funcdesc}{getparam}{name} +Return the \var{value} of the first parameter (as returned by +\code{getplist()} of the form \samp{\var{name}=\var{value}} for the +given \var{name}. If \var{value} is surrounded by quotes of the form +\var{<...>} or \var{"..."}, these are removed. +\end{funcdesc} + +\begin{funcdesc}{getencoding}{} +Return the encoding specified in the \samp{Content-transfer-encoding} +message header. If no such header exists, return \code{"7bit"}. The +encoding is converted to lower case. +\end{funcdesc} + +\begin{funcdesc}{gettype}{} +Return the message type (of the form \samp{\var{type}/var{subtype}}) +as specified in the \samp{Content-type} header. If no such header +exists, return \code{"text/plain"}. The type is converted to lower +case. +\end{funcdesc} + +\begin{funcdesc}{getmaintype}{} +Return the main type as specified in the \samp{Content-type} header. +If no such header exists, return \code{"text"}. The main type is +converted to lower case. +\end{funcdesc} + +\begin{funcdesc}{getsubtype}{} +Return the subtype as specified in the \samp{Content-type} header. If +no such header exists, return \code{"plain"}. The subtype is +converted to lower case. +\end{funcdesc} diff --git a/Doc/lib/libnntplib.tex b/Doc/lib/libnntplib.tex index b1a891d..e5ee97d 100644 --- a/Doc/lib/libnntplib.tex +++ b/Doc/lib/libnntplib.tex @@ -3,4 +3,50 @@ \renewcommand{\indexsubitem}{(in module nntplib)} -To be provided. +This module defines the class \code{NNTP} which implements the client +side of the NNTP protocol. It can be used to implement a news reader +or poster, or automated news processors. For more information on NNTP +(Network News Transfer Protocol), see Internet RFC 977. + +Due to time constraints, the documentation for this module could not +be completed for this release of the Python documentation. Here are +two small examples of how it can be used. + +To list some statistics about a newsgroup and print the subjects of +the last 10 articles: + +\begin{verbatim} +>>> s = NNTP('news.cwi.nl') +>>> resp, count, first, last, name = s.group('comp.lang.python') +>>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last +Group comp.lang.python has 59 articles, range 3742 to 3803 +>>> resp, subs = s.xhdr('subject', first + '-' + last) +>>> for id, sub in subs[-10:]: print id, sub +... +3792 Re: Removing elements from a list while iterating... +3793 Re: Who likes Info files? +3794 Emacs and doc strings +3795 a few questions about the Mac implementation +3796 Re: executable python scripts +3797 Re: executable python scripts +3798 Re: a few questions about the Mac implementation +3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules +3802 Re: executable python scripts +3803 Re: POSIX wait and SIGCHLD +>>> s.quit() +'205 news.cwi.nl closing connection. Goodbye.' +>>> +\end{verbatim} + +To post an article from a file (this assumes that the article has +valid headers): + +\begin{verbatim} +>>> s = NNTP('news.cwi.nl') +>>> f = open('/tmp/article') +>>> s.post(f) +'240 Article posted successfully.' +>>> s.quit() +'205 news.cwi.nl closing connection. Goodbye.' +>>> +\end{verbatim} diff --git a/Doc/lib/libprofile.tex b/Doc/lib/libprofile.tex index ecf41c3..3cd4296 100644 --- a/Doc/lib/libprofile.tex +++ b/Doc/lib/libprofile.tex @@ -500,7 +500,7 @@ that it relies on the Python interpreter to dispatch \dfn{call}, \dfn{return}, and \dfn{exception} events. Compiled C code does not get interpreted, and hence is ``invisible'' to the profiler. All time spent in C code (including builtin functions) will be charged to the -Python function that was invoked the C code. If the C code calls out +Python function that invoked the C code. If the C code calls out to some native Python code, then those calls will be profiled properly. diff --git a/Doc/libftplib.tex b/Doc/libftplib.tex index f5f7ef3..f78805c 100644 --- a/Doc/libftplib.tex +++ b/Doc/libftplib.tex @@ -3,4 +3,202 @@ \renewcommand{\indexsubitem}{(in module ftplib)} -To be provided. +This module defines the class \code{FTP} and a few related items. The +\code{FTP} class implements the client side of the FTP protocol. You +can use this to write Python programs that perform a variety of +automated FTP jobs, such as mirroring other ftp servers. It is also +used bu the module \code{urllib} to handle URLs that use FTP. For +more information on FTP (File Transfer Protocol), see Internet RFC +959. + +Here's a sample session using the \code{ftplib} module: + +\begin{verbatim} +>>> from ftplib import FTP +>>> ftp = FTP('ftp.cwi.nl') # connect to host, default port +>>> ftp.login() # default user anonymous, passwd user@hostname +>>> ftp.retrlines('LIST') # list directory contents +total 24418 +drwxrwsr-x 5 ftp-usr pdmaint 1536 Mar 20 09:48 . +dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 .. +-rw-r--r-- 1 ftp-usr pdmaint 5305 Mar 20 09:48 INDEX + . + . + . +>>> ftp.quit() +\end{verbatim} + +The module defines the following items: + +\begin{funcdesc}{FTP}{\optional{host\optional{\, user\, passwd\, acct}}} +Return a new instance of the \code{FTP} class. When +\var{host} is given, the method call \code{connect(\var{host})} is +made. When \var{user} is given, additionally the method call +\code{login(\var{user}, \var{passwd}, \var{acct})} is made (where +\var{passwd} and \var{acct} default to the empty string when not given). +\end{funcdesc} + +\begin{datadesc}{all_errors} +The set of all exceptions (as a tuple) that methods of \code{FTP} +instances may raise as a result of problems with the FTP connection +(as opposed to programming errors made by the caller). This set +includes the four exceptions listed below as well as +\code{socket.error} and \code{IOError}. +\end{datadesc} + +\begin{excdesc}{error_reply} +Exception raised when an unexpected reply is received from the server. +\end{excdesc} + +\begin{excdesc}{error_temp} +Exception raised when an error code in the range 400--499 is received. +\end{excdesc} + +\begin{excdesc}{error_perm} +Exception raised when an error code in the range 500--599 is received. +\end{excdesc} + +\begin{excdesc}{error_proto} +Exception raised when a reply is received from the server that does +not begin with a digit in the range 1--5. +\end{excdesc} + +\subsection{FTP Objects} + +FTP instances have the following methods: + +\renewcommand{\indexsubitem}{(FTP object method)} + +\begin{funcdesc}{set_debuglevel}{level} +Set the instance's debugging level. This controls the amount of +debugging output printed. The default, 0, produces no debugging +output. A value of 1 produces a moderate amount of debugging output, +generally a single line per request. A value of 2 or higher produces +the maximum amount of debugging output, logging each line sent and +received on the control connection. +\end{funcdesc} + +\begin{funcdesc}{connect}{host\optional{\, port}} +Connect to the given host and port. The default port number is 21, as +specified by the FTP protocol specification. It is rarely needed to +specify a different port number. This function should be called only +once for each instance; it should not be called at all if a host was +given when the instance was created. All other methods can only be +used after a connection has been made. +\end{funcdesc} + +\begin{funcdesc}{getwelcome}{} +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.) +\end{funcdesc} + +\begin{funcdesc}{login}{\optional{user\optional{\, passwd\optional{\, acct}}}} +Log in as the given \var{user}. The \var{passwd} and \var{acct} +parameters are optional and default to the empty string. If no +\var{user} is specified, it defaults to \samp{anonymous}. If +\var{user} is \code{anonymous}, the default \var{passwd} is +\samp{\var{realuser}@\var{host}} where \var{realuser} is the real user +name (glanced from the \samp{LOGNAME} or \samp{USER} environment +variable) and \var{host} is the hostname as returned by +\code{socket.gethostname()}. This function should be called only +once for each instance, after a connection has been established; it +should not be called at all if a host and user were given when the +instance was created. Most FTP commands are only allowed after the +client has logged in. +\end{funcdesc} + +\begin{funcdesc}{abort}{} +Abort a file transfer that is in progress. Using this does not always +work, but it's worth a try. +\end{funcdesc} + +\begin{funcdesc}{sendcmd}{command} +Send a simple command string to the server and return the response +string. +\end{funcdesc} + +\begin{funcdesc}{voidcmd}{command} +Send a simple command string to the server and handle the response. +Return nothing if a response code in the range 200--299 is received. +Raise an exception otherwise. +\end{funcdesc} + +\begin{funcdesc}{retrbinary}{command\, callback\, maxblocksize} +Retrieve a file in binary transfer mode. \var{command} should be an +appropriate \samp{RETR} command, i.e.\ \code{"RETR \var{filename}"}. +The \var{callback} function is called for each block of data received, +with a single string argument giving the data block. +The \var{maxblocksize} argument specifies the maximum block size +(which may not be the actual size of the data blocks passed to +\var{callback}). +\end{funcdesc} + +\begin{funcdesc}{retrlines}{command\optional{\, callback}} +Retrieve a file or directory listing in \ASCII{} transfer mode. +var{command} should be an appropriate \samp{RETR} command (see +\code{retrbinary()} or a \samp{LIST} command (usually just the string +\code{"LIST"}). The \var{callback} function is called for each line, +with the trailing CRLF stripped. The default \var{callback} prints +the line to \code{sys.stdout}. +\end{funcdesc} + +\begin{funcdesc}{storbinary}{command\, file\, blocksize} +Store a file in binary transfer mode. \var{command} should be an +appropriate \samp{STOR} command, i.e.\ \code{"STOR \var{filename}"}. +\var{file} is an open file object which is read until EOF using its +\code{read()} method in blocks of size \var{blocksize} to provide the +data to be stored. +\end{funcdesc} + +\begin{funcdesc}{storlines}{command\, file} +Store a file in \ASCII{} transfer mode. \var{command} should be an +appropriate \samp{STOR} command (see \code{storbinary()}). Lines are +read until EOF from the open file object \var{file} using its +\code{readline()} method to privide the data to be stored. +\end{funcdesc} + +\begin{funcdesc}{nlst}{argument\optional{\, \ldots}} +Return a list of files as returned by the \samp{NLST} command. The +optional var{argument} is a directory to list (default is the current +server directory). Multiple arguments can be used to pass +non-standard options to the \samp{NLST} command. +\end{funcdesc} + +\begin{funcdesc}{dir}{argument\optional{\, \ldots}} +Return a directory listing as returned by the \samp{LIST} command, as +a list of lines. The optional var{argument} is a directory to list +(default is the current server directory). Multiple arguments can be +used to pass non-standard options to the \samp{LIST} command. If the +last argument is a function, it is used as a \var{callback} function +as for \code{retrlines()}. +\end{funcdesc} + +\begin{funcdesc}{rename}{fromname\, toname} +Rename file \var{fromname} on the server to \var{toname}. +\end{funcdesc} + +\begin{funcdesc}{cwd}{pathname} +Set the current directory on the server. +\end{funcdesc} + +\begin{funcdesc}{mkd}{pathname} +Create a new directory on the server. +\end{funcdesc} + +\begin{funcdesc}{pwd}{} +Return the pathname of the current directory on the server. +\end{funcdesc} + +\begin{funcdesc}{quit}{} +Send a \samp{QUIT} command to the server and close the connection. +This is the ``polite'' way to close a connection, but it may raise an +exception of the server reponds with an error to the \code{QUIT} +command. +\end{funcdesc} + +\begin{funcdesc}{close}{} +Close the connection unilaterally. This should not be applied to an +already closed connection (e.g.\ after a successful call to +\code{quit()}. +\end{funcdesc} diff --git a/Doc/libgopherlib.tex b/Doc/libgopherlib.tex index eb50fdd..e94e1f9 100644 --- a/Doc/libgopherlib.tex +++ b/Doc/libgopherlib.tex @@ -3,4 +3,28 @@ \renewcommand{\indexsubitem}{(in module gopherlib)} -To be provided. +This module provides a minimal implementation of client side of the +the Gopher protocol. It is used by the module \code{urllib} to handle +URLs that use the Gopher protocol. + +The module defines the following functions: + +\begin{funcdesc}{send_selector}{selector\, host\optional{\, port}} +Send a \var{selector} string to the gopher server at \var{host} and +\var{port} (default 70). Return an open file object from which the +returned document can be read. +\end{funcdesc} + +\begin{funcdesc}{send_query}{selector\, query\, host\optional{\, port}} +Send a \var{selector} string and a \var{query} string to a gopher +server at \var{host} and \var{port} (default 70). Return an open file +object from which the returned document can be read. +\end{funcdesc} + +Note that the data returned by the Gopher server can be of any type, +depending on the first character of the selector string. If the data +is text (first character of the selector is \samp{0}), lines are +terminated by CRLF, and the data is terminated by a line consisting of +a single \samp{.}, and a leading \samp{.} should be stripped from +lines that begin with \samp{..}. Directory listings (first charactger +of the selector is \samp{1}) are transferred using the same protocol. diff --git a/Doc/libmimetools.tex b/Doc/libmimetools.tex index 361e0d0..03f9247 100644 --- a/Doc/libmimetools.tex +++ b/Doc/libmimetools.tex @@ -3,4 +3,94 @@ \renewcommand{\indexsubitem}{(in module mimetools)} -To be provided. +This module defines a subclass of the class \code{rfc822.Message} and +a number of utility functions that are useful for the manipulation for +MIME style multipart or encoded message. + +It defines the following items: + +\begin{funcdesc}{Message}{fp} +Return a new instance of the \code{mimetools.Message} class. This is +a subclass of the \code{rfc822.Message} class, with some additional +methods (see below). +\end{funcdesc} + +\begin{funcdesc}{choose_boundary}{} +Return a unique string that has a high likelihood of being usable as a +part boundary. The string has the form +\code{"\var{hostipaddr}.\var{uid}.\var{pid}.\var{timestamp}.\var{random}"}. +\end{funcdesc} + +\begin{funcdesc}{decode}{input\, output\, encoding} +Read data encoded using the allowed MIME \var{encoding} from open file +object \var{input} and write the decoded data to open file object +\var{output}. Valid values for \var{encoding} include +\code{"base64"}, \code{"quoted-printable"} and \code{"uuencode"}. +\end{funcdesc} + +\begin{funcdesc}{encode}{input\, output\, encoding} +Read data from open file object \var{input} and write it encoded using +the allowed MIME \var{encoding} to open file object \var{output}. +Valid values for \var{encoding} are the same as for \code{decode()}. +\end{funcdesc} + +\begin{funcdesc}{copyliteral}{input\, output} +Read lines until EOF from open file \var{input} and write them to open +file \var{output}. +\end{funcdesc} + +\begin{funcdesc}{copybinary}{input\, output} +Read blocks until EOF from open file \var{input} and write them to open +file \var{output}. The block size is currently fixed at 8192. +\end{funcdesc} + + +\subsection{Additional Methods of \sectcode{Message} objects} +\nodename{mimetools.Message Methods} + +The \code{mimetools.Message} class defines the following methods in +addition to the \code{rfc822.Message} class: + +\renewcommand{\indexsubitem}{(mimetool.Message method)} + +\begin{funcdesc}{getplist}{} +Return the parameter list of the \code{Content-type} header. This is +a list if strings. For parameters of the form +\samp{\var{key}=\var{value}}, \var{key} is converted to lower case but +\var{value} is not. For example, if the message contains the header +\samp{Content-type: text/html; spam=1; Spam=2; Spam} then +\code{getplist()} will return the Python list \code{['spam=1', +'spam=2', 'Spam']}. +\end{funcdesc} + +\begin{funcdesc}{getparam}{name} +Return the \var{value} of the first parameter (as returned by +\code{getplist()} of the form \samp{\var{name}=\var{value}} for the +given \var{name}. If \var{value} is surrounded by quotes of the form +\var{<...>} or \var{"..."}, these are removed. +\end{funcdesc} + +\begin{funcdesc}{getencoding}{} +Return the encoding specified in the \samp{Content-transfer-encoding} +message header. If no such header exists, return \code{"7bit"}. The +encoding is converted to lower case. +\end{funcdesc} + +\begin{funcdesc}{gettype}{} +Return the message type (of the form \samp{\var{type}/var{subtype}}) +as specified in the \samp{Content-type} header. If no such header +exists, return \code{"text/plain"}. The type is converted to lower +case. +\end{funcdesc} + +\begin{funcdesc}{getmaintype}{} +Return the main type as specified in the \samp{Content-type} header. +If no such header exists, return \code{"text"}. The main type is +converted to lower case. +\end{funcdesc} + +\begin{funcdesc}{getsubtype}{} +Return the subtype as specified in the \samp{Content-type} header. If +no such header exists, return \code{"plain"}. The subtype is +converted to lower case. +\end{funcdesc} diff --git a/Doc/libnntplib.tex b/Doc/libnntplib.tex index b1a891d..e5ee97d 100644 --- a/Doc/libnntplib.tex +++ b/Doc/libnntplib.tex @@ -3,4 +3,50 @@ \renewcommand{\indexsubitem}{(in module nntplib)} -To be provided. +This module defines the class \code{NNTP} which implements the client +side of the NNTP protocol. It can be used to implement a news reader +or poster, or automated news processors. For more information on NNTP +(Network News Transfer Protocol), see Internet RFC 977. + +Due to time constraints, the documentation for this module could not +be completed for this release of the Python documentation. Here are +two small examples of how it can be used. + +To list some statistics about a newsgroup and print the subjects of +the last 10 articles: + +\begin{verbatim} +>>> s = NNTP('news.cwi.nl') +>>> resp, count, first, last, name = s.group('comp.lang.python') +>>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last +Group comp.lang.python has 59 articles, range 3742 to 3803 +>>> resp, subs = s.xhdr('subject', first + '-' + last) +>>> for id, sub in subs[-10:]: print id, sub +... +3792 Re: Removing elements from a list while iterating... +3793 Re: Who likes Info files? +3794 Emacs and doc strings +3795 a few questions about the Mac implementation +3796 Re: executable python scripts +3797 Re: executable python scripts +3798 Re: a few questions about the Mac implementation +3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules +3802 Re: executable python scripts +3803 Re: POSIX wait and SIGCHLD +>>> s.quit() +'205 news.cwi.nl closing connection. Goodbye.' +>>> +\end{verbatim} + +To post an article from a file (this assumes that the article has +valid headers): + +\begin{verbatim} +>>> s = NNTP('news.cwi.nl') +>>> f = open('/tmp/article') +>>> s.post(f) +'240 Article posted successfully.' +>>> s.quit() +'205 news.cwi.nl closing connection. Goodbye.' +>>> +\end{verbatim} diff --git a/Doc/libprofile.tex b/Doc/libprofile.tex index ecf41c3..3cd4296 100644 --- a/Doc/libprofile.tex +++ b/Doc/libprofile.tex @@ -500,7 +500,7 @@ that it relies on the Python interpreter to dispatch \dfn{call}, \dfn{return}, and \dfn{exception} events. Compiled C code does not get interpreted, and hence is ``invisible'' to the profiler. All time spent in C code (including builtin functions) will be charged to the -Python function that was invoked the C code. If the C code calls out +Python function that invoked the C code. If the C code calls out to some native Python code, then those calls will be profiled properly. |