rasterio.env module
Rasterio’s GDAL/AWS environment
- class rasterio.env.Env(session=None, aws_unsigned=False, profile_name=None, session_class=<function Session.aws_or_dummy>, **options)
Bases:
object
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 rasterio.Env(GDAL_CACHEMAX=128000000) as env: # All drivers are registered, GDAL's raster block cache # size is set to 128 MB. # 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.
- aws_creds_from_context_options()
- credentialize()
Get credentials and configure GDAL
Note well: this method is a no-op if the GDAL environment already has credentials, unless session is not None.
- Return type:
None
- drivers()
Return a mapping of registered drivers.
- class rasterio.env.GDALVersion(major=0, minor=0)
Bases:
object
Convenience class for obtaining GDAL major and minor version components and comparing between versions. This is highly simplistic and assumes a very normal numbering scheme for versions and ignores everything except the major and minor components.
- at_least(other)
- major
- minor
- classmethod parse(input)
Parses input tuple or string to GDALVersion. If input is a GDALVersion instance, it is returned.
- Parameters:
input (tuple of (major, minor), string, or instance of GDALVersion) –
- Return type:
GDALVersion instance
- classmethod runtime()
Return GDALVersion of current GDAL runtime
- class rasterio.env.ThreadEnv
Bases:
_local
- rasterio.env.defenv(**options)
Create a default environment if necessary.
- rasterio.env.delenv()
Delete options in the existing environment.
- rasterio.env.ensure_env(f)
A decorator that ensures an env exists before a function calls any GDAL C functions.
- rasterio.env.ensure_env_credentialled(f)
DEPRECATED alias for ensure_env_with_credentials
- rasterio.env.ensure_env_with_credentials(f)
Ensures a config environment exists and is credentialized
- Parameters:
f (function) – A function.
- Return type:
A function wrapper.
Notes
The function wrapper checks the first argument of f and credentializes the environment if the first argument is a URI with scheme “s3”.
- rasterio.env.env_ctx_if_needed()
Return an Env if one does not exist
- Return type:
Env or a do-nothing context manager
- rasterio.env.getenv()
Get a mapping of current options.
- rasterio.env.hascreds()
- rasterio.env.hasenv()
- rasterio.env.require_gdal_version(version, param=None, values=None, is_max_version=False, reason='')
A decorator that ensures the called function or parameters are supported by the runtime version of GDAL. Raises GDALVersionError if conditions are not met.
Examples
@require_gdal_version('2.2') def some_func():
calling some_func with a runtime version of GDAL that is < 2.2 raises a GDALVersionErorr.
@require_gdal_version('2.2', param='foo') def some_func(foo='bar'):
calling some_func with parameter foo of any value on GDAL < 2.2 raises a GDALVersionError.
@require_gdal_version('2.2', param='foo', values=('bar',)) def some_func(foo=None):
calling some_func with parameter foo and value bar on GDAL < 2.2 raises a GDALVersionError.
- Parameters:
version (tuple, string, or GDALVersion) –
param (string (optional, default: None)) – If values are absent, then all use of this parameter with a value other than default value requires at least GDAL version.
values (tuple, list, or set (optional, default: None)) – contains values that require at least GDAL version. param is required for values.
is_max_version (bool (optional, default: False)) – if True indicates that the version provided is the maximum version allowed, instead of requiring at least that version.
reason (string (optional: default: '')) – custom error message presented to user in addition to message about GDAL version. Use this to provide an explanation of what changed if necessary context to the user.
- Return type:
wrapped function
- rasterio.env.setenv(**options)
Set options in the existing environment.