From a1a47c6f38b46fe2d75276cff037048ee9acfdc4 Mon Sep 17 00:00:00 2001 From: Rapptz Date: Fri, 8 Jan 2016 14:03:11 -0500 Subject: 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. --- docs/migrating.rst | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) (limited to 'docs') diff --git a/docs/migrating.rst b/docs/migrating.rst index 2cfa2bc6..c47986a2 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 -- cgit v1.2.3