Docs for Env and method name change

Also remove rfc3987

rasterio/env.py

@@ -13,17 +13,64 @@
 
 
 class Env(GDALEnv):
-    """Abstraction for GDAL and AWS configuration"""
+    """Abstraction for GDAL and AWS configuration
+
+    The GDAL library is stateful: it has a registry of format drivers,
+    an error stack, and dozens of configuration options.
+
+    Rasterio's approach to working with GDAL is to wrap all the state
+    up using a Python context manager (see PEP 343,
+    https://www.python.org/dev/peps/pep-0343/). When the context is
+    entered GDAL drivers are registered, error handlers are
+    configured, and configuration options are set. When the context
+    is exited, drivers are removed from the registry and other
+    configurations are removed.
+
+    Example:
+
+        with Env(GDAL_CACHEMAX=512) as env:
+            # All drivers are registered, GDAL's raster block cache
+            # size is set to 512MB.
+            # Commence processing...
+            ...
+            # End of processing.
+
+        # At this point, configuration options are set to their
+        # previous (possible unset) values.
+
+    A boto3 session or boto3 session constructor arguments
+    `aws_access_key_id`, `aws_secret_access_key`, `aws_session_token`
+    may be passed to Env's constructor. In the latter case, a session
+    will be created as soon as needed. AWS credentials are configured
+    for GDAL as needed.
+    """
 
     def __init__(self, aws_session=None, **options):
+        """Create a new GDAL/AWS environment.
+
+        Note: this class is a context manager. GDAL isn't configured
+        until the context is entered via `with Env():`
+
+        Parameters
+        ----------
+        aws_session: object, optional
+            A boto3 session.
+        **options: optional
+            A mapping of boto3 session constructor keyword arguments
+            and GDAL configuration options.
+
+        Returns
+        -------
+        A new instance of Env.
+        """
         super(Env, self).__init__(**options)
         self.aws_session = aws_session
         self._creds = (
             self.aws_session._session.get_credentials()
             if self.aws_session else None)
 
-    def _get_aws_credentials(self):
-        """Create a boto3 session and extract credentials from it"""
+    def get_aws_credentials(self):
+        """Get credentials and configure GDAL."""
         if not self.started:
             raise EnvError(
                 "Credentials can't be obtained until an Env has been entered.")
@@ -173,7 +220,7 @@ def open(self, path, mode='r', driver=None, width=None, height=None,
         # on S3.
         pth, archive, scheme = parse_path(path)
         if scheme == 's3' and not _env._creds:
-            _env._get_aws_credentials()
+            _env.get_aws_credentials()
             log.debug("In env %r AWS credentials have been obtained", _env)
 
         # Create dataset instances and pass the given env, which will

setup.py

@@ -215,7 +215,7 @@ def copy_data_tree(datadir, destdir):
     readme = f.read()
 
 # Runtime requirements.
-inst_reqs = ['affine', 'cligj', 'numpy', 'snuggs', 'click-plugins', 'rfc3987']
+inst_reqs = ['affine', 'cligj', 'numpy', 'snuggs', 'click-plugins']
 
 if sys.version_info < (3, 4):
     inst_reqs.append('enum34')
@@ -274,8 +274,8 @@ def copy_data_tree(datadir, destdir):
     install_requires=inst_reqs,
     extras_require={
         'ipython': ['ipython>=2.0'],
-        's3': ['boto3'],
-        'test': ['boto3', 'packaging']})
+        's3': ['boto3>=1.2.4'],
+        'test': ['boto3>=1.2.4', 'packaging']})
 
 if os.environ.get('PACKAGE_DATA'):
     setup_args['package_data'] = {'rasterio': ['gdal_data/*', 'proj_data/*']}

tests/test_env.py

@@ -67,7 +67,7 @@ def test_session_lazy():
             aws_access_key_id='id', aws_secret_access_key='key',
             aws_session_token='token', region_name='null-island-1') as s:
         assert s._creds is None
-        s._get_aws_credentials()
+        s.get_aws_credentials()
         assert s._creds.access_key == 'id'
         assert s._creds.secret_key == 'key'
         assert s._creds.token == 'token'
@@ -81,7 +81,7 @@ def test_session_env_lazy(monkeypatch):
     monkeypatch.setenv('AWS_SESSION_TOKEN', 'token')
     with Env() as s:
         assert s._creds is None
-        s._get_aws_credentials()
+        s.get_aws_credentials()
         assert s._creds.access_key == 'id'
         assert s._creds.secret_key == 'key'
         assert s._creds.token == 'token'
@@ -93,7 +93,7 @@ def test_session_lazy_env_error():
     s = Env(aws_access_key_id='id', aws_secret_access_key='key',
             aws_session_token='token', region_name='null-island-1')
     with pytest.raises(EnvError):
-        s._get_aws_credentials()
+        s.get_aws_credentials()
 
 
 @mingdalversion