This is /home/pdm/install/Python-2.1/Doc/lib/python-lib.info, produced by makeinfo version 4.0 from lib.texi. April 15, 2001 2.1  File: python-lib.info, Node: urllib2, Next: httplib, Prev: urllib, Up: Internet Protocols and Support extensible library for opening URLs =================================== This module was documented by Jeremy Hylton . This section was written by Moshe Zadka . An extensible library for opening URLs using a variety of protocols The `urllib2' module defines functions and classes which help in opening URLs (mostly HTTP) in a complex world -- basic and digest authentication, redirections and more. The `urllib2' module defines the following functions: `urlopen(url[, data])' Open the url URL, which can either a string or a `Request' object (currently the code checks that it really is a `Request' instance, or an instance of a subclass of `Request'). DATA should be a string, which specifies additional data to send to the server. In HTTP requests, which are the only ones that support DATA, it should be a buffer in the format of `application/x-www-form-urlencoded', for example one returned from `urllib.urlencode()'. This function returns a file-like object with two additional methods: * `geturl()' -- return the URL of the resource retrieved * `info()' -- return the meta-information of the page, as a dictionary-like object Raises `URLError' on errors. `install_opener(opener)' Install a `OpenerDirector' instance as the default opener. The code does not check for a real `OpenerDirector', and any class with the appropriate interface will work. `build_opener([handler, ...])' Return an `OpenerDirector' instance, which chains the handlers in the order given. HANDLERs can be either instances of `BaseHandler', or subclasses of `BaseHandler' (in which case it must be possible to call the constructor without any parameters. Instances of the following classes will be in the front of the HANDLERs, unless the HANDLERs contain them, instances of them or subclasses of them: `ProxyHandler, UnknownHandler, HTTPHandler, HTTPDefaultErrorHandler, HTTPRedirectHandler, FTPHandler, FileHandler' If the Python installation has SSL support (`socket.ssl()' exists), `HTTPSHandler' will also be added. The following exceptions are raised as appropriate: `URLError' The error handlers raise when they run into a problem. It is a subclass of `IOError'. `HTTPError' A subclass of `URLError', it can also function as a non-exceptional file-like return value (the same thing that `urlopen()' returns). This is useful when handling exotic HTTP errors, such as requests for authentication. `GopherError' A subclass of `URLError', this is the error raised by the Gopher handler. The following classes are provided: `Request(url[, data[, headers]])' This class is an abstraction of a URL request. URL should be a string which is a valid URL. For descrtion of DATA see the `add_data()' description. HEADERS should be a dictionary, and will be treated as if `add_header()' was called with each key and value as arguments. `OpenerDirector()' The `OpenerDirector' class opens URLs via `BaseHandler's chained together. It manages the chaining of handlers, and recovery from errors. `BaseHandler()' This is the base class for all registered handlers -- and handles only the simple mechanics of registration. `HTTPDefaultErrorHandler()' A class which defines a default handler for HTTP error responses; all responses are turned into `HTTPError' exceptions. `HTTPRedirectHandler()' A class to handle redirections. `ProxyHandler([proxies])' Cause requests to go through a proxy. If PROXIES is given, it must be a dictionary mapping protocol names to URLs of proxies. The default is to read the list of proxies from the environment variables `PROTOCOL_proxy'. `HTTPPasswordMgr()' Keep a database of `(REALM, URI) -> (USER, PASSWORD)' mappings. `HTTPPasswordMgrWithDefaultRealm()' Keep a database of `(REALM, URI) -> (USER, PASSWORD)' mappings. A realm of `None' is considered a catch-all realm, which is searched if no other realm fits. `AbstractBasicAuthHandler([password_mgr])' This is a mixin class that helps with HTTP authentication, both to the remote host and to a proxy. PASSWORD_MGR should be something that is compatible with `HTTPPasswordMgr' -- supplies the documented interface above. `HTTPBasicAuthHandler([password_mgr])' Handle authentication with the remote host. Valid PASSWORD_MGR, if given, are the same as for `AbstractBasicAuthHandler'. `ProxyBasicAuthHandler([password_mgr])' Handle authentication with the proxy. Valid PASSWORD_MGR, if given, are the same as for `AbstractBasicAuthHandler'. `AbstractDigestAuthHandler([password_mgr])' This is a mixin class, that helps with HTTP authentication, both to the remote host and to a proxy. PASSWORD_MGR should be something that is compatible with `HTTPPasswordMgr' -- supplies the documented interface above. `HTTPDigestAuthHandler([password_mgr])' Handle authentication with the remote host. Valid PASSWORD_MGR, if given, are the same as for `AbstractBasicAuthHandler'. `ProxyDigestAuthHandler([password_mgr])' Handle authentication with the proxy. PASSWORD_MGR, if given, shoudl be the same as for the constructor of `AbstractDigestAuthHandler'. `HTTPHandler()' A class to handle opening of HTTP URLs. `HTTPSHandler()' A class to handle opening of HTTPS URLs. `FileHandler()' Open local files. `FTPHandler()' Open FTP URLs. `CacheFTPHandler()' Open FTP URLs, keeping a cache of open FTP connections to minimize delays. `GopherHandler()' Open gopher URLs. `UnknownHandler()' A catch-all class to handle unknown URLs. * Menu: * Request Objects:: * OpenerDirector Objects:: * BaseHandler Objects:: * HTTPRedirectHandler Objects:: * ProxyHandler Objects:: * HTTPPasswordMgr Objects:: * AbstractBasicAuthHandler Objects:: * HTTPBasicAuthHandler Objects:: * ProxyBasicAuthHandler Objects:: * AbstractDigestAuthHandler Objects:: * HTTPDigestAuthHandler Objects:: * ProxyDigestAuthHandler Objects:: * HTTPHandler Objects:: * HTTPSHandler Objects:: * FileHandler Objects:: * FTPHandler Objects:: * CacheFTPHandler Objects:: * GopherHandler Objects:: * UnknownHandler Objects::  File: python-lib.info, Node: Request Objects, Next: OpenerDirector Objects, Prev: urllib2, Up: urllib2 Request Objects --------------- The following methods describe all of `Request''s public interface, and so all must be overridden in subclasses. `add_data(data)' Set the `Request' data to DATA is ignored by all handlers except HTTP handlers -- and there it should be an `application/x-www-form-encoded' buffer, and will change the request to be `POST' rather then `GET'. `has_data(data)' Return whether the instance has a non-`None' data. `get_data(data)' Return the instance's data. `add_header(key, val)' Add another header to the request. Headers are currently ignored by all handlers except HTTP handlers, where they are added to the list of headers sent to the server. Note that there cannot be more then one header with the same name, and later calls will overwrite previous calls in case the KEY collides. Currently, this is no loss of HTTP functionality, since all headers which have meaning when used more then once have a (header-specific) way of gaining the same functionality using only one header. `get_full_url()' Return the URL given in the constructor. `get_type()' Return the type of the URL -- also known as the scheme. `get_host()' Return the host to which connection will be made. `get_selector()' Return the selector -- the part of the URL that is sent to the server. `set_proxy(host, type)' Make the request by connecting to a proxy server. The HOST and TYPE will replace those of the instance, and the instance's selector will be the original URL given in the constructor.  File: python-lib.info, Node: OpenerDirector Objects, Next: BaseHandler Objects, Prev: Request Objects, Up: urllib2 OpenerDirector Objects ---------------------- `OpenerDirector' instances have the following methods: `add_handler(handler)' HANDLER should be an instance of `BaseHandler'. The following methods are searched, and added to the possible chains. * `PROTOCOL_open()' -- signal that the handler knows how to open PROTOCOL URLs. * `PROTOCOL_error_TYPE()' -- signal that the handler knows how to handle TYPE errors from PROTOCOL. `close()' Explicitly break cycles, and delete all the handlers. Because the `OpenerDirector' needs to know the registered handlers, and a handler needs to know who the `OpenerDirector' who called it is, there is a reference cycles. Even though recent versions of Python have cycle-collection, it is sometimes preferable to explicitly break the cycles. `open(url[, data])' Open the given URL. (which can be a request object or a string), optionally passing the given DATA. Arguments, return values and exceptions raised are the same as those of `urlopen()' (which simply calls the `open()' method on the default installed `OpenerDirector'. `error(proto[, arg[, ...]])' Handle an error in a given protocol. The HTTP protocol is special cased to use the code as the error. This will call the registered error handlers for the given protocol with the given arguments (which are protocol specific). Return values and exceptions raised are the same as those of `urlopen()'.  File: python-lib.info, Node: BaseHandler Objects, Next: HTTPRedirectHandler Objects, Prev: OpenerDirector Objects, Up: urllib2 BaseHandler Objects ------------------- `BaseHandler' objects provide a couple of methods that are directly useful, and others that are meant to be used by derived classes. These are intended for direct use: `add_parent(director)' Add a director as parent. `close()' Remove any parents. The following members and methods should be used only be classes derived from `BaseHandler': `parent' A valid `OpenerDirector', which can be used to open using a different protocol, or handle errors. `default_open(req)' This method is _not_ defined in `BaseHandler', but subclasses should define it if they want to catch all URLs. This method, if exists, will be called by the `parent' `OpenerDirector'. It should return a file-like object as described in the return value of the `open()' of `OpenerDirector' or `None'. It should raise `URLError', unless a truly exceptional thing happens (for example, `MemoryError' should not be mapped to `URLError'. This method will be called before any protocol-specific open method. `PROTOCOL_open(req)' This method is _not_ defined in `BaseHandler', but subclasses should define it if they want to handle URLs with the given protocol. This method, if defined, will be called by the `parent' `OpenerDirector'. Return values should be the same as for `default_open()'. `unknown_open(req)' This method is NOT defined in `BaseHandler', but subclasses should define it if they want to catch all URLs with no specific registerd handler to open it. This method, if exists, will be called by the `parent' `OpenerDirector'. Return values should be the same as for `default_open()'. `http_error_default(req, fp, code, msg, hdrs)' This method is _not_ defined in `BaseHandler', but subclasses should override it if they intend to provide a catch-all for otherwise unhandled HTTP errors. It will be called automatically by the `OpenerDirector' getting the error, and should not normally be called in other circumstances. REQ will be a `Request' object, FP will be a file-like object with the HTTP error body, CODE will be the three-digit code of the error, MSG will be the user-visible explanation of the code and HDRS will be a mapping object with the headers of the error. Return values and exceptions raised should be the same as those of `urlopen()'. `http_error_NNN(req, fp, code, msg, hdrs)' NNN should be a three-digit HTTP error code. This method is also not defined in `BaseHandler', but will be called, if it exists, on an instance of a subclass, when an HTTP error with code NNN occurs. Subclasses should override this method to handle specific HTTP errors. Arguments, return values and exceptions raised should be the same as for `http_error_default()'.  File: python-lib.info, Node: HTTPRedirectHandler Objects, Next: ProxyHandler Objects, Prev: BaseHandler Objects, Up: urllib2 HTTPRedirectHandler Objects --------------------------- *Note:* 303 redirection is not supported by this version of `urllib2'. `http_error_301(req, fp, code, msg, hdrs)' Redirect to the `Location:' URL. This method is called by the parent `OpenerDirector' when getting an HTTP permanent-redirect response. `http_error_302(req, fp, code, msg, hdrs)' The same as `http_error_301()', but called for the temporary-redirect response.  File: python-lib.info, Node: ProxyHandler Objects, Next: HTTPPasswordMgr Objects, Prev: HTTPRedirectHandler Objects, Up: urllib2 ProxyHandler Objects -------------------- `PROTOCOL_open(request)' The `ProxyHandler' will have a method `PROTOCOL_open()' for every PROTOCOL which has a proxy in the PROXIES dictionary given in the constructor. The method will modify requests to go through the proxy, by calling `request.set_proxy()', and call the next handler in the chain to actually execute the protocol.  File: python-lib.info, Node: HTTPPasswordMgr Objects, Next: AbstractBasicAuthHandler Objects, Prev: ProxyHandler Objects, Up: urllib2 HTTPPasswordMgr Objects ----------------------- These methods are available on `HTTPPasswordMgr' and `HTTPPasswordMgrWithDefaultRealm' objects. `add_password(realm, uri, user, passwd)' URI can be either a single URI, or a sequene of URIs. REALM, USER and PASSWD must be strings. This causes `(USER, PASSWD)' to be used as authentication tokens when authentication for REALM and a super-URI of any of the given URIs is given. `find_user_password(realm, authuri)' Get user/password for given realm and URI, if any. This method will return `(None, None)' if there is no matching user/password. For `HTTPPasswordMgrWithDefaultRealm' objects, the realm `None' will be searched if the given REALM has no matching user/password.  File: python-lib.info, Node: AbstractBasicAuthHandler Objects, Next: HTTPBasicAuthHandler Objects, Prev: HTTPPasswordMgr Objects, Up: urllib2 AbstractBasicAuthHandler Objects -------------------------------- `handle_authentication_request(authreq, host, req, headers)' Handle an authentication request by getting user/password pair, and retrying. AUTHREQ should be the name of the header where the information about the realm, HOST is the host to authenticate too, REQ should be the (failed) `Request' object, and HEADERS should be the error headers.  File: python-lib.info, Node: HTTPBasicAuthHandler Objects, Next: ProxyBasicAuthHandler Objects, Prev: AbstractBasicAuthHandler Objects, Up: urllib2 HTTPBasicAuthHandler Objects ---------------------------- `http_error_401(req, fp, code, msg, hdrs)' Retry the request with authentication info, if available.  File: python-lib.info, Node: ProxyBasicAuthHandler Objects, Next: AbstractDigestAuthHandler Objects, Prev: HTTPBasicAuthHandler Objects, Up: urllib2 ProxyBasicAuthHandler Objects ----------------------------- `http_error_407(req, fp, code, msg, hdrs)' Retry the request with authentication info, if available.  File: python-lib.info, Node: AbstractDigestAuthHandler Objects, Next: HTTPDigestAuthHandler Objects, Prev: ProxyBasicAuthHandler Objects, Up: urllib2 AbstractDigestAuthHandler Objects --------------------------------- `handle_authentication_request(authreq, host, req, headers)' AUTHREQ should be the name of the header where the information about the realm, HOST should be the host to authenticate too, REQ should be the (failed) `Request' object, and HEADERS should be the error headers.  File: python-lib.info, Node: HTTPDigestAuthHandler Objects, Next: ProxyDigestAuthHandler Objects, Prev: AbstractDigestAuthHandler Objects, Up: urllib2 HTTPDigestAuthHandler Objects ----------------------------- `http_error_401(req, fp, code, msg, hdrs)' Retry the request with authentication info, if available.  File: python-lib.info, Node: ProxyDigestAuthHandler Objects, Next: HTTPHandler Objects, Prev: HTTPDigestAuthHandler Objects, Up: urllib2 ProxyDigestAuthHandler Objects ------------------------------ `http_error_407(req, fp, code, msg, hdrs)' Retry the request with authentication information, if available.  File: python-lib.info, Node: HTTPHandler Objects, Next: HTTPSHandler Objects, Prev: ProxyDigestAuthHandler Objects, Up: urllib2 HTTPHandler Objects ------------------- `http_open(req)' Send an HTTP request, whcih can be either GET or POST, depending on `REQ.has_data()'.  File: python-lib.info, Node: HTTPSHandler Objects, Next: FileHandler Objects, Prev: HTTPHandler Objects, Up: urllib2 HTTPSHandler Objects -------------------- `https_open(req)' Send an HTTPS request, which can be either GET or POST, depending on `REQ.has_data()'.  File: python-lib.info, Node: FileHandler Objects, Next: FTPHandler Objects, Prev: HTTPSHandler Objects, Up: urllib2 FileHandler Objects ------------------- `file_open(req)' Open the file locally, if there is no host name, or the host name is `'localhost''. Change the protocol to `ftp' otherwise, and retry opening it using `parent'.  File: python-lib.info, Node: FTPHandler Objects, Next: CacheFTPHandler Objects, Prev: FileHandler Objects, Up: urllib2 FTPHandler Objects ------------------ `ftp_open(req)' Open the FTP file indicated by REQ. The login is always done with empty username and password.  File: python-lib.info, Node: CacheFTPHandler Objects, Next: GopherHandler Objects, Prev: FTPHandler Objects, Up: urllib2 CacheFTPHandler Objects ----------------------- `CacheFTPHandler' objects are `FTPHandler' objects with the following additional methods: `setTimeout(t)' Set timeout of connections to T seconds. `setMaxConns(m)' Set maximum number of cached connections to M.  File: python-lib.info, Node: GopherHandler Objects, Next: UnknownHandler Objects, Prev: CacheFTPHandler Objects, Up: urllib2 GopherHandler Objects --------------------- `gopher_open(req)' Open the gopher resource indicated by REQ.  File: python-lib.info, Node: UnknownHandler Objects, Prev: GopherHandler Objects, Up: urllib2 UnknownHandler Objects ---------------------- [UnknownHandler]{unknown_open} `1(2)' Raise a `URLError' exception.  File: python-lib.info, Node: httplib, Next: ftplib, Prev: urllib2, Up: Internet Protocols and Support HTTP protocol client ==================== HTTP protocol client (requires sockets). This module defines a class which implements the client side of the HTTP protocol. It is normally not used directly -- the module `urllib' uses it to handle URLs that use HTTP. The module defines one class, `HTTP': `HTTP([host[, port]])' An `HTTP' instance represents one transaction with an HTTP server. It should be instantiated passing it a host and optional port number. If no port number is passed, the port is extracted from the host string if it has the form `HOST:PORT', else the default HTTP port (80) is used. If no host is passed, no connection is made, and the `connect()' method should be used to connect to a server. For example, the following calls all create instances that connect to the server at the same host and port: >>> h1 = httplib.HTTP('www.cwi.nl') >>> h2 = httplib.HTTP('www.cwi.nl:80') >>> h3 = httplib.HTTP('www.cwi.nl', 80) Once an `HTTP' instance has been connected to an HTTP server, it should be used as follows: 1. 1. Make exactly one call to the `putrequest()' method. 2. 2. Make zero or more calls to the `putheader()' method. 3. 3. Call the `endheaders()' method (this can be omitted if step 4 makes no calls). 4. 4. Optional calls to the `send()' method. 5. 5. Call the `getreply()' method. 6. 6. Call the `getfile()' method and read the data off the file object that it returns. * Menu: * HTTP Objects:: * Examples 3::  File: python-lib.info, Node: HTTP Objects, Next: Examples 3, Prev: httplib, Up: httplib HTTP Objects ------------ `HTTP' instances have the following methods: `set_debuglevel(level)' Set the debugging level (the amount of debugging output printed). The default debug level is `0', meaning no debugging output is printed. `connect(host[, port])' Connect to the server given by HOST and PORT. See the intro for the default port. This should be called directly only if the instance was instantiated without passing a host. `send(data)' Send data to the server. This should be used directly only after the `endheaders()' method has been called and before `getreply()' has been called. `putrequest(request, selector)' This should be the first call after the connection to the server has been made. It sends a line to the server consisting of the REQUEST string, the SELECTOR string, and the HTTP version (`HTTP/1.0'). `putheader(header, argument[, ...])' Send an RFC 822 style header to the server. It sends a line to the server consisting of the header, a colon and a space, and the first argument. If more arguments are given, continuation lines are sent, each consisting of a tab and an argument. `endheaders()' Send a blank line to the server, signalling the end of the headers. `getreply()' Complete the request by shutting down the sending end of the socket, read the reply from the server, and return a triple `(REPLYCODE, MESSAGE, HEADERS)'. Here, REPLYCODE is the integer reply code from the request (e.g., `200' if the request was handled properly); MESSAGE is the message string corresponding to the reply code; and HEADERS is an instance of the class `mimetools.Message' containing the headers received from the server. See the description of the `mimetools' module. `getfile()' Return a file object from which the data returned by the server can be read, using the `read()', `readline()' or `readlines()' methods.  File: python-lib.info, Node: Examples 3, Prev: HTTP Objects, Up: httplib Examples -------- Here is an example session that uses the `GET' method: >>> import httplib >>> h = httplib.HTTP('www.cwi.nl') >>> h.putrequest('GET', '/index.html') >>> h.putheader('Accept', 'text/html') >>> h.putheader('Accept', 'text/plain') >>> h.endheaders() >>> errcode, errmsg, headers = h.getreply() >>> print errcode # Should be 200 >>> f = h.getfile() >>> data = f.read() # Get the raw HTML >>> f.close() Here is an example session that shows how to `POST' requests: >>> import httplib, urllib >>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0}) >>> h = httplib.HTTP("www.musi-cal.com:80") >>> h.putrequest("POST", "/cgi-bin/query") >>> h.putheader("Content-type", "application/x-www-form-urlencoded") >>> h.putheader("Content-length", "%d" % len(params)) >>> h.putheader('Accept', 'text/plain') >>> h.putheader('Host', 'www.musi-cal.com') >>> h.endheaders() >>> h.send(params) >>> reply, msg, hdrs = h.getreply() >>> print reply # should be 200 >>> data = h.getfile().read() # get the raw HTML  File: python-lib.info, Node: ftplib, Next: gopherlib, Prev: httplib, Up: Internet Protocols and Support FTP protocol client =================== FTP protocol client (requires sockets). This module defines the class `FTP' and a few related items. The `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 by the module `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 `ftplib' module: >>> from ftplib import FTP >>> ftp = FTP('ftp.cwi.nl') # connect to host, default port >>> ftp.login() # 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.retrbinary('RETR README', open('README', 'wb').write) '226 Transfer complete.' >>> ftp.quit() The module defines the following items: `FTP([host[, user[, passwd[, acct]]]])' Return a new instance of the `FTP' class. When HOST is given, the method call `connect(HOST)' is made. When USER is given, additionally the method call `login(USER, PASSWD, ACCT)' is made (where PASSWD and ACCT default to the empty string when not given). `all_errors' The set of all exceptions (as a tuple) that methods of `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 `socket.error' and `IOError'. `error_reply' Exception raised when an unexpected reply is received from the server. `error_temp' Exception raised when an error code in the range 400-499 is received. `error_perm' Exception raised when an error code in the range 500-599 is received. `error_proto' Exception raised when a reply is received from the server that does not begin with a digit in the range 1-5. See also: *Note netrc:: Parser for the `.netrc' file format. The file `.netrc' is typically used by FTP clients to load user authentication information before prompting the user. The file `Tools/scripts/ftpmirror.py' in the Python source distribution is a script that can mirror FTP sites, or portions thereof, using the `ftplib' module. It can be used as an extended example that applies this module. * Menu: * FTP Objects::  File: python-lib.info, Node: FTP Objects, Prev: ftplib, Up: ftplib FTP Objects ----------- Several methods are available in two flavors: one for handling text files and another for binary files. These are named for the command which is used followed by `lines' for the text version or `binary' for the binary version. `FTP' instances have the following methods: `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. `connect(host[, 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. `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.) `login([user[, passwd[, acct]]])' Log in as the given USER. The PASSWD and ACCT parameters are optional and default to the empty string. If no USER is specified, it defaults to `'anonymous''. If USER is `'anonymous'', the default PASSWD is `REALUSER@HOST' where REALUSER is the real user name (glanced from the `LOGNAME' or `USER' environment variable) and HOST is the hostname as returned by `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. `abort()' Abort a file transfer that is in progress. Using this does not always work, but it's worth a try. `sendcmd(command)' Send a simple command string to the server and return the response string. `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. `retrbinary(command, callback[, maxblocksize[, rest]])' Retrieve a file in binary transfer mode. COMMAND should be an appropriate `RETR' command, i.e. `'RETR FILENAME''. The CALLBACK function is called for each block of data received, with a single string argument giving the data block. The optional MAXBLOCKSIZE argument specifies the maximum chunk size to read on the low-level socket object created to do the actual transfer (which will also be the largest size of the data blocks passed to CALLBACK). A reasonable default is chosen. REST means the same thing as in the `transfercmd()' method. `retrlines(command[, callback])' Retrieve a file or directory listing in ASCII transfer mode. COMMAND should be an appropriate `RETR' command (see `retrbinary()' or a `LIST' command (usually just the string `'LIST''). The CALLBACK function is called for each line, with the trailing CRLF stripped. The default CALLBACK prints the line to `sys.stdout'. `set_pasv(boolean)' Enable "passive" mode if BOOLEAN is true, other disable passive mode. (In Python 2.0 and before, passive mode was off by default; in Python 2.1 and later, it is on by default.) `storbinary(command, file[, blocksize])' Store a file in binary transfer mode. COMMAND should be an appropriate `STOR' command, i.e. `"STOR FILENAME"'. FILE is an open file object which is read until `EOF' using its `read()' method in blocks of size BLOCKSIZE to provide the data to be stored. The BLOCKSIZE argument defaults to 8192. _Changed in Python version 2.1_ `storlines(command, file)' Store a file in ASCII transfer mode. COMMAND should be an appropriate `STOR' command (see `storbinary()'). Lines are read until `EOF' from the open file object FILE using its `readline()' method to provide the data to be stored. `transfercmd(cmd[, rest])' Initiate a transfer over the data connection. If the transfer is active, send a `PORT' command and the transfer command specified by CMD, and accept the connection. If the server is passive, send a `PASV' command, connect to it, and start the transfer command. Either way, return the socket for the connection. If optional REST is given, a `REST' command is sent to the server, passing REST as an argument. REST is usually a byte offset into the requested file, telling the server to restart sending the file's bytes at the requested offset, skipping over the initial bytes. Note however that RFC 959 requires only that REST be a string containing characters in the printable range from ASCII code 33 to ASCII code 126. The `transfercmd()' method, therefore, converts REST to a string, but no check is performed on the string's contents. If the server does not recognize the `REST' command, an `error_reply' exception will be raised. If this happens, simply call `transfercmd()' without a REST argument. `ntransfercmd(cmd[, rest])' Like `transfercmd()', but returns a tuple of the data connection and the expected size of the data. If the expected size could not be computed, `None' will be returned as the expected size. CMD and REST means the same thing as in `transfercmd()'. `nlst(argument[, ...])' Return a list of files as returned by the `NLST' command. The optional ARGUMENT is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to the `NLST' command. `dir(argument[, ...])' Produce a directory listing as returned by the `LIST' command, printing it to standard output. The optional ARGUMENT is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to the `LIST' command. If the last argument is a function, it is used as a CALLBACK function as for `retrlines()'; the default prints to `sys.stdout'. This method returns `None'. `rename(fromname, toname)' Rename file FROMNAME on the server to TONAME. `delete(filename)' Remove the file named FILENAME from the server. If successful, returns the text of the response, otherwise raises `error_perm' on permission errors or `error_reply' on other errors. `cwd(pathname)' Set the current directory on the server. `mkd(pathname)' Create a new directory on the server. `pwd()' Return the pathname of the current directory on the server. `rmd(dirname)' Remove the directory named DIRNAME on the server. `size(filename)' Request the size of the file named FILENAME on the server. On success, the size of the file is returned as an integer, otherwise `None' is returned. Note that the `SIZE' command is not standardized, but is supported by many common server implementations. `quit()' Send a `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 `QUIT' command. This implies a call to the `close()' method which renders the `FTP' instance useless for subsequent calls (see below). `close()' Close the connection unilaterally. This should not be applied to an already closed connection (e.g. after a successful call to `quit()'. After this call the `FTP' instance should not be used any more (i.e., after a call to `close()' or `quit()' you cannot reopen the connection by issuing another `login()' method).  File: python-lib.info, Node: gopherlib, Next: poplib, Prev: ftplib, Up: Internet Protocols and Support Gopher protocol client ====================== Gopher protocol client (requires sockets). This module provides a minimal implementation of client side of the the Gopher protocol. It is used by the module `urllib' to handle URLs that use the Gopher protocol. The module defines the following functions: `send_selector(selector, host[, port])' Send a SELECTOR string to the gopher server at HOST and PORT (default `70'). Returns an open file object from which the returned document can be read. `send_query(selector, query, host[, port])' Send a SELECTOR string and a QUERY string to a gopher server at HOST and PORT (default `70'). Returns an open file object from which the returned document can be read. 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 `0'), lines are terminated by CRLF, and the data is terminated by a line consisting of a single `.', and a leading `.' should be stripped from lines that begin with `..'. Directory listings (first character of the selector is `1') are transferred using the same protocol.  File: python-lib.info, Node: poplib, Next: imaplib, Prev: gopherlib, Up: Internet Protocols and Support POP3 protocol client ==================== POP3 protocol client (requires sockets). This module defines a class, `POP3', which encapsulates a connection to an POP3 server and implements protocol as defined in RFC 1725. The `POP3' class supports both the minimal and optional command sets. Note that POP3, though widely supported, is obsolescent. The implementation quality of POP3 servers varies widely, and too many are quite poor. If your mailserver supports IMAP, you would be better off using the `IMAP' class, as IMAP servers tend to be better implemented. A single class is provided by the `poplib' module: `POP3(host[, port])' This class implements the actual POP3 protocol. The connection is created when the instance is initialized. If PORT is omitted, the standard POP3 port (110) is used. One exception is defined as an attribute of the `poplib' module: `error_proto' Exception raised on any errors. The reason for the exception is passed to the constructor as a string. * Menu: * POP3 Objects:: * POP3 Example::  File: python-lib.info, Node: POP3 Objects, Next: POP3 Example, Prev: poplib, Up: poplib POP3 Objects ------------ All POP3 commands are represented by methods of the same name, in lower-case; most return the response text sent by the server. An `POP3' instance has the following methods: `getwelcome()' Returns the greeting string sent by the POP3 server. `user(username)' Send user command, response should indicate that a password is required. `pass_(password)' Send password, response includes message count and mailbox size. Note: the mailbox on the server is locked until `quit()' is called. `apop(user, secret)' Use the more secure APOP authentication to log into the POP3 server. `rpop(user)' Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server. `stat()' Get mailbox status. The result is a tuple of 2 integers: `(MESSAGE COUNT, MAILBOX SIZE)'. `list([which])' Request message list, result is in the form `(RESPONSE, ['mesg_num octets', ...])'. If WHICH is set, it is the message to list. `retr(which)' Retrieve whole message number WHICH, and set its seen flag. Result is in form `(RESPONSE, ['line', ...], OCTETS)'. `dele(which)' Flag message number WHICH for deletion. On most servers deletions are not actually performed until QUIT (the major exception is Eudora QPOP, which deliberately violates the RFCs by doing pending deletes on any disconnect). `rset()' Remove any deletion marks for the mailbox. `noop()' Do nothing. Might be used as a keep-alive. `quit()' Signoff: commit changes, unlock mailbox, drop connection. `top(which, howmuch)' Retrieves the message header plus HOWMUCH lines of the message after the header of message number WHICH. Result is in form `(RESPONSE, ['line', ...], OCTETS)'. The POP3 TOP command this method uses, unlike the RETR command, doesn't set the message's seen flag; unfortunately, TOP is poorly specified in the RFCs and is frequently broken in off-brand servers. Test this method by hand against the POP3 servers you will use before trusting it. `uidl([which])' Return message digest (unique id) list. If WHICH is specified, result contains the unique id for that message in the form `'RESPONSE MESGNUM UID', otherwise result is list `(RESPONSE, ['mesgnum uid', ...], OCTETS)'. See also: The standard Python IMAP module. `http://www.tuxedo.org/~esr/fetchail/fetchmail-FAQ.html'{ The FAQ for the fetchmail POP/IMAP client collects information on POP3 server variations and RFC noncompliance that may be useful if you need to write an application based on poplib.}  File: python-lib.info, Node: POP3 Example, Prev: POP3 Objects, Up: poplib POP3 Example ------------ Here is a minimal example (without error checking) that opens a mailbox and retrieves and prints all messages: import getpass, poplib M = poplib.POP3('localhost') M.user(getpass.getuser()) M.pass_(getpass.getpass()) numMessages = len(M.list()[1]) for i in range(numMessages): for j in M.retr(i+1)[1]: print j At the end of the module, there is a test section that contains a more extensive example of usage.  File: python-lib.info, Node: imaplib, Next: nntplib, Prev: poplib, Up: Internet Protocols and Support IMAP4 protocol client ===================== IMAP4 protocol client (requires sockets). This module was documented by Piers Lauder . This section was written by Piers Lauder . This module defines a class, `IMAP4', which encapsulates a connection to an IMAP4 server and implements a large subset of the IMAP4rev1 client protocol as defined in RFC 2060. It is backward compatible with IMAP4 (RFC 1730) servers, but note that the `STATUS' command is not supported in IMAP4. A single class is provided by the `imaplib' module: `IMAP4([host[, port]])' This class implements the actual IMAP4 protocol. The connection is created and protocol version (IMAP4 or IMAP4rev1) is determined when the instance is initialized. If HOST is not specified, `''' (the local host) is used. If PORT is omitted, the standard IMAP4 port (143) is used. Two exceptions are defined as attributes of the `IMAP4' class: `IMAP4.error' Exception raised on any errors. The reason for the exception is passed to the constructor as a string. `IMAP4.abort' IMAP4 server errors cause this exception to be raised. This is a sub-class of `IMAP4.error'. Note that closing the instance and instantiating a new one will usually allow recovery from this exception. `IMAP4.readonly' This exception is raised when a writable mailbox has its status changed by the server. This is a sub-class of `IMAP4.error'. Some other client now has write permission, and the mailbox will need to be re-opened to re-obtain write permission. The following utility functions are defined: `Internaldate2tuple(datestr)' Converts an IMAP4 INTERNALDATE string to Coordinated Universal Time. Returns a `time' module tuple. `Int2AP(num)' Converts an integer into a string representation using characters from the set [`A' .. `P']. `ParseFlags(flagstr)' Converts an IMAP4 `FLAGS' response to a tuple of individual flags. `Time2Internaldate(date_time)' Converts a `time' module tuple to an IMAP4 `INTERNALDATE' representation. Returns a string in the form: `"DD-Mmm-YYYY HH:MM:SS +HHMM"' (including double-quotes). Note that IMAP4 message numbers change as the mailbox changes; in particular, after an `EXPUNGE' command performs deletions the remaining messages are renumbered. So it is highly advisable to use UIDs instead, with the UID command. At the end of the module, there is a test section that contains a more extensive example of usage. See also: Documents describing the protocol, and sources and binaries for servers implementing it, can all be found at the University of Washington's _IMAP Information Center_ (). * Menu: * IMAP4 Objects:: * IMAP4 Example::  File: python-lib.info, Node: IMAP4 Objects, Next: IMAP4 Example, Prev: imaplib, Up: imaplib IMAP4 Objects ------------- All IMAP4rev1 commands are represented by methods of the same name, either upper-case or lower-case. All arguments to commands are converted to strings, except for `AUTHENTICATE', and the last argument to `APPEND' which is passed as an IMAP4 literal. If necessary (the string contains IMAP4 protocol-sensitive characters and isn't enclosed with either parentheses or double quotes) each string is quoted. However, the PASSWORD argument to the `LOGIN' command is always quoted. If you want to avoid having an argument string quoted (eg: the FLAGS argument to `STORE') then enclose the string in parentheses (eg: `r'(\Deleted)''). Each command returns a tuple: `(TYPE, [DATA, ...])' where TYPE is usually `'OK'' or `'NO'', and DATA is either the text from the command response, or mandated results from the command. An `IMAP4' instance has the following methods: `append(mailbox, flags, date_time, message)' Append message to named mailbox. `authenticate(func)' Authenticate command -- requires response processing. This is currently unimplemented, and raises an exception. `check()' Checkpoint mailbox on server. `close()' Close currently selected mailbox. Deleted messages are removed from writable mailbox. This is the recommended command before `LOGOUT'. `copy(message_set, new_mailbox)' Copy MESSAGE_SET messages onto end of NEW_MAILBOX. `create(mailbox)' Create new mailbox named MAILBOX. `delete(mailbox)' Delete old mailbox named MAILBOX. `expunge()' Permanently remove deleted items from selected mailbox. Generates an `EXPUNGE' response for each deleted message. Returned data contains a list of `EXPUNGE' message numbers in order received. `fetch(message_set, message_parts)' Fetch (parts of) messages. MESSAGE_PARTS should be a string of message part names enclosed within parentheses, eg: `"(UID BODY[TEXT])"'. Returned data are tuples of message part envelope and data. `list([directory[, pattern]])' List mailbox names in DIRECTORY matching PATTERN. DIRECTORY defaults to the top-level mail folder, and PATTERN defaults to match anything. Returned data contains a list of `LIST' responses. `login(user, password)' Identify the client using a plaintext password. The PASSWORD will be quoted. `logout()' Shutdown connection to server. Returns server `BYE' response. `lsub([directory[, pattern]])' List subscribed mailbox names in directory matching pattern. DIRECTORY defaults to the top level directory and PATTERN defaults to match any mailbox. Returned data are tuples of message part envelope and data. `noop()' Send `NOOP' to server. `open(host, port)' Opens socket to PORT at HOST. You may override this method. `partial(message_num, message_part, start, length)' Fetch truncated part of a message. Returned data is a tuple of message part envelope and data. `recent()' Prompt server for an update. Returned data is `None' if no new messages, else value of `RECENT' response. `rename(oldmailbox, newmailbox)' Rename mailbox named OLDMAILBOX to NEWMAILBOX. `response(code)' Return data for response CODE if received, or `None'. Returns the given code, instead of the usual type. `search(charset, criterium[, ...])' Search mailbox for matching messages. Returned data contains a space separated list of matching message numbers. CHARSET may be `None', in which case no `CHARSET' will be specified in the request to the server. The IMAP protocol requires that at least one criterium be specified; an exception will be raised when the server returns an error. Example: # M is a connected IMAP4 instance... msgnums = M.search(None, 'FROM', '"LDJ"') # or: msgnums = M.search(None, '(FROM "LDJ")') `select([mailbox[, readonly]])' Select a mailbox. Returned data is the count of messages in MAILBOX (`EXISTS' response). The default MAILBOX is `'INBOX''. If the READONLY flag is set, modifications to the mailbox are not allowed. `socket()' Returns socket instance used to connect to server. `status(mailbox, names)' Request named status conditions for MAILBOX. `store(message_set, command, flag_list)' Alters flag dispositions for messages in mailbox. `subscribe(mailbox)' Subscribe to new mailbox. `uid(command, arg[, ...])' Execute command args with messages identified by UID, rather than message number. Returns response appropriate to command. At least one argument must be supplied; if none are provided, the server will return an error and an exception will be raised. `unsubscribe(mailbox)' Unsubscribe from old mailbox. `xatom(name[, arg[, ...]])' Allow simple extension commands notified by server in `CAPABILITY' response. The following attributes are defined on instances of `IMAP4': `PROTOCOL_VERSION' The most recent supported protocol in the `CAPABILITY' response from the server. `debug' Integer value to control debugging output. The initialize value is taken from the module variable `Debug'. Values greater than three trace each command.