[Python-checkins] r60188 - in python/trunk: Lib/ftplib.py Misc/NEWS

[gregory.p.smith]

Author: gregory.p.smith
Date: Tue Jan 22 01:19:41 2008
New Revision: 60188

Modified:
   python/trunk/Lib/ftplib.py
   python/trunk/Misc/NEWS
Log:
accepts and closes issue #1221598: adds an optional callback to ftplib.FTP
storbinary() and storlines() methods.


Modified: python/trunk/Lib/ftplib.py
==============================================================================
--- python/trunk/Lib/ftplib.py	(original)
+++ python/trunk/Lib/ftplib.py	Tue Jan 22 01:19:41 2008
@@ -32,6 +32,7 @@
 # Changes and improvements suggested by Steve Majewski.
 # Modified by Jack to work on the mac.
 # Modified by Siebren to support docstrings and PASV.
+# Modified by Phil Schwartz to add storbinary and storlines callbacks.
 #
 
 import os
@@ -375,14 +376,18 @@
         return resp
 
     def retrbinary(self, cmd, callback, blocksize=8192, rest=None):
-        """Retrieve data in binary mode.
+        """Retrieve data in binary mode.  A new port is created for you.
 
-        `cmd' is a RETR command.  `callback' is a callback function is
-        called for each block.  No more than `blocksize' number of
-        bytes will be read from the socket.  Optional `rest' is passed
-        to transfercmd().
+        Args:
+          cmd: A RETR command.
+          callback: A single parameter callable to be called on each
+                    block of data read.
+          blocksize: The maximum number of bytes to read from the
+                     socket at one time.  [default: 8192]
+          rest: Passed to transfercmd().  [default: None]
 
-        A new port is created for you.  Return the response code.
+        Returns:
+          The response code.
         """
         self.voidcmd('TYPE I')
         conn = self.transfercmd(cmd, rest)
@@ -395,11 +400,17 @@
         return self.voidresp()
 
     def retrlines(self, cmd, callback = None):
-        '''Retrieve data in line mode.
-        The argument is a RETR or LIST command.
-        The callback function (2nd argument) is called for each line,
-        with trailing CRLF stripped.  This creates a new port for you.
-        print_line() is the default callback.'''
+        """Retrieve data in line mode.  A new port is created for you.
+
+        Args:
+          cmd: A RETR or LIST command.
+          callback: An optional single parameter callable that is called
+                    for each line with the trailing CRLF stripped.
+                    [default: print_line()]
+
+        Returns:
+          The response code.
+        """
         if callback is None: callback = print_line
         resp = self.sendcmd('TYPE A')
         conn = self.transfercmd(cmd)
@@ -418,19 +429,42 @@
         conn.close()
         return self.voidresp()
 
-    def storbinary(self, cmd, fp, blocksize=8192):
-        '''Store a file in binary mode.'''
+    def storbinary(self, cmd, fp, blocksize=8192, callback=None):
+        """Store a file in binary mode.  A new port is created for you.
+
+        Args:
+          cmd: A STOR command.
+          fp: A file-like object with a read(num_bytes) method.
+          blocksize: The maximum data size to read from fp and send over
+                     the connection at once.  [default: 8192]
+          callback: An optional single parameter callable that is called on
+                    on each block of data after it is sent.  [default: None]
+
+        Returns:
+          The response code.
+        """
         self.voidcmd('TYPE I')
         conn = self.transfercmd(cmd)
         while 1:
             buf = fp.read(blocksize)
             if not buf: break
             conn.sendall(buf)
+            if callback: callback(buf)
         conn.close()
         return self.voidresp()
 
-    def storlines(self, cmd, fp):
-        '''Store a file in line mode.'''
+    def storlines(self, cmd, fp, callback=None):
+        """Store a file in line mode.  A new port is created for you.
+
+        Args:
+          cmd: A STOR command.
+          fp: A file-like object with a readline() method.
+          callback: An optional single parameter callable that is called on
+                    on each line after it is sent.  [default: None]
+
+        Returns:
+          The response code.
+        """
         self.voidcmd('TYPE A')
         conn = self.transfercmd(cmd)
         while 1:
@@ -440,6 +474,7 @@
                 if buf[-1] in CRLF: buf = buf[:-1]
                 buf = buf + CRLF
             conn.sendall(buf)
+            if callback: callback(buf)
         conn.close()
         return self.voidresp()
 

Modified: python/trunk/Misc/NEWS
==============================================================================
--- python/trunk/Misc/NEWS	(original)
+++ python/trunk/Misc/NEWS	Tue Jan 22 01:19:41 2008
@@ -374,6 +374,9 @@
 Library
 -------
 
+- #1221598: add optional callbacks to ftplib.FTP's storbinary() and
+  storlines() methods.  (Contributed by Phil Schwartz)
+
 - #1715: include sub-extension modules in pydoc's text output.
 
 - #1836: fix an off-by-one bug in TimedRotatingHandler's rollover