sue triple quotes instead of hash colon

benchmarks/benchmarks/generate_data/__init__.py

@@ -26,11 +26,12 @@
 from iris._lazy_data import as_concrete_data
 from iris.fileformats import netcdf
 
-#: Python executable used by :func:`run_function_elsewhere`, set via env
-#:  variable of same name. Must be path of Python within an environment that
-#:  includes Iris (including dependencies and test modules) and Mule.
 try:
     DATA_GEN_PYTHON = environ["DATA_GEN_PYTHON"]
+    """Python executable used by :func:`run_function_elsewhere`, set via env variable of same name.
+       Must be path of Python within an environment that
+       includes Iris (including dependencies and test modules) and Mule."""
+
     _ = check_output([DATA_GEN_PYTHON, "-c", "a = True"])
 except KeyError:
     error = "Env variable DATA_GEN_PYTHON not defined."

lib/iris/__init__.py

@@ -243,16 +243,14 @@ def context(self, **kwargs):
             self.__dict__.update(current_state)
 
 
-#: Object containing all the Iris run-time options.
 FUTURE = Future()
+"""Object containing all the Iris run-time options."""
 
-
-# Initialise the site configuration dictionary.
-#: Iris site configuration dictionary.
 site_configuration: dict[
     Literal["cf_profile", "cf_patch", "cf_patch_conventions"],
     Callable | Literal[False] | None,
 ] = {}
+"""Initialise the site configuration dictionary."""
 
 try:
     from iris.site_config import update as _update

lib/iris/analysis/__init__.py

