You are viewing the latest unreleased documentation v3.3.dev0. You may prefer a stable version.

Provides an interface to manage URI scheme support in iris.

In this module:, new_saver)[source]#

Add a custom saver to the Iris session.


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

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

See also

↑ top ↑, default='file')[source]#

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


>>> from import decode_uri
>>> print(decode_uri(''))
('http', '//')
>>> 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 ↑[source]#

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


  • file_specs (iterable of string):

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


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

↑ top ↑[source]#

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


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


A save function or None. Save functions can be passed to

↑ top ↑, callback, constraints=None)[source]#

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.


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

↑ top ↑, callback)[source]#

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


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

↑ top ↑, cube, field, filename)[source]#

Runs the callback mechanism given the appropriate arguments.


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


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

↑ top ↑, 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.


  • 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. Filename can be given as a string or pathlib.PurePath.


  • 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

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


# Save a cube to PP, "myfile.pp")

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

# Save a cube to netCDF, defaults to NETCDF4 file format, "")

# Save a cube list to netCDF, using the NETCDF3_CLASSIC storage option, "", netcdf_format="NETCDF3_CLASSIC")


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("")
# The next line causes data loss in '' and the cube., "")

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.