Changeset 487:e68724ac688d

Timestamp:

2006-02-06 22:39:20 (4 years ago)

Author:

Stefan Schwarzer <sschwarzer@…>

Branch:

default

convert_revision:

svn:778c30c8-61e0-0310-89d4-fe2f97a467b2/trunk@506

Message:

Added an optional parameter `also_files` to `FTPHost.keep_alive`
and documented it in `ftputil.txt`.

Files:

• ftputil.py (modified) (2 diffs)
• ftputil.txt (modified) (3 diffs)

ftputil.py

@@ -103 +103 @@
            'PermanentError', 'ParserError', 'FTPIOError',
            'RootDirError', 'FTPHost']
-__version__ = '2.0.4'
+__version__ = '2.1b'
 
 
@@ -249 +249 @@
         return self.file(path, mode)
 
-    def keep_alive(self):
+    def keep_alive(self, also_files=True):
         """
         Do something without side effects to keep the connection to
         the server. This can be used to prevent broken connections due
         to server timeouts.
+
+        If the parameter `also_files` is a true value, which is the
+        default, propagate the connection refresh to all associated
+        open file-like objects. In multi-threaded applications, you
+        may want to set `also_files` to `False` and call the
+        `keep_alive` method of the file-like objects individually.
         """
         # just prevent loss of the connection, so discard the result
         self.getcwd()
+        # refresh also connections of associated file-like objects
+        if also_files:
+            for host in self._children:
+                host._file.keep_alive()
 
     def close(self):

ftputil.txt

@@ -654 +654 @@
   and use of remote file-like objects.
 
-- ``keep_alive()``
+.. _`FTPHost.keep_alive`:
+
+- ``keep_alive(also_files=True)``
 
   Do something without side effects to hold the connection to the FTP
   server. This should be used to prevent server timeouts after several
   minutes of inactivity.
+
+  Note that not only an ``FTPHost`` object but also *each* of the
+  file-objects made from it has its own connection to the FTP server,
+  so all of the connections must be kept alive. Use the default
+  setting, ``True``, for ``also_files`` to propagate the refresh to
+  all open file-like objects made from this ``FTPHost`` instance.
+
+  However, be careful with the default parameter in multi-threaded
+  applications.
 
 
@@ -711 +722 @@
   server. This should be used to prevent server timeouts after several
   minutes of inactivity.
+
+  Note that not only an ``FTPHost`` object but also *each* of the
+  file-objects made from it has its own connection to the FTP server,
+  so all of the connections must be kept alive. Use the
+  `FTPHost.keep_alive`_ to refresh all connections at once.
 
 
@@ -816 +832 @@
 - Timeouts of individual child sessions currently are not handled.
   This is only a problem if your ``FTPHost`` object or the generated
-  ``FTPFile`` objects are inactive for about ten minutes or longer. A
-  workaround is to keep the respective connections busy, e. g. call
-  ``getcwd`` on ``FTPHost`` objects or ``write("")`` on remote
-  file-like objects.
+  ``FTPFile`` objects are inactive for about ten minutes or longer.
+  As a workaround, you can use the ``keep_alive`` methods of
+  ``FTPHost`` objects and remote file-like objects.
 
 - Until now, I haven't paid attention to thread safety. In principle,