Source code for iris.fileformats.netcdf.loader

# Copyright Iris contributors
#
# This file is part of Iris and is released under the BSD license.
# See LICENSE in the root of the repository for full licensing details.
"""Load Iris cubes from NetCDF files and OPeNDAP URLs.

.. deprecated:: 3.17
    ``CHUNK_CONTROL`` and ``ChunkControl`` have moved to
    :mod:`iris.fileformats.cf.loader`, because chunking policy is not specific
    to netCDF. They can still be reached here, with a warning, for one
    deprecation cycle.

.. z_reference:: iris.fileformats.netcdf.loader
   :tags: topic_load_save

   API reference

See : `NetCDF User's Guide <https://docs.unidata.ucar.edu/nug/current/>`_
and `netCDF4 python module <https://github.com/Unidata/netcdf4-python>`_.

Also : `CF Conventions <https://cfconventions.org/>`_.

.. maintainer-notes::

   What is left here is what is genuinely netCDF's: opening the file sources,
   and the proxy class that reads from them. Interpreting what is inside is
   :mod:`iris.fileformats.cf.loader`'s job.

"""

from collections.abc import Iterable
import warnings

from iris._deprecation import warn_deprecated
from iris.fileformats.cf.loader import (
    _actions_engine,
    _load_aux_factory,
    _load_cube,
    _translate_constraints_to_var_callback,
)
import iris.warnings

# Show actions activation statistics.
# NOTE: read by iris.fileformats.cf.loader._load_cube_inner, through this
# module rather than by value, so that assigning to it here still works.
DEBUG = False

# Get _bytecoding_datasets, needed by NetCDFDataProxy just below.
from . import _bytecoding_datasets

# An expected part of the public loader API, but includes thread safety
#  concerns so is housed in _thread_safe_nc.
# NOTE: this is the *default*, as required for public legacy api
#  - in practice, when creating our proxies we dynamically choose between this and
#    :class:`_thread_safe_nc.DatasetWrapper`, depending on
#    :data:`_bytecoding_datasets.DECODE_TO_STRINGS_ON_READ`
NetCDFDataProxy = _bytecoding_datasets.EncodedNetCDFDataProxy

#: Names that moved to :mod:`iris.fileformats.cf.loader` in Iris 3.17 and are
#: still readable here, with a warning, for one deprecation cycle.
#:
#: Read-only: a module ``__getattr__`` cannot intercept assignment, so a name
#: that users *set* must keep its definition here instead. ``DEBUG`` is the
#: one such name, and is deliberately absent from this set.
#:
#: The same limitation means ``mock.patch("iris.fileformats.netcdf.loader."
#: "CHUNK_CONTROL", ...)`` succeeds and is a silent no-op: ``mock.patch``
#: creates the attribute on this module, while production code reads
#: ``iris.fileformats.cf.loader.CHUNK_CONTROL``. Patch
#: :mod:`iris.fileformats.cf.loader` instead.
_RELOCATED_NAMES = frozenset({"CHUNK_CONTROL", "ChunkControl"})


[docs] def __getattr__(name): """Forward a relocated name to :mod:`iris.fileformats.cf.loader`. Parameters ---------- name : str The attribute being looked up. Python calls this only for names that are not already module attributes. Returns ------- Any The object of that name in :mod:`iris.fileformats.cf.loader` - the same object, not a copy. Raises ------ AttributeError If ``name`` is not one of the relocated names. Raised without warning, so that a ``hasattr`` probe that comes back False stays quiet. """ if name not in _RELOCATED_NAMES: raise AttributeError(f"module {__name__!r} has no attribute {name!r}") # Deferred so that importing this module stays quiet and cheap. from iris.fileformats.cf import loader as cf_loader warn_deprecated( f"iris.fileformats.netcdf.loader.{name} has moved to " f"iris.fileformats.cf.loader.{name}, because it is not specific to " "netCDF. The name here will be removed in a future release.", # warn_deprecated's default stacklevel=2 points at the line below, # inside this function - PEP 562 means that line is a genuine call # frame, not the user's code. One level further out reaches the # line that actually read the attribute. stacklevel=3, ) return getattr(cf_loader, name)
[docs] def __dir__(): """List module attributes, including the relocated names. A module ``__getattr__`` forwards reads of the relocated names, but does not make them discoverable: PEP 562 does not extend to ``dir()``, :func:`inspect.getmembers`, or tab-completion, so this fills the gap. Returns ------- list of str The real module globals, unioned with the relocated names. """ return sorted(set(globals()) | _RELOCATED_NAMES)
[docs] def load_cubes(file_sources, callback=None, constraints=None): """Load cubes from a list of NetCDF filenames/OPeNDAP URLs. Also supports Zarr files in the NcZarr URL format, e.g. ``file:///path/to/file#mode=nczarr,file``. Note that NcZarr is limited to Zarr Storage Specification version 2. See the `NcZarr docs <https://docs.unidata.ucar.edu/nug/current/nczarr_head.html>` for more. Parameters ---------- file_sources : str or list One or more NetCDF filenames/OPeNDAP URLs/NcZarr URLs to load from. OR open datasets. callback : function, optional Function which can be passed on to :func:`iris.io.run_callback`. constraints : optional Returns ------- Generator of loaded NetCDF/NcZarr :class:`iris.cube.Cube`. """ # Deferred import to avoid circular imports. from iris.fileformats.cf import CFReader from iris.io import run_callback from .ugrid_load import ( _attach_mesh_coords, _meshes_from_cf, _prepare_mesh_coords, ) # Create a low-level data-var filter from the original load constraints, if they are suitable. var_callback = _translate_constraints_to_var_callback(constraints) # Create an actions engine. engine = _actions_engine() if isinstance(file_sources, str) or not isinstance(file_sources, Iterable): file_sources = [file_sources] for file_source in file_sources: # Ingest the file. At present may be a filepath or an open netCDF4.Dataset. with CFReader(file_source) as cf: meshes = _meshes_from_cf(cf) # Process each CF data variable. data_variables = list(cf.cf_group.data_variables.values()) + list( cf.cf_group.promoted.values() ) for cf_var in data_variables: if var_callback and not var_callback(cf_var): # Deliver only selected results. continue # MeshCoords are built before the cube and attached after it: # see _prepare_mesh_coords for why the two cannot be one step. pending_mesh_coords = _prepare_mesh_coords(cf, meshes, cf_var) cube = _load_cube(engine, cf, cf_var, cf.filename) if pending_mesh_coords is not None: _attach_mesh_coords(pending_mesh_coords, cube) # Process any associated formula terms and attach # the corresponding AuxCoordFactory. try: _load_aux_factory(engine, cube) except ValueError as e: warnings.warn( "{}".format(e), category=iris.warnings.IrisLoadWarning, ) # Perform any user registered callback function. cube = run_callback(callback, cube, cf_var, file_source) # Callback mechanism may return None, which must not be yielded if cube is None: continue yield cube