From 52c2fc46a547e99dd8d70d3cef6c0d02ff0088d9 Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Thu, 24 Oct 2024 17:09:37 +0100 Subject: [PATCH] Review changes : documentation improvements. --- lib/iris/__init__.py | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/lib/iris/__init__.py b/lib/iris/__init__.py index 0a3541bcb4..60b0a10ee7 100644 --- a/lib/iris/__init__.py +++ b/lib/iris/__init__.py @@ -317,12 +317,22 @@ def _load_collection(uris, constraints=None, callback=None): class LoadPolicy(threading.local): """A container for loading strategy options. - Controls merge/concatenate usage, and the handling of cases where multiple reference - fields merge to define an additional dimension (e.g. a time-varying orography). + Controls merge/concatenate usage during loading. + + Also controls the detection and handling of cases where a hybrid coordinate + uses multiple reference fields : for example, a UM file which contains a series of + fields describing time-varying orography. Options can be set directly, or via :meth:`~iris.LoadPolicy.set`, or changed for the scope of a code block with :meth:`~iris.LoadPolicy.context`. + .. note :: + + The default behaviour will "fix" loading for cases like the one just described. + However this is not strictly backwards-compatible. If this causes problems, + you can force identical loading behaviour to earlier Iris versions with + ``LOAD_POLICY.set("legacy")`` or equivalent. + .. testsetup:: from iris import LOAD_POLICY @@ -528,10 +538,10 @@ def context(self, settings=None, **kwargs): 0: x_wind / (m s-1) (time: 2; model_level_number: 5; latitude: 144; longitude: 192) 1: x_wind / (m s-1) (time: 12; model_level_number: 5; latitude: 144; longitude: 192) 2: x_wind / (m s-1) (model_level_number: 5; latitude: 144; longitude: 192) - + >>> >>> with LOAD_POLICY.context("recommended"): ... cubes = iris.load(path, "x_wind") - >>> cubes + >>> print(cubes) 0: x_wind / (m s-1) (model_level_number: 5; time: 15; latitude: 144; longitude: 192)> """ # Save the current state @@ -546,7 +556,7 @@ def context(self, settings=None, **kwargs): self.set(saved_settings) -#: Object containing file loading options. +#: A control object containing the current file loading options. LOAD_POLICY = LoadPolicy("legacy") # The unique (singleton) policy object # N.B. FOR NOW, our starting point is "legacy" rather than "default"