iris.io¶
Provides an interface to manage URI scheme support in iris.
In this module:
-
iris.io.
add_saver
(file_extension, new_saver)[source]¶ 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()
-
iris.io.
decode_uri
(uri, 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. 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/...')
-
iris.io.
expand_filespecs
(file_specs)[source]¶ 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.
-
iris.io.
find_saver
(filespec)[source]¶ Find the saver function appropriate to the given filename or extension.
- Parameters
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()
.
-
iris.io.
load_files
(filenames, 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.
Note
Typically, this function should not be called directly; instead, the intended interface for loading is
iris.load()
.
-
iris.io.
load_http
(urls, callback)[source]¶ 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()
.
-
iris.io.
run_callback
(callback, cube, field, filename)[source]¶ 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:
Function signature must be:
(cube, field, filename)
.Modifies the given cube inplace, unless a new cube is returned by the function.
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.
-
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:
- netCDF - the Unidata network Common Data Format:
- GRIB2 - the WMO GRIdded Binary data format:
see
iris_grib.save_grib2()
.
- PP - the Met Office UM Post Processing Format:
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 anappend
keyword if it’s file format can handle multiple cubes. See alsoiris.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.