Docs improvements

Details:

* Docs: Documented exceptions that can be raised, in all methods.

* Docs: Switched links to items in the Python documentation to go to Python 3
  instead of Python 2.

* Docs: Clarified that NocaseList supports the functionality of the built-in
  list class as of Python 3.8, including all methods that have been added since
  Python 2.7, on all Python versions.

Signed-off-by: Andreas Maier <andreas.r.maier@gmx.de>

docs/changes.rst

@@ -29,6 +29,15 @@ Released: not yet
 
 * Docs: Switched Sphinx theme to sphinx_rtd_theme (See issue #19)
 
+* Docs: Documented exceptions that can be raised, in all methods.
+
+* Docs: Switched links to items in the Python documentation to go to Python 3
+  instead of Python 2.
+
+* Docs: Clarified that NocaseList supports the functionality of the built-in
+  list class as of Python 3.8, including all methods that have been added since
+  Python 2.7, on all Python versions.
+
 **Cleanup:**
 
 **Known issues:**

docs/conf.py

@@ -476,7 +476,7 @@ def get_version(version_file):
 #       to datatypes of function parameters can be controlled.
 #
 intersphinx_mapping = {
-  'py': ('https://docs.python.org/2/', None), # agnostic to Python version
+  'py': ('https://docs.python.org/3/', None), # agnostic to Python version
   'py2': ('https://docs.python.org/2', None), # specific to Python 2
   'py3': ('https://docs.python.org/3', None), # specific to Python 3
 }

docs/reference.rst

@@ -4,16 +4,19 @@
 API Reference
 =============
 
+
 .. _`Class NocaseList`:
 
 Class NocaseList
 ----------------
 
-.. automodule:: nocaselist._nocaselist
-
 .. autoclass:: nocaselist.NocaseList
    :members:
-   :special-members:
+   :special-members: __getitem__
+
+   .. # Note, we want to exclude __init__. Specifying one other special member
+   .. # ba name causes __init__ to be excluded and all other special methods to
+   .. # be included.
 
    .. rubric:: Methods
 

nocaselist/_nocaselist.py

@@ -1,5 +1,5 @@
 """
-The only class exposed by this package is :class:`nocaselist.NocaseList`.
+This module provides class NocaseList.
 """
 
 from __future__ import print_function, absolute_import
@@ -20,7 +20,7 @@ def _lc_list(lst):
 class NocaseList(list):
     # pylint: disable=line-too-long
     """
-    A case-insensitive, case-preserving, list.
+    A case-insensitive and case-preserving list.
 
     The list is case-insensitive: Whenever items of the list are looked up by
     value or item values are compared, that is done case-insensitively. The
@@ -40,14 +40,18 @@ class NocaseList(list):
     The implementation maintains a second list with the lower-cased items of
     the inherited list, and ensures that both lists are in sync.
 
-    The ``NocaseList`` class supports all behaviors of the built-in
-    :class:`py:list` class, so its documentation applies completely:
-
-    * `built-in list class documentation <https://docs.python.org/3/library/stdtypes.html#list>`_
+    The :class:`NocaseList` class supports the functionality of the built-in
+    `list class of Python 3.8`_, so its documentation applies completely.
+    Methods that have been added to the built-in :class:`py3:list`
+    class between Python 2.7 and Python 3.8 (i.e. :meth:`~NocaseList.clear` and
+    :meth:`~NocaseList.copy`) are supported by the :class:`NocaseList` class on
+    all Python versions.
 
     The following documentation is provided only for explicit documentation of
     the case-insensitive behavior, and to indicate which methods have been
     implemented for maintaining the second lower-cased list.
+
+    .. _list class of Python 3.8: https://docs.python.org/3.8/library/stdtypes.html#list
     """  # noqa E401
     # pylint: enable=line-too-long
 
@@ -83,6 +87,9 @@ def __setitem__(self, index, value):
         Update the value of the item at an existing index in the list.
 
         Invoked using ``ncl[index] = value``.
+
+        Raises:
+          AttributeError: The value does not have a ``lower()`` method.
         """
         super(NocaseList, self).__setitem__(index, value)
         self._lc_list[index] = value.lower()
@@ -102,6 +109,9 @@ def __contains__(self, value):
         item with the value, by looking it up case-insensitively.
 
         Invoked using ``value in ncl``.
+
+        Raises:
+          AttributeError: The value does not have a ``lower()`` method.
         """
         return value.lower() in self._lc_list
 
@@ -182,6 +192,10 @@ def __eq__(self, other):
         iterable. In all cases, the comparison takes place case-insensitively.
 
         Invoked using e.g. ``ncl == other``.
+
+        Raises:
+          AttributeError: A value in the other list does not have a ``lower()``
+            method.
         """
         if isinstance(other, NocaseList):
             other = other._lc_list  # pylint: disable=protected-access
@@ -198,6 +212,10 @@ def __ne__(self, other):
         iterable. In all cases, the comparison takes place case-insensitively.
 
         Invoked using e.g. ``ncl != other``.
+
+        Raises:
+          AttributeError: A value in the other list does not have a ``lower()``
+            method.
         """
         if isinstance(other, NocaseList):
             other = other._lc_list  # pylint: disable=protected-access
@@ -214,6 +232,10 @@ def __gt__(self, other):
         iterable. In all cases, the comparison takes place case-insensitively.
 
         Invoked using e.g. ``ncl > other``.
+
+        Raises:
+          AttributeError: A value in the other list does not have a ``lower()``
+            method.
         """
         if isinstance(other, NocaseList):
             other = other._lc_list  # pylint: disable=protected-access
@@ -230,6 +252,10 @@ def __lt__(self, other):
         iterable. In all cases, the comparison takes place case-insensitively.
 
         Invoked using e.g. ``ncl < other``.
+
+        Raises:
+          AttributeError: A value in the other list does not have a ``lower()``
+            method.
         """
         if isinstance(other, NocaseList):
             other = other._lc_list  # pylint: disable=protected-access
@@ -247,6 +273,10 @@ def __ge__(self, other):
         iterable. In all cases, the comparison takes place case-insensitively.
 
         Invoked using e.g. ``ncl >= other``.
+
+        Raises:
+          AttributeError: A value in the other list does not have a ``lower()``
+            method.
         """
         if isinstance(other, NocaseList):
             other = other._lc_list  # pylint: disable=protected-access
@@ -264,6 +294,10 @@ def __le__(self, other):
         iterable. In all cases, the comparison takes place case-insensitively.
 
         Invoked using e.g. ``ncl <= other``.
+
+        Raises:
+          AttributeError: A value in the other list does not have a ``lower()``
+            method.
         """
         if isinstance(other, NocaseList):
             other = other._lc_list  # pylint: disable=protected-access
@@ -275,6 +309,9 @@ def count(self, value):
         """
         Return the number of times the specified value occurs in the list,
         comparing the value and the list items case-insensitively.
+
+        Raises:
+          AttributeError: The value does not have a ``lower()`` method.
         """
         return self._lc_list.count(value.lower())
 
@@ -306,6 +343,7 @@ def index(self, value, start=0, stop=9223372036854775807):
         of the first item after the search range.
 
         Raises:
+          AttributeError: The value does not have a ``lower()`` method.
           ValueError: No such item is found.
         """
         return self._lc_list.index(value.lower(), start, stop)
@@ -314,6 +352,9 @@ def append(self, value):
         """
         Append the specified value as a new item to the end of the list
         (and return None).
+
+        Raises:
+          AttributeError: The value does not have a ``lower()`` method.
         """
         super(NocaseList, self).append(value)
         self._lc_list.append(value.lower())
@@ -322,6 +363,10 @@ def extend(self, iterable):
         """
         Extend the list by the items in the specified iterable
         (and return None).
+
+        Raises:
+          AttributeError: A value in the iterable does not have a ``lower()``
+            method.
         """
         super(NocaseList, self).extend(iterable)
         for value in iterable:
@@ -331,6 +376,9 @@ def insert(self, index, value):
         """
         Insert a new item with specified value before the item at the specified
         index (and return None).
+
+        Raises:
+          AttributeError: The value does not have a ``lower()`` method.
         """
         super(NocaseList, self).insert(index, value)
         self._lc_list.insert(index, value.lower())
@@ -348,6 +396,9 @@ def remove(self, value):
         Remove the first item from the list whose value is equal to the
         specified value (and return None), comparing the value and the list
         items case-insensitively.
+
+        Raises:
+          AttributeError: The value does not have a ``lower()`` method.
         """
         self._lc_list.remove(value.lower())
         super(NocaseList, self).remove(value)
@@ -376,6 +427,9 @@ def sort(self, key=None, reverse=False):
 
         def lower_key(value):
             """Key function used for sorting"""
+            # The function cannot raise AttributeError due to missing lower()
+            # method, because the list items have been verified for that when
+            # adding them to the list.
             if key:
                 return key(value.lower())
             return value.lower()