SciTools/iris — pull request #1159 by bjlittle (2014-06-04 12:37:13+00:00)
Title: Future NetCDF variable promotion.

This PR enhances the netCDF loader to allow it the ability to promote multi-dimensional auxiliary coordinate variables to be data variables i.e. cubes.

This functionality is exposed to the user via the `iris.FUTURE` API and the controlled attribute `netcdf_promote`. This permits the following usage:

* Use the netCDF loader as normal, with no variable promotion:

```python
cubes = iris.load(fname)
```

* Turn-on, and keep on, variable promotion until explicitly turned-off:

```python
iris.FUTURE.netcdf_promote = True
cubes = iris.load(fname)
...
iris.FUTURE.netcdf_promote = False
```

* Turn-on variable promotion limited to within a context scope:
```python
with iris.FUTURE.context(netcdf_promote=True):
cubes = iris.load(fname)
```

The `iris.FUTURE` approach was adopted rather than explicitly naming netCDF variables to promote, as the user may not know beforehand, the names of the variables that require to be promoted to cubes. It also avoids the propagation of `kwargs` down through to the loader.

Note that, a specific promoted variable cube may be targeted using the standard constrained loading mechanism:

```python
with iris.FUTURE.context(netcdf_promote=True):
cube = iris.load_cube(fname, 'sea_surface_height_above_geoid')
```

Closes PR #1070.