Add Client.latency, AutoShardedClient.latency and latencies.

This should allow an easier way to query the Discord protocol gateway
latency, defined by the difference HEARTBEAT_ACK between and the last
sent HEARTBEAT.

1 files changed, 18 insertions, 0 deletions

diff --git a/discord/shard.py b/discord/shard.py
index 70b99ee6..89463059 100644
--- a/discord/shard.py
+++ b/discord/shard.py
@@ -149,6 +149,24 @@ class AutoShardedClient(Client):
         ws = self.shards[shard_id].ws
         yield from ws.send_as_json(payload)
 
+    @property
+    def latency(self):
+        """float: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.
+
+        This operates similarly to :meth:`.Client.latency` except it uses the average
+        latency of every shard's latency. To get a list of shard latency, check the
+        :attr:`latencies` property.
+        """
+        return sum(latency for _, latency in self.latencies) / len(self.shards)
+
+    @property
+    def latencies(self):
+        """List[Tuple[int, float]]: A list of latencies between a HEARTBEAT and a HEARTBEAT_ACK in seconds.
+
+        This returns a list of tuples with elements ``(shard_id, latency)``.
+        """
+        return [(shard_id, shard.ws.latency) for shard_id, shard in self.shards.items()]
+
     @asyncio.coroutine
     def request_offline_members(self, *guilds):
         """|coro|