Expand SFTPFile.prefetch docstring re #562, re #677

1 files changed, 13 insertions, 1 deletions

diff --git a/paramiko/sftp_file.py b/paramiko/sftp_file.py
index a29a7d79..8d147342 100644
--- a/paramiko/sftp_file.py
+++ b/paramiko/sftp_file.py
@@ -391,9 +391,21 @@ class SFTPFile (BufferedFile):
         data may be read in a random order (using `.seek`); chunks of the
         buffer that haven't been read will continue to be buffered.
 
+        :param int file_size:
+            When this is ``None`` (the default), this method calls `stat` to
+            determine the remote file size. In some situations, doing so can
+            cause exceptions or hangs (see `#562
+            <https://github.com/paramiko/paramiko/pull/562>`_); as a
+            workaround, one may call `stat` explicitly and pass its value in
+            via this parameter.
+
         .. versionadded:: 1.5.1
+        .. versionchanged:: 1.16.0
+            The ``file_size`` parameter was added (with no default value).
+        .. versionchanged:: 1.16.1
+            The ``file_size`` parameter was made optional for backwards
+            compatibility.
         """
-
         if file_size is None:
             file_size = self.stat().st_size;