@@ -486,15 +486,17 @@ def __init__(
             Passed through to :data:`call_func`, :data:`lazy_func`, and
             :data:`units_func`.
         """
-        #: Cube cell method string.
         self.cell_method = cell_method
-        #: Data aggregation function.
+        """Cube cell method string."""
+
         self.call_func = call_func
-        #: Unit conversion function.
+        """Data aggregation function."""
+
         self.units_func = units_func
-        #: Lazy aggregation function, may be None to indicate that a lazy
-        #: operation is not available.
+        """Unit conversion function."""
+
         self.lazy_func = lazy_func
+        """Lazy aggregation function, may be None to indicate that a lazy operation is not available."""
 
         self._kwargs = kwargs
 
@@ -948,8 +950,8 @@ def __init__(self, units_func=None, lazy_func=None, **kwargs):
         self._name = "weighted_percentile"
         self._args = ["percent", "weights"]
 
-        #: A list of keywords associated with weighted behaviour.
         self._weighting_keywords = ["returned", "weights"]
+        """A list of keywords associated with weighted behaviour."""
 
     def post_process(
         self, collapsed_cube, data_result, coords, **kwargs
@@ -1086,8 +1088,8 @@ def __init__(
             **kwargs,
         )
 
-        #: A list of keywords that trigger weighted behaviour.
         self._weighting_keywords = ["returned", "weights"]
+        """A list of keywords that trigger weighted behaviour."""
 
     def uses_weighting(self, **kwargs):
         """Determine whether this aggregator uses weighting.
@@ -2309,8 +2311,9 @@ def __init__(
             preserving the time of year.
 
         """
-        #: Group-by and shared coordinates that have been grouped.
         self.coords: list[iris.coords.Coord] = []
+        """Group-by and shared coordinates that have been grouped."""
+
         self._groupby_coords: list[iris.coords.Coord] = []
         self._shared_coords: list[tuple[iris.coords.Coord, int]] = []
         self._groupby_indices: list[tuple[int, ...]] = []

lib/iris/analysis/calculus.py

@@ -739,8 +739,6 @@ def curl(i_cube, j_cube, k_cube=None):
     return result
 
 
-#: Acceptable X-Y-Z standard name combinations that
-#:  :func:`curl` can use (via :func:`spatial_vectors_with_phenom_name`).
 DIRECTIONAL_NAMES: tuple[tuple[str, str, str], ...] = (
     ("u", "v", "w"),
     ("x", "y", "z"),
@@ -749,6 +747,8 @@ def curl(i_cube, j_cube, k_cube=None):
     ("easterly", "northerly", "vertical"),
     ("easterly", "northerly", "radial"),
 )
+"""Acceptable X-Y-Z standard name combinations that :func:`curl` can use
+   (via :func:`spatial_vectors_with_phenom_name`)."""
 
 
 def spatial_vectors_with_phenom_name(i_cube, j_cube, k_cube=None):

lib/iris/aux_factory.py

@@ -37,11 +37,11 @@ def __init__(self):
         if not hasattr(self, "_metadata_manager"):
             self._metadata_manager = metadata_manager_factory(CoordMetadata)
 
-        #: Descriptive name of the coordinate made by the factory
         self.long_name = None
+        """Descriptive name of the coordinate made by the factory."""
 
-        #: netCDF variable name for the coordinate made by the factory
         self.var_name = None
+        """netCDF variable name for the coordinate made by the factory."""
 
         self.coord_system = None
         # See the climatological property getter.

lib/iris/common/lenient.py

@@ -17,14 +17,14 @@
 ]
 
 
-#: Default _Lenient services global activation state.
 _LENIENT_ENABLE_DEFAULT = True
+"""Default _Lenient services global activation state."""
 
-#: Default Lenient maths feature state.
 _LENIENT_MATHS_DEFAULT = True
+"""Default Lenient maths feature state."""
 
-#: Protected _Lenient internal non-client, non-service keys.
 _LENIENT_PROTECTED = ("active", "enable")
+"""Protected _Lenient internal non-client, non-service keys."""
 
 
 def _lenient_client(*dargs, services=None):
@@ -654,8 +654,8 @@ def unregister_service(self, func):
             raise ValueError(emsg)
 
 
-#: (Private) Instance that manages all Iris run-time lenient client and service options.
 _LENIENT = _Lenient()
+"""(Private) Instance that manages all Iris run-time lenient client and service options."""
 
-#: (Public) Instance that manages all Iris run-time lenient features.
 LENIENT = Lenient()
+"""(Public) Instance that manages all Iris run-time lenient features."""

lib/iris/common/metadata.py

@@ -1461,8 +1461,8 @@ def get_axis(instance):
 @lru_cache(maxsize=None)
 def _factory_cache(cls):
     def __init__(self, cls, **kwargs):
-        #: The metadata class to be manufactured by this factory.
         self.cls = cls
+        """The metadata class to be manufactured by this factory."""
 
         # Proxy for self.cls._fields for later internal use, as this
         # saves on indirect property lookup via self.cls
@@ -1600,7 +1600,6 @@ def metadata_manager_factory(cls, **kwargs):
     return manager
 
 
-#: Convenience collection of lenient metadata combine services.
 # TODO: change lists back to tuples once CellMeasureMetadata is re-integrated
 # here (currently in experimental.ugrid).
 SERVICES_COMBINE = [
@@ -1611,9 +1610,8 @@ def metadata_manager_factory(cls, **kwargs):
     CubeMetadata.combine,
     DimCoordMetadata.combine,
 ]
+"""Convenience collection of lenient metadata combine services."""
 
-
-#: Convenience collection of lenient metadata difference services.
 SERVICES_DIFFERENCE = [
     AncillaryVariableMetadata.difference,
     BaseMetadata.difference,
@@ -1622,9 +1620,8 @@ def metadata_manager_factory(cls, **kwargs):
     CubeMetadata.difference,
     DimCoordMetadata.difference,
 ]
+"""Convenience collection of lenient metadata difference services."""
 
-
-#: Convenience collection of lenient metadata equality services.
 SERVICES_EQUAL = [
     AncillaryVariableMetadata.__eq__,
     AncillaryVariableMetadata.equal,
@@ -1639,7 +1636,7 @@ def metadata_manager_factory(cls, **kwargs):
     DimCoordMetadata.__eq__,
     DimCoordMetadata.equal,
 ]
+"""Convenience collection of lenient metadata equality services."""
 
-
-#: Convenience collection of lenient metadata services.
 SERVICES = SERVICES_COMBINE + SERVICES_DIFFERENCE + SERVICES_EQUAL
+"""Convenience collection of lenient metadata services."""

lib/iris/common/mixin.py

@@ -67,7 +67,6 @@ class LimitedAttributeDict(dict):
 
     """
 
-    #: Attributes with special CF meaning, forbidden in Iris attribute dictionaries.
     CF_ATTRS_FORBIDDEN = (
         "standard_name",
         "long_name",
@@ -88,6 +87,7 @@ class LimitedAttributeDict(dict):
         "scale_factor",
         "_FillValue",
     )
+    """Attributes with special CF meaning, forbidden in Iris attribute dictionaries."""
 
     def __init__(self, *args, **kwargs):
         dict.__init__(self, *args, **kwargs)

lib/iris/common/resolve.py

@@ -264,62 +264,72 @@ def __init__(self, lhs=None, rhs=None):
             True
 
         """
-        #: The ``lhs`` operand to be resolved into the resultant :class:`~iris.cube.Cube`.
         self.lhs_cube = None  # set in __call__
-        #: The ``rhs`` operand to be resolved into the resultant :class:`~iris.cube.Cube`.
+        """The ``lhs`` operand to be resolved into the resultant :class:`~iris.cube.Cube`."""
+
         self.rhs_cube = None  # set in __call__
+        """The ``rhs`` operand to be resolved into the resultant :class:`~iris.cube.Cube`."""
 
-        #: The transposed/reshaped (if required) ``lhs`` :class:`~iris.cube.Cube`, which
-        #: can be broadcast with the ``rhs`` :class:`~iris.cube.Cube`.
         self.lhs_cube_resolved = None
-        #: The transposed/reshaped (if required) ``rhs`` :class:`~iris.cube.Cube`, which
-        #: can be broadcast with the ``lhs`` :class:`~iris.cube.Cube`.
+        """The transposed/reshaped (if required)
+           ``lhs`` :class:`~iris.cube.Cube`, which
+           can be broadcast with the ``rhs`` :class:`~iris.cube.Cube`."""
+
         self.rhs_cube_resolved = None
+        """The transposed/reshaped (if required)
+           ``rhs`` :class:`~iris.cube.Cube`, which can be broadcast with the
+           ``lhs`` :class:`~iris.cube.Cube`."""
 
-        #: Categorised dim, aux and scalar coordinate items for ``lhs`` :class:`~iris.cube.Cube`.
         self.lhs_cube_category = None  # set in _metadata_resolve
-        #: Categorised dim, aux and scalar coordinate items for ``rhs`` :class:`~iris.cube.Cube`.
+        """Categorised dim, aux and scalar coordinate items for ``lhs`` :class:`~iris.cube.Cube`."""
+
         self.rhs_cube_category = None  # set in _metadata_resolve
+        """Categorised dim, aux and scalar coordinate items for ``rhs`` :class:`~iris.cube.Cube`."""
 
-        #: Categorised dim, aux and scalar coordinate items **local** to the
-        #: ``lhs`` :class:`~iris.cube.Cube` only.
         self.lhs_cube_category_local = None  # set in _metadata_resolve
-        #: Categorised dim, aux and scalar coordinate items **local** to the
-        #: ``rhs`` :class:`~iris.cube.Cube` only.
+        """Categorised dim, aux and scalar coordinate items **local** to the ``lhs`` :class:`~iris.cube.Cube` only."""
+
         self.rhs_cube_category_local = None  # set in _metadata_resolve
-        #: Categorised dim, aux and scalar coordinate items **common** to both
-        #: the ``lhs`` :class:`~iris.cube.Cube` and the ``rhs`` :class:`~iris.cube.Cube`.
+        """Categorised dim, aux and scalar coordinate items **local** to the ``rhs`` :class:`~iris.cube.Cube` only."""
+
         self.category_common = None  # set in _metadata_resolve
+        """Categorised dim, aux and scalar coordinate items
+           **common** to both the ``lhs`` :class:`~iris.cube.Cube` and
+           the ``rhs`` :class:`~iris.cube.Cube`."""
 
-        #: Analysis of dim coordinates spanning the ``lhs`` :class:`~iris.cube.Cube`.
         self.lhs_cube_dim_coverage = None  # set in _metadata_coverage
-        #: Analysis of aux and scalar coordinates spanning the ``lhs`` :class:`~iris.cube.Cube`.
+        """Analysis of dim coordinates spanning the ``lhs`` :class:`~iris.cube.Cube`."""
+
         self.lhs_cube_aux_coverage = None  # set in _metadata_coverage
-        #: Analysis of dim coordinates spanning the ``rhs`` :class:`~iris.cube.Cube`.
+        """Analysis of aux and scalar coordinates spanning the ``lhs`` :class:`~iris.cube.Cube`."""
+
         self.rhs_cube_dim_coverage = None  # set in _metadata_coverage
-        #: Analysis of aux and scalar coordinates spanning the ``rhs`` :class:`~iris.cube.Cube`.
+        """Analysis of dim coordinates spanning the ``rhs`` :class:`~iris.cube.Cube`."""
+
         self.rhs_cube_aux_coverage = None  # set in _metadata_coverage
+        """Analysis of aux and scalar coordinates spanning the ``rhs`` :class:`~iris.cube.Cube`."""
 
-        #: Map **common** metadata from the ``rhs`` :class:`~iris.cube.Cube` to
-        #: the ``lhs`` :class:`~iris.cube.Cube` if ``lhs-rank`` >= ``rhs-rank``,
-        #: otherwise map **common** metadata from the ``lhs`` :class:`~iris.cube.Cube`
-        #: to the ``rhs`` :class:`~iris.cube.Cube`.
         self.map_rhs_to_lhs = None  # set in __call__
+        """Map **common** metadata from the ``rhs`` :class:`~iris.cube.Cube` to the ``lhs`` :class:`~iris.cube.Cube`
+           if ``lhs-rank`` >= ``rhs-rank``, otherwise map **common** metadata from
+           the ``lhs`` :class:`~iris.cube.Cube` to the
+           ``rhs`` :class:`~iris.cube.Cube`."""
 
-        #: Mapping of the dimensions between **common** metadata for the :class:`~iris.cube.Cube`
-        #: operands, where the direction of the mapping is governed by
-        #: :attr:`~iris.common.resolve.Resolve.map_rhs_to_lhs`.
         self.mapping = None  # set in _metadata_mapping
+        """Mapping of the dimensions between **common** metadata.
+           For the :class:`~iris.cube.Cube` operands, where the direction of the
+           mapping is governed by
+           :attr:`~iris.common.resolve.Resolve.map_rhs_to_lhs`."""
 
-        #: Cache containing a list of dim, aux and scalar coordinates prepared
-        #: and ready for creating and attaching to the resultant resolved
-        #: :class:`~iris.cube.Cube`.
         self.prepared_category = None  # set in _metadata_prepare
+        """Cache containing a list of dim, aux and scalar coordinates.
+           Prepared and ready for creating and attaching to the resultant resolved
+           :class:`~iris.cube.Cube`."""
 
-        #: Cache containing a list of aux factories prepared and ready for
-        #: creating and attaching to the resultant resolved
-        #: :class:`~iris.cube.Cube`.
         self.prepared_factories = None  # set in _metadata_prepare
+        """Cache containing a list of aux factories.
+           Prepared and ready for creating and attaching to the resultant resolved
+           :class:`~iris.cube.Cube`."""
 
         # The shape of the resultant resolved cube.
         self._broadcast_shape = None  # set in _as_compatible_cubes

lib/iris/config.py

@@ -127,7 +127,7 @@ def get_dir_option(section, option, default=None):
     return path
 
 
-def _set_test_data_dir():
+def _get_test_data_dir():
     """Return the test data directory and overriding if approproiate."""
     override = os.environ.get("OVERRIDE_TEST_DATA_REPOSITORY")
 
@@ -157,7 +157,7 @@ def _set_test_data_dir():
 # Resource options
 _RESOURCE_SECTION = "Resources"
 
-TEST_DATA_DIR = _set_test_data_dir()
+TEST_DATA_DIR = _get_test_data_dir()
 """Local directory where test data exists.
    Defaults to "test_data" sub-directory of the Iris package install directory.
    The test data directory supports the subset of Iris unit tests that require data.