Add documentation, kwargs for Reader (#2236)

Support additional keyword argument for shapefile readers and add documentation about the `Reader` being an alias to whichever shapefile reading library is available.

lib/cartopy/io/shapereader.py

@@ -123,17 +123,20 @@ def __init__(self, geometry, attributes):
 
 class BasicReader:
     """
-    Provide an interface for accessing the contents of a shapefile.
+    Provide an interface for accessing the contents of a shapefile with the
+    Python Shapefile Library (PyShp). See the PyShp
+    `Readme <https://pypi.org/project/pyshp/>`_ for more information.
 
     The primary methods used on a BasicReader instance are
     :meth:`~cartopy.io.shapereader.BasicReader.records` and
     :meth:`~cartopy.io.shapereader.BasicReader.geometries`.
 
     """
 
-    def __init__(self, filename, bbox=None):
+    def __init__(self, filename, bbox=None, **kwargs):
         # Validate the filename/shapefile
-        self._reader = reader = shapefile.Reader(filename)
+        self._reader = reader = shapefile.Reader(filename, **kwargs)
+        self._bbox = bbox
         if reader.shp is None or reader.shx is None or reader.dbf is None:
             raise ValueError("Incomplete shapefile definition "
                              "in '%s'." % filename)
@@ -158,7 +161,7 @@ def geometries(self):
         :meth:`~Record.geometry` method.
 
         """
-        for shape in self._reader.iterShapes():
+        for shape in self._reader.iterShapes(bbox=self._bbox):
             # Skip the shape that can not be represented as geometry.
             if shape.shapeType != shapefile.NULL:
                 yield sgeom.shape(shape)
@@ -168,28 +171,32 @@ def records(self):
         Return an iterator of :class:`~Record` instances.
 
         """
+
         # Ignore the "DeletionFlag" field which always comes first
         fields = self._reader.fields[1:]
-        for shape_record in self._reader.iterShapeRecords():
+        for shape_record in self._reader.iterShapeRecords(bbox=self._bbox):
             attributes = shape_record.record.as_dict()
             yield Record(shape_record.shape, attributes, fields)
 
 
 class FionaReader:
     """
     Provides an interface for accessing the contents of a shapefile
-    with the fiona library, which has a much faster reader than pyshp.
+    with the fiona library, which has a much faster reader than PyShp. See
+    `fiona.open
+    <https://fiona.readthedocs.io/en/latest/fiona.html#fiona.open>`_
+    for additional information on supported kwargs.
 
     The primary methods used on a FionaReader instance are
     :meth:`~cartopy.io.shapereader.FionaReader.records` and
     :meth:`~cartopy.io.shapereader.FionaReader.geometries`.
 
     """
 
-    def __init__(self, filename, bbox=None):
+    def __init__(self, filename, bbox=None, **kwargs):
         self._data = []
 
-        with fiona.open(filename) as f:
+        with fiona.open(filename, **kwargs) as f:
             if bbox is not None:
                 assert len(bbox) == 4
                 features = f.filter(bbox=bbox)
@@ -253,10 +260,19 @@ def records(self):
                                item.items() if key != 'geometry'})
 
 
-if _HAS_FIONA:
-    Reader = FionaReader
-else:
-    Reader = BasicReader
+Reader = FionaReader if _HAS_FIONA else BasicReader
+"""
+Alias of the default available shapereader interface.
+
+Will either be :class:`~cartopy.io.shapereader.FionaReader` (if fiona
+installed) or :class:`~cartopy.io.shapereader.BasicReader`
+(based on PyShp). Note that FionaReader has greater speed and additional
+functionality, including attempting to auto-detect source encoding and
+support for different format drivers. Both libraries support the 'encoding'
+and 'bbox' keyword arguments. If specific functionality is needed,
+BasicReader and FionaReader instances can also be created directly.
+
+"""
 
 
 def natural_earth(resolution='110m', category='physical', name='coastline'):