From a1a47c6f38b46fe2d75276cff037048ee9acfdc4 Mon Sep 17 00:00:00 2001
From: Rapptz <Rapptz@gmail.com>
Date: Fri, 8 Jan 2016 14:03:11 -0500
Subject: [PATCH] Document the breaking change with the new dictionary storage
 change.

Since the only things dict views support are iteration we should
advise people who want the old behaviour to change it to a list.
---
 discord/client.py  |  4 ++--
 discord/server.py  |  4 ++--
 docs/migrating.rst | 37 +++++++++++++++++++++++++++++++++++++
 3 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/discord/client.py b/discord/client.py
index 4c06dcbf4..77b714669 100644
--- a/discord/client.py
+++ b/discord/client.py
@@ -88,9 +88,9 @@ class Client:
         Represents the current voice connection. None if you are not connected
         to a voice channel. To connect to voice use :meth:`join_voice_channel`.
         To query the voice connection state use :meth:`is_voice_connected`.
-    servers : list of :class:`Server`
+    servers : iterable of :class:`Server`
         The servers that the connected client is a member of.
-    private_channels : list of :class:`PrivateChannel`
+    private_channels : iterable of :class:`PrivateChannel`
         The private channels that the connected client is participating on.
     messages
         A deque_ of :class:`Message` that the client has received from all
diff --git a/discord/server.py b/discord/server.py
index 66ae3cd63..2d2afe6bc 100644
--- a/discord/server.py
+++ b/discord/server.py
@@ -67,9 +67,9 @@ class Server(Hashable):
     afk_channel : :class:`Channel`
         The channel that denotes the AFK channel. None if it doesn't exist.
     members
-        A list of :class:`Member` that are currently on the server.
+        An iterable of :class:`Member` that are currently on the server.
     channels
-        A list of :class:`Channel` that are currently on the server.
+        An iterable of :class:`Channel` that are currently on the server.
     icon : str
         The server's icon.
     id : str
diff --git a/docs/migrating.rst b/docs/migrating.rst
index 2cfa2bc62..c47986a20 100644
--- a/docs/migrating.rst
+++ b/docs/migrating.rst
@@ -122,6 +122,43 @@ After:
 In order for you to ``yield from`` or ``await`` a coroutine then your function must be decorated
 with ``@asyncio.coroutine`` or ``async def``.
 
+.. _migrating-iterable:
+
+Iterables
+----------
+
+For performance reasons, many of the internal data structures were changed into a dictionary to support faster
+lookup. As a consequence, this meant that some lists that were exposed via the API have changed into iterables
+and not sequences. In short, this means that certain attributes now only support iteration and not any of the
+sequence functions.
+
+The affected attributes are as follows:
+
+- :attr:`Client.servers`
+- :attr:`Client.private_channels`
+- :attr:`Server.channels`
+- :attr:`Server.members`
+
+Some examples of previously valid behaviour that is now invalid
+
+.. code-block:: python
+
+    if client.servers[0].name == "test":
+        # do something
+
+Since they are no longer ``list``\s, they no longer support indexing or any operation other than iterating.
+In order to get the old behaviour you should explicitly cast it to a list.
+
+.. code-block:: python
+
+    servers = list(client.servers)
+    # work with servers
+
+.. warning::
+
+    Due to internal changes of the structure, the order you receive the data in
+    is not in a guaranteed order.
+
 .. _migrating-enums:
 
 Enumerators