Add docstrings and type annotations. Fix references to parent and rea…

…der between ResourceHandle and ResourceContainer.

importlib_resources/abc.py

@@ -87,12 +87,14 @@ def read_text(self, encoding=None):
 
     @abc.abstractmethod
     def is_dir(self):
+        # type: () -> bool
         """
         Return True if self is a dir
         """
 
     @abc.abstractmethod
     def is_file(self):
+        # type: () -> bool
         """
         Return True if self is a file
         """
@@ -121,9 +123,14 @@ def open(self, mode='r', *args, **kwargs):
 
 
 class SimpleReader(ABC):
+    """
+    The minimum, low-level interface required from a resource
+    provider.
+    """
 
     @abc.abstractproperty
     def package(self):
+        # type: () -> str
         """
         The name of the package for which this reader loads resources.
         """
@@ -156,6 +163,11 @@ def name(self):
 
 
 class TraversableResources(ResourceReader):
+    """
+    The required interface for providing traversable
+    resources.
+    """
+
     @abc.abstractmethod
     def files(self):
         """Return a Traversable object for the loaded package."""
@@ -178,8 +190,9 @@ class ResourceHandle(Traversable):
     Handle to a named resource in a ResourceReader.
     """
 
-    def __init__(self, reader, name):
-        self.reader = reader
+    def __init__(self, parent, name):
+        # type: (ResourceContainer, str) -> None
+        self.parent = parent
         self.name = name
 
     def is_file(self):
@@ -189,7 +202,7 @@ def is_dir(self):
         return False
 
     def open(self, mode='r', *args, **kwargs):
-        stream = self.reader.open_binary(self.name)
+        stream = self.parent.reader.open_binary(self.name)
         if 'b' not in mode:
             stream = io.TextIOWrapper(*args, **kwargs)
         return stream
@@ -216,9 +229,9 @@ def is_file(self):
     def iterdir(self):
         files = (
             ResourceHandle(self, name)
-            for name in self.resources
+            for name in self.reader.resources
             )
-        dirs = map(ResourceContainer, self.children())
+        dirs = map(ResourceContainer, self.reader.children())
         return itertools.chain(files, dirs)
 
     def open(self, *args, **kwargs):
@@ -232,5 +245,10 @@ def joinpath(self, name):
 
 
 class TraversableReader(TraversableResources, SimpleReader):
+    """
+    A TraversableResources based on SimpleReader. Resource providers
+    may derive from this class to provide the TraversableResources
+    interface by supplying the SimpleReader interface.
+    """
     def files(self):
         return ResourceContainer(self)