bpo-18558: Clarify glossary entry for "Iterable" (#3732)

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index dba9186d935a6a8bbac3b02ca5abb5867c66a6ab..b947520b96b66512c5dae22602b0692ac3431794 100644 (file)
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -535,7 +535,10 @@ Glossary
       iterables include all sequence types (such as :class:`list`, :class:`str`,
       and :class:`tuple`) and some non-sequence types like :class:`dict`,
       :term:`file objects <file object>`, and objects of any classes you define
-      with an :meth:`__iter__` or :meth:`__getitem__` method.  Iterables can be
+      with an :meth:`__iter__` method or with a :meth:`__getitem__` method
+      that implements :term:`Sequence` semantics.
+
+      Iterables can be
       used in a :keyword:`for` loop and in many other places where a sequence is
       needed (:func:`zip`, :func:`map`, ...).  When an iterable object is passed
       as an argument to the built-in function :func:`iter`, it returns an

diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst
index 58b03b9bd76804226c664328071a0a2312b036fa..60154532094423bdcd61336d78cbbc06c530fa68 100644 (file)
--- a/Doc/library/collections.abc.rst
+++ b/Doc/library/collections.abc.rst
@@ -107,7 +107,12 @@ ABC                        Inherits from          Abstract Methods        Mixin
 .. class:: Iterable
 
    ABC for classes that provide the :meth:`__iter__` method.
-   See also the definition of :term:`iterable`.
+
+   Checking ``isinstance(obj, Iterable)`` detects classes that are registered
+   as :class:`Iterable` or that have an :meth:`__iter__` method, but it does
+   not detect classes that iterate with the :meth:`__getitem__` method.
+   The only reliable way to determine whether an object is :term:`iterable`
+   is to call ``iter(obj)``.
 
 .. class:: Collection