iris.io

Provides an interface to manage URI scheme support in iris.

In this module:

• add_saver

• decode_uri

• expand_filespecs

• find_saver

• load_files

• load_http

• run_callback

• save

iris.io.add_saver(file_extension, new_saver)

Add a custom saver to the Iris session.

Args:

• file_extension: A string such as “pp” or “my_format”.

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

See also iris.io.save()

↑ top ↑

iris.io.decode_uri(uri, default='file')

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

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

Examples

>>> from iris.io import decode_uri
>>> print(decode_uri('http://www.thing.com:8080/resource?id=a:b'))
('http', '//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/...')

↑ top ↑

iris.io.expand_filespecs(file_specs)

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

Args:

• file_specs (iterable of string):

  File paths which may contain ‘~’ elements or wildcards.

Returns

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

↑ top ↑

iris.io.find_saver(filespec)

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

Parameters

"PP". (* filespec - A string such as "my_file.pp" or) –

Returns

A save function or None. Save functions can be passed to iris.io.save().

↑ top ↑

iris.io.load_files(filenames, callback, constraints=None)

Takes 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.

Note

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

↑ top ↑

iris.io.load_http(urls, callback)

Takes a list of urls and a callback function, and returns a generator of Cubes from the given URLs.

Note

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

↑ top ↑

iris.io.run_callback(callback, cube, field, filename)

Runs the callback mechanism given the appropriate arguments.

Args:

• 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.

Note

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

↑ top ↑

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

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:

• netCDF - the Unidata network Common Data Format:

  • see iris.fileformats.netcdf.save()

• GRIB2 - the WMO GRIdded Binary data format:

  • see iris_grib.save_grib2().

• PP - the Met Office UM Post Processing Format:

  • see iris.fileformats.pp.save()

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

Args:

• source:

  iris.cube.Cube, iris.cube.CubeList or sequence of cubes.

• target:

  A filename (or writeable, depending on file format). When given a filename or file, Iris can determine the file format.

Kwargs:

• saver:

  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 it’s file format can handle multiple cubes. See also iris.io.add_saver().

All other keywords are passed through to the saver function; see the relevant saver documentation for more information on keyword arguments.

Examples:

# 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")

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.