Add note about OpenSSH sftp's concurrent limit

2 files changed, 16 insertions, 4 deletions

diff --git a/paramiko/sftp_client.py b/paramiko/sftp_client.py
index a0d38bb9..8ebeb85e 100644
--- a/paramiko/sftp_client.py
+++ b/paramiko/sftp_client.py
@@ -783,7 +783,10 @@ class SFTPClient(BaseSFTP, ClosingContextManager):
         :param int max_concurrent_prefetch_requests:
             The maximum number of concurrent read requests to prefetch.
             When this is ``None`` (the default), do not limit the number of
-            concurrent prefetch requests.
+            concurrent prefetch requests. Note: OpenSSH's sftp internally
+            imposes a limit of 64 concurrent requests, while Paramiko imposes
+            no limit by default; consider setting a limit if a file can be
+            successfully received with sftp but hangs with Paramiko.
         :return: the `number <int>` of bytes written to the opened file object
 
         .. versionadded:: 1.10
@@ -821,7 +824,10 @@ class SFTPClient(BaseSFTP, ClosingContextManager):
         :param int max_concurrent_prefetch_requests:
             The maximum number of concurrent read requests to prefetch.
             When this is ``None`` (the default), do not limit the number of
-            concurrent prefetch requests.
+            concurrent prefetch requests. Note: OpenSSH's sftp internally
+            imposes a limit of 64 concurrent requests, while Paramiko imposes
+            no limit by default; consider setting a limit if a file can be
+            successfully received with sftp but hangs with Paramiko.
 
         .. versionadded:: 1.4
         .. versionchanged:: 1.7.4
diff --git a/paramiko/sftp_file.py b/paramiko/sftp_file.py
index 12861df7..86d9a560 100644
--- a/paramiko/sftp_file.py
+++ b/paramiko/sftp_file.py
@@ -457,7 +457,10 @@ class SFTPFile(BufferedFile):
         :param int max_concurrent_requests:
             The maximum number of concurrent read requests to prefetch.
             When this is ``None`` (the default), do not limit the number of
-            concurrent prefetch requests.
+            concurrent prefetch requests. Note: OpenSSH's sftp internally
+            imposes a limit of 64 concurrent requests, while Paramiko imposes
+            no limit by default; consider setting a limit if a file can be
+            successfully received with sftp but hangs with Paramiko.
 
         .. versionadded:: 1.5.1
         .. versionchanged:: 1.16.0
@@ -492,7 +495,10 @@ class SFTPFile(BufferedFile):
         :param int max_concurrent_prefetch_requests:
             The maximum number of concurrent read requests to prefetch.
             When this is ``None`` (the default), do not limit the number of
-            concurrent prefetch requests.
+            concurrent prefetch requests. Note: OpenSSH's sftp internally
+            imposes a limit of 64 concurrent requests, while Paramiko imposes
+            no limit by default; consider setting a limit if a file can be
+            successfully received with sftp but hangs with Paramiko.
         :return: a list of blocks read, in the same order as in ``chunks``
 
         .. versionadded:: 1.5.4