Logo Iris 1.12

Previous topic

iris.fileformats.um_cf_map

Next topic

iris.io.format_picker

This Page

iris.io

Provides an interface to manage URI scheme support in iris.

In this module:

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 list of matching file paths. If any of the file-specs matches no existing files, an exception is raised.

↑ top ↑

iris.io.find_saver(filespec)

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

Args:

  • filespec - A string such as “my_file.pp” or “PP”.
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 writable).

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.

Args:

  • source - A iris.cube.Cube, iris.cube.CubeList or

    sequence of cubes.

  • target - A filename (or writable, depending on file format).

    When given a filename or file, Iris can determine the file format.

Kwargs:

  • saver - Optional. Specifies the save function to use.

    If omitted, Iris will attempt to determine the format.

    This keyword can be used to implement a custom save format. Function form must be: 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.