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

classmethod default_options()

Default configuration options

Parameters:: None
Return type:: dict

drivers(): Return a mapping of registered drivers.

classmethod from_defaults(*args, **kwargs)

Create an environment with default config options

Parameters:

args (optional) – Positional arguments for Env()
kwargs (optional) – Keyword arguments for Env()

Return type:

Env

Notes

The items in kwargs will be overlaid on the default values.

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.NullContextManager: Bases: object

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.