Merge branch '1.16' into 1.17

paramiko/client.py

@@ -382,6 +382,12 @@ def connect(
     def close(self):
         """
         Close this SSHClient and its underlying `.Transport`.
+
+        .. warning::
+            Failure to do this may, in some situations, cause your Python
+            interpreter to hang at shutdown (often due to race conditions).
+            It's good practice to `close` your client objects anytime you're
+            done using them, instead of relying on garbage collection.
         """
         if self._transport is None:
             return

sites/www/faq.rst

@@ -24,3 +24,13 @@ However, **closed does not imply locked** - affected users can still post
 comments on such tickets - and **we will always consider actual patch
 submissions for these issues**, provided they can get +1s from similarly
 affected users and are proven to not break existing functionality.
+
+I'm having strange issues with my code hanging at shutdown!
+===========================================================
+
+Make sure you explicitly ``.close()`` your connection objects (usually
+``SSHClient``) if you're having any sort of hang/freeze at shutdown time!
+
+Doing so isn't strictly necessary 100% of the time, but it is almost always the
+right solution if you run into the various corner cases that cause race
+conditions, etc.