iris.io#

Provides an interface to manage URI scheme support in iris.

iris.io.add_saver(file_extension, new_saver)[source]#

Add a custom saver to the Iris session.

Parameters:

  • file_extension (str) – A string such as “pp” or “my_format”.

  • new_saver (function) – A function of the form my_saver(cube, target).

See also

iris.io.save

Save one or more Cubes to file (or other writeable).

iris.io.decode_uri(uri, default='file')[source]#

Decode a single URI into scheme and scheme-specific parts.

In addition to well-formed URIs, it also supports bare file paths as strings or pathlib.PurePath. Both Windows and UNIX style paths are accepted.

It also supports ‘bare objects’, i.e. anything which is not a string. These are identified with a scheme of ‘data’, and returned unchanged.

Examples

>>> from iris.io import decode_uri
>>> print(decode_uri('https://www.thing.com:8080/resource?id=a:b'))
('https', '//www.thing.com:8080/resource?id=a:b')

>>> print(decode_uri('file:///data/local/dataZoo/...'))
('file', '///data/local/dataZoo/...')

>>> print(decode_uri('/data/local/dataZoo/...'))
('file', '/data/local/dataZoo/...')

>>> print(decode_uri('file:///C:\data\local\dataZoo\...'))
('file', '///C:\\data\\local\\dataZoo\\...')

>>> print(decode_uri('C:\data\local\dataZoo\...'))
('file', 'C:\\data\\local\\dataZoo\\...')

>>> print(decode_uri('dataZoo/...'))
('file', 'dataZoo/...')

>>> print(decode_uri({}))
('data', {})
iris.io.expand_filespecs(file_specs, files_expected=True)[source]#

Find all matching file paths from a list of file-specs.

Parameters:

  • file_specs (iterable of str) – File paths which may contain ~ elements or wildcards.

  • files_expected (bool, default=True) – Whether file is expected to exist (i.e. for load).

Returns:

If files_expected is True:

A well-ordered list of matching absolute file paths. If any of the file-specs match no existing files, an exception is raised.

If files_expected is False:

A list of expanded file paths.

Return type:

list of str

iris.io.find_saver(filespec)[source]#

Find the saver function appropriate to the given filename or extension.

Parameters:

filespec (str) – A string such as “my_file.pp” or “PP”.

Returns:

Save functions can be passed to iris.io.save(). Value may also be None.

Return type:

Save function

iris.io.load_data_objects(urls, callback)[source]#

Take a list of data-source objects and a callback function, returns a generator of Cubes.

The ‘objects’ take the place of ‘uris’ in the load calls. The appropriate types of the data-source objects are expected to be recognised by the handlers : This is done in the usual way by passing the context to the format picker to get a handler for each.

Note

Typically, this function should not be called directly; instead, the intended interface for loading is iris.load().

iris.io.load_files(filenames, callback, constraints=None)[source]#

Create a generator of Cubes from given files.

Take a list of filenames which may also be globs, and optionally a constraint set and a callback function, and returns a generator of Cubes from the given files.

Notes

Typically, this function should not be called directly; instead, the intended interface for loading is iris.load().

iris.io.load_http(urls, callback)[source]#

Create generator of Cubes from the given OPeNDAP URLs.

Take a list of OPeNDAP URLs and a callback function, and returns a generator of Cubes from the given URLs.

Notes

Typically, this function should not be called directly; instead, the intended interface for loading is iris.load().

iris.io.run_callback(callback, cube, field, filename)[source]#

Run the callback mechanism given the appropriate arguments.

Parameters:

callback –

A function to add metadata from the originating field and/or URI which obeys the following rules:

  1. Function signature must be: (cube, field, filename).

  2. Modifies the given cube inplace, unless a new cube is returned by the function.

  3. If the cube is to be rejected the callback must raise an iris.exceptions.IgnoreCubeException.

Notes

It is possible that this function returns None for certain callbacks, the caller of this function should handle this case.

This function maintains laziness when called; it does not realise data. See more at Real and Lazy Data.

iris.io.save(source, target, saver=None, **kwargs)[source]#

Save one or more Cubes to file (or other writeable).

Iris currently supports three file formats for saving, which it can recognise by filename extension:

A custom saver can be provided to the function to write to a different file format.

Parameters:

  • source (iris.cube.Cube or iris.cube.CubeList)

  • target (str or pathlib.PurePath or io.TextIOWrapper) – When given a filename or file, Iris can determine the file format.

  • saver (str or function, optional) –

    Specifies the file format to save. If omitted, Iris will attempt to determine the format. If a string, this is the recognised filename extension (where the actual filename may not have it).

    Otherwise the value is a saver function, of the form: my_saver(cube, target) plus any custom keywords. It is assumed that a saver will accept an append keyword if its file format can handle multiple cubes. See also iris.io.add_saver().

  • **kwargs (dict, optional) – All other keywords are passed through to the saver function; see the relevant saver documentation for more information on keyword arguments.

Warning

Saving a cube whose data has been loaded lazily (if cube.has_lazy_data() returns True) to the same file it expects to load data from will cause both the data in-memory and the data on disk to be lost.

cube = iris.load_cube("somefile.nc")
# The next line causes data loss in 'somefile.nc' and the cube.
iris.save(cube, "somefile.nc")

In general, overwriting a file which is the source for any lazily loaded data can result in corruption. Users should proceed with caution when attempting to overwrite an existing file.

Examples

>>> # Setting up
>>> import iris
>>> my_cube = iris.load_cube(iris.sample_data_path('air_temp.pp'))
>>> my_cube_list = iris.load(iris.sample_data_path('space_weather.nc'))

>>> # Save a cube to PP
>>> iris.save(my_cube, "myfile.pp")

>>> # Save a cube list to a PP file, appending to the contents of the file
>>> # if it already exists
>>> iris.save(my_cube_list, "myfile.pp", append=True)

>>> # Save a cube to netCDF, defaults to NETCDF4 file format
>>> iris.save(my_cube, "myfile.nc")

>>> # Save a cube list to netCDF, using the NETCDF3_CLASSIC storage option
>>> iris.save(my_cube_list, "myfile.nc", netcdf_format="NETCDF3_CLASSIC")

Notes

This function maintains laziness when called; it does not realise data. See more at Real and Lazy Data.

Submodules#