queues: Add a note to Queue.get about difference from stdlib

Tornado's interpretation of the timeout argument differs from the
stdlib's queue.

Fixes #2370

diff --git a/tornado/queues.py b/tornado/queues.py
index d135c3cb0115c200418adbd3673265262d80e7b5..19ff6c66c660402633f1901c5c4a4503136fc433 100644 (file)
--- a/tornado/queues.py
+++ b/tornado/queues.py
@@ -232,6 +232,16 @@ class Queue(Generic[_T]):
         scale as `tornado.ioloop.IOLoop.time`, normally `time.time`), or a
         `datetime.timedelta` object for a deadline relative to the
         current time.
+
+        .. note::
+
+           The ``timeout`` argument of this method differs from that
+           of the standard library's `queue.Queue.get`. That method
+           interprets numeric values as relative timeouts; this one
+           interprets them as absolute deadlines and requires
+           ``timedelta`` objects for relative timeouts (consistent
+           with other timeouts in Tornado).
+
         """
         future = Future()  # type: Future[_T]
         try: