diff --git a/cfdm/constructs.py b/cfdm/constructs.py index 13686b53f3..fe0330b8bb 100644 --- a/cfdm/constructs.py +++ b/cfdm/constructs.py @@ -959,8 +959,8 @@ def copy(self, data=True): :Parameters: data: `bool`, optional - If False then do not copy data contained in the metadata - constructs. By default such data are copied. + If True (the default) then copy data contained in the + metadata constructs. :Returns: diff --git a/cfdm/core/abstract/propertiesdata.py b/cfdm/core/abstract/propertiesdata.py index 0e9c2dcfd7..d182df6104 100644 --- a/cfdm/core/abstract/propertiesdata.py +++ b/cfdm/core/abstract/propertiesdata.py @@ -167,8 +167,8 @@ def copy(self, data=True): :Parameters: data: `bool`, optional - If False then do not copy data. By default data are - copied. + If True (the default) then copy data, else the + data is not copied. :Returns: @@ -397,8 +397,8 @@ def set_data(self, data, copy=True, inplace=True): {{data_like}} copy: `bool`, optional - If False then do not copy the data prior to insertion. By - default the data are copied. + If True (the default) then copy the data prior to + insertion, else the data is not copied. {{inplace: `bool`, optional (default True)}} diff --git a/cfdm/core/abstract/propertiesdatabounds.py b/cfdm/core/abstract/propertiesdatabounds.py index 664aedb5bb..d8ec9cab5d 100644 --- a/cfdm/core/abstract/propertiesdatabounds.py +++ b/cfdm/core/abstract/propertiesdatabounds.py @@ -606,8 +606,8 @@ def set_bounds(self, bounds, copy=True): The bounds to be inserted. copy: `bool`, optional - If False then do not copy the bounds prior to - insertion. By default the bounds are copied. + If True (the default) then copy the bounds prior to + insertion, else the bounds are not copied. :Returns: @@ -701,8 +701,8 @@ def set_interior_ring(self, interior_ring, copy=True): The interior_ring to be inserted. copy: `bool`, optional - If False then do not copy the interior_ring prior to - insertion. By default the interior_ring are copied. + If True (the default) then copy the interior_ring + prior to insertion, else it is not copied. :Returns: diff --git a/cfdm/core/constructs.py b/cfdm/core/constructs.py index 8c0dbc0e4d..71d8ac9df6 100644 --- a/cfdm/core/constructs.py +++ b/cfdm/core/constructs.py @@ -102,9 +102,9 @@ def __init__( constructs from those of *source*. copy: `bool`, optional - If False then do not deep copy metadata constructs - from those of *source* prior to initialisation. By - default such metadata constructs are deep copied. + If True (the default) then deep copy metadata constructs + from those of *source* prior to initialisation, else they + are not deep copied. _ignore: sequence of `str`, optional Ignores the given construct types. @@ -979,9 +979,7 @@ def copy(self, data=True): :Parameters: - data: `bool`, optional - If False then do not copy data contained in the - metadata constructs. By default such data are copied. + {{data: `bool`, optional}} :Returns: diff --git a/cfdm/core/coordinatereference.py b/cfdm/core/coordinatereference.py index dd6aac4bd6..24ce6c60fe 100644 --- a/cfdm/core/coordinatereference.py +++ b/cfdm/core/coordinatereference.py @@ -618,10 +618,7 @@ def set_coordinate_conversion(self, coordinate_conversion, copy=True): coordinate_conversion: `CoordinateConversion` The coordinate conversion component to be inserted. - copy: `bool`, optional - If False then do not copy the coordinate conversion prior - to insertion. By default the coordinate conversion is - copied. + {{copy: `bool`, optional}} :Returns: @@ -665,9 +662,7 @@ def set_datum(self, datum, copy=True): datum: `Datum` The datum component to be inserted. - copy: `bool`, optional - If False then do not copy the datum prior to insertion. By - default the datum is copied. + {{copy: `bool`, optional}} :Returns: diff --git a/cfdm/core/data/data.py b/cfdm/core/data/data.py index a8637409d3..82b18e6e70 100644 --- a/cfdm/core/data/data.py +++ b/cfdm/core/data/data.py @@ -305,8 +305,8 @@ def copy(self, array=True): :Parameters: array: `bool`, optional - If False then do not copy the array. By default the array - is copied. + If True (the default) then copy the array, else the + array is not copied. :Returns: diff --git a/cfdm/core/dimensioncoordinate.py b/cfdm/core/dimensioncoordinate.py index 24905006fd..536c96890e 100644 --- a/cfdm/core/dimensioncoordinate.py +++ b/cfdm/core/dimensioncoordinate.py @@ -73,9 +73,7 @@ def set_data(self, data, copy=True, inplace=True): {{data_like}} - copy: `bool`, optional - If False then do not copy the data prior to insertion. By - default the data are copied. + {{data copy: `bool`, optional}} {{inplace: `bool`, optional (default True)}} diff --git a/cfdm/core/docstring/docstring.py b/cfdm/core/docstring/docstring.py index c7f81f1271..ea339cf8d9 100644 --- a/cfdm/core/docstring/docstring.py +++ b/cfdm/core/docstring/docstring.py @@ -58,10 +58,9 @@ raised instead.""", # inplace: `bool`, optional (default True) "{{inplace: `bool`, optional (default True)}}": """inplace: `bool`, optional: - If False then do not do the operation in-place and - return a new, modified `{{class}}` instance. By - default the operation is in-place and `None` is - returned.""", + If True (the default) then do the operation in-place and + return `None`. If False a new, modified `{{class}}` + instance is returned.""", # init properties "{{init properties: `dict`, optional}}": """properties: `dict`, optional Set descriptive properties. The dictionary keys are @@ -105,8 +104,8 @@ initialisation with the `set_interior_ring` method.""", # init copy "{{init copy: `bool`, optional}}": """copy: `bool`, optional - If False then do not deep copy input parameters prior - to initialisation. By default arguments are deep + If True (the default) deep copy input parameters prior + to initialisation. If False arguments are not deep copied.""", # init source "{{init source}}": """Note that if *source* is a `{{class}}` instance then @@ -117,4 +116,16 @@ to a `Data` object, i.e. `numpy` array_like objects, `Data` objects, and {{package}} instances that contain `Data` objects.""", + # data: `bool`, optional + "{{data: `bool`, optional}}": """data: `bool`, optional + If True (the default) then copy data contained in the + metadata construct(s), else the data is not copied.""", + # (component-based) copy: `bool`, optional + "{{copy: `bool`, optional}}": """copy: `bool`, optional + If True (the default) then copy the component prior to + insertion, else it is not copied.""", + # data copy: `bool`, optional + "{{data copy: `bool`, optional}}": """copy: `bool`, optional + If True (the default) then copy the data prior to + insertion, else the data is not copied.""", } diff --git a/cfdm/core/domain.py b/cfdm/core/domain.py index ba8758d24a..77711e7114 100644 --- a/cfdm/core/domain.py +++ b/cfdm/core/domain.py @@ -145,9 +145,7 @@ def copy(self, data=True): :Parameters: - data: `bool`, optional - If False then do not copy data. By default data are - copied. + {{data: `bool`, optional}} :Returns: diff --git a/cfdm/core/field.py b/cfdm/core/field.py index a8e3dcac35..c686bddce3 100644 --- a/cfdm/core/field.py +++ b/cfdm/core/field.py @@ -488,9 +488,7 @@ def set_data(self, data, axes=None, copy=True, inplace=True): *Parameter example:* ``axes=None`` - copy: `bool`, optional - If False then do not copy the data prior to insertion. By - default the data are copied. + {{data copy: `bool`, optional}} {{inplace: `bool`, optional (default True)}} diff --git a/cfdm/core/functions.py b/cfdm/core/functions.py index 21b8bee7fb..23a0a9fa7a 100644 --- a/cfdm/core/functions.py +++ b/cfdm/core/functions.py @@ -17,11 +17,13 @@ def environment(display=True, paths=True): :Parameters: display: `bool`, optional - If False then return the description of the environment as - a string. By default the description is printed. + If True (the default) then display the description of the + environment as a string. If False the description is + instead returned as a list. paths: `bool`, optional - If False then do not output the locations of each package. + If True (the default) then output the locations of each + package. If False the locations are not included. :Returns: diff --git a/cfdm/data/abstract/raggedarray.py b/cfdm/data/abstract/raggedarray.py index 4a895a8aea..9ab3ffedc1 100644 --- a/cfdm/data/abstract/raggedarray.py +++ b/cfdm/data/abstract/raggedarray.py @@ -83,10 +83,7 @@ def __init__( {{init source}} - copy: `bool`, optional - If False then do not deep copy input parameters prior - to initialisation. By default arguments are deep - copied. + {{deep copy}} """ if count_variable is not None: diff --git a/cfdm/data/data.py b/cfdm/data/data.py index abdccce980..a486508435 100644 --- a/cfdm/data/data.py +++ b/cfdm/data/data.py @@ -130,10 +130,7 @@ def __init__( {{init source}} - copy: `bool`, optional - If False then do not deep copy input parameters prior - to initialisation. By default arguments are deep - copied. + {{deep copy}} kwargs: ignored Not used. Present to facilitate subclassing. @@ -1274,8 +1271,8 @@ def copy(self, array=True): :Parameters: array: `bool`, optional - If False then do not copy the array. By default the array - is copied. + If True (the default) then copy the array, else it + is not copied. :Returns: diff --git a/cfdm/data/gatheredarray.py b/cfdm/data/gatheredarray.py index 6ed039245d..0260941710 100644 --- a/cfdm/data/gatheredarray.py +++ b/cfdm/data/gatheredarray.py @@ -90,10 +90,7 @@ def __init__( .. versionadded:: (cfdm) 1.9.TODO.0 - copy: `bool`, optional - If False then do not deep copy input parameters prior - to initialisation. By default arguments are deep - copied. + {{deep copy}} .. versionadded:: (cfdm) 1.9.TODO.0 diff --git a/cfdm/data/netcdfarray.py b/cfdm/data/netcdfarray.py index 563c7607e8..877e3fcbda 100644 --- a/cfdm/data/netcdfarray.py +++ b/cfdm/data/netcdfarray.py @@ -80,8 +80,8 @@ def __init__( The number of array dimensions in the netCDF file. mask: `bool` - If False then do not mask by convention when reading data - from disk. By default data is masked by convention. + If True (the default) then mask by convention when + reading data from disk. A netCDF array is masked depending on the values of any of the netCDF variable attributes ``valid_min``, @@ -97,10 +97,7 @@ def __init__( .. versionadded:: (cfdm) 1.9.TODO.0 - copy: `bool`, optional - If False then do not deep copy input parameters prior - to initialisation. By default arguments are deep - copied. + {{deep copy}} .. versionadded:: (cfdm) 1.9.TODO.0 diff --git a/cfdm/data/raggedcontiguousarray.py b/cfdm/data/raggedcontiguousarray.py index 9744851ffc..db7059b114 100644 --- a/cfdm/data/raggedcontiguousarray.py +++ b/cfdm/data/raggedcontiguousarray.py @@ -56,10 +56,7 @@ def __init__( .. versionadded:: (cfdm) 1.9.TODO.0 - copy: `bool`, optional - If False then do not deep copy input parameters prior - to initialisation. By default arguments are deep - copied. + {{deep copy}} .. versionadded:: (cfdm) 1.9.TODO.0 diff --git a/cfdm/data/raggedindexedarray.py b/cfdm/data/raggedindexedarray.py index d416e21d66..b469cc134f 100644 --- a/cfdm/data/raggedindexedarray.py +++ b/cfdm/data/raggedindexedarray.py @@ -57,10 +57,7 @@ def __init__( .. versionadded:: (cfdm) 1.9.TODO.0 - copy: `bool`, optional - If False then do not deep copy input parameters prior - to initialisation. By default arguments are deep - copied. + {{deep copy}} .. versionadded:: (cfdm) 1.9.TODO.0 diff --git a/cfdm/data/raggedindexedcontiguousarray.py b/cfdm/data/raggedindexedcontiguousarray.py index 1d3bbc3d9c..6bc2dcce4d 100644 --- a/cfdm/data/raggedindexedcontiguousarray.py +++ b/cfdm/data/raggedindexedcontiguousarray.py @@ -65,10 +65,7 @@ def __init__( .. versionadded:: (cfdm) 1.9.TODO.0 - copy: `bool`, optional - If False then do not deep copy input parameters prior - to initialisation. By default arguments are deep - copied. + {{deep copy}} .. versionadded:: (cfdm) 1.9.TODO.0 diff --git a/cfdm/data/subarray/abstract/subarray.py b/cfdm/data/subarray/abstract/subarray.py index 18d63a592b..c09806c6ef 100644 --- a/cfdm/data/subarray/abstract/subarray.py +++ b/cfdm/data/subarray/abstract/subarray.py @@ -66,10 +66,7 @@ def __init__( {{init source}} - copy: `bool`, optional - If False then do not deep copy input parameters prior - to initialisation. By default arguments are deep - copied. + {{deep copy}} context_manager: function, optional A context manager that provides a runtime context for diff --git a/cfdm/data/subarray/abstract/subsampledsubarray.py b/cfdm/data/subarray/abstract/subsampledsubarray.py index 76df39ad2e..1bfe8aa385 100644 --- a/cfdm/data/subarray/abstract/subsampledsubarray.py +++ b/cfdm/data/subarray/abstract/subsampledsubarray.py @@ -109,10 +109,7 @@ def __init__( {{init source}} - copy: `bool`, optional - If False then do not deep copy input parameters prior - to initialisation. By default arguments are deep - copied. + {{deep copy}} context_manager: function, optional A context manager that provides a runtime context for diff --git a/cfdm/data/subarray/gatheredsubarray.py b/cfdm/data/subarray/gatheredsubarray.py index c6138e3261..9dd5ebc899 100644 --- a/cfdm/data/subarray/gatheredsubarray.py +++ b/cfdm/data/subarray/gatheredsubarray.py @@ -67,10 +67,7 @@ def __init__( {{init source}} - copy: `bool`, optional - If False then do not deep copy input parameters prior - to initialisation. By default arguments are deep - copied. + {{deep copy}} context_manager: function, optional A context manager that provides a runtime context for diff --git a/cfdm/data/subsampledarray.py b/cfdm/data/subsampledarray.py index 3dfaf9d239..11ca6e73f6 100644 --- a/cfdm/data/subsampledarray.py +++ b/cfdm/data/subsampledarray.py @@ -249,10 +249,7 @@ def __init__( {{init source}} - copy: `bool`, optional - If False then do not deep copy input parameters prior - to initialisation. By default arguments are deep - copied. + {{deep copy}} """ super().__init__( diff --git a/cfdm/docstring/docstring.py b/cfdm/docstring/docstring.py index 154657adc1..125251c0c7 100644 --- a/cfdm/docstring/docstring.py +++ b/cfdm/docstring/docstring.py @@ -112,8 +112,8 @@ ``name='data1'``""", # header: `bool`, optional "{{header: `bool`, optional}}": """header: `bool`, optional - If False then do not output a comment describing the - components.""", + If True (the default) output a comment describing the + components. If False no such comment is returned.""", # ignore_compression: `bool`, optional "{{ignore_compression: `bool`, optional}}": """ignore_compression: `bool`, optional If False then the compression type and, if applicable, @@ -345,6 +345,11 @@ By default, *chunks* is ``-1``, meaning that all non-compressed dimensions in each subarray have the maximum possible size.""", + # deep copy + "{{deep copy}}": """copy: `bool`, optional + If True (the default) then deep copy input + parameters prior to initialisation, else they are + not (deep) copied.""", # ---------------------------------------------------------------- # Method description susbstitutions (4 levels of indentataion) # ---------------------------------------------------------------- diff --git a/cfdm/functions.py b/cfdm/functions.py index a3f2bc76f0..6a4b377cc0 100644 --- a/cfdm/functions.py +++ b/cfdm/functions.py @@ -303,7 +303,8 @@ def environment(display=True, paths=True): a string. By default the description is printed. paths: `bool`, optional - If False then do not output the locations of each package. + If True (the default) then output the locations of each + package. :Returns: @@ -440,8 +441,8 @@ def unique_constructs(constructs, copy=True): a mixture of types. The sequence can be empty. copy: `bool`, optional - If False then do not copy returned constructs. By default - they are deep copies. + If True (the default) then deep copy returned constructs, + else they are not (deep) copied. :Returns: diff --git a/cfdm/mixin/propertiesdatabounds.py b/cfdm/mixin/propertiesdatabounds.py index 205d9dc14c..5855d050b0 100644 --- a/cfdm/mixin/propertiesdatabounds.py +++ b/cfdm/mixin/propertiesdatabounds.py @@ -95,10 +95,7 @@ def __init__( {{init source}} - copy: `bool`, optional - If False then do not deep copy input parameters prior - to initialisation. By default arguments are deep - copied. + {{deep copy}} """ # Initialise properties, data, geometry and interior ring @@ -1553,8 +1550,8 @@ def set_node_count(self, node_count, copy=True): The node count variable to be inserted. copy: `bool`, optional - If False then do not copy the node count variable - prior to insertion. By default it is copied. + If True (the default) then copy the node count + variable prior to insertion. :Returns: @@ -1593,8 +1590,8 @@ def set_part_node_count(self, part_node_count, copy=True): The part node count variable to be inserted. copy: `bool`, optional - If False then do not copy the part node count variable - prior to insertion. By default it is copied. + If True (the default) then copy the part node count + variable prior to insertion. :Returns: diff --git a/cfdm/read_write/netcdf/netcdfread.py b/cfdm/read_write/netcdf/netcdfread.py index e07b88dfdc..129cff7daa 100644 --- a/cfdm/read_write/netcdf/netcdfread.py +++ b/cfdm/read_write/netcdf/netcdfread.py @@ -372,8 +372,8 @@ def file_open(self, filename, flatten=True, verbose=None): `netCDF.Dataset` instance. flatten: `bool`, optional - If False then do not flatten a grouped file. Ignored if - the file has no groups. + If True (the default) then flatten a grouped file. + Ignored if the file has no groups. .. versionadded:: (cfdm) 1.8.6 diff --git a/cfdm/read_write/netcdf/netcdfwrite.py b/cfdm/read_write/netcdf/netcdfwrite.py index db41258c9a..1ebd4130d8 100644 --- a/cfdm/read_write/netcdf/netcdfwrite.py +++ b/cfdm/read_write/netcdf/netcdfwrite.py @@ -4519,13 +4519,22 @@ def write( .. versionadded:: (cfdm) 1.8.0 warn_valid: `bool`, optional - If False then do not print a warning when writing + If True (the default) then print a warning when writing "out-of-range" data, as indicated by the values, if present, of any of the ``valid_min``, ``valid_max`` or ``valid_range`` properties on field and metadata - constructs that have data. + constructs that have data. If False the warning + is not printed. - See `cfdm.write` for details. + The consequence of writing out-of-range data values is + that, by default, these values will be masked when the + file is subsequently read. + + *Parameter example:* + If a construct has ``valid_max`` property with value + ``100`` and data with maximum value ``999``, then the + resulting warning may be suppressed by setting + ``warn_valid=False``. .. versionadded:: (cfdm) 1.8.3 diff --git a/cfdm/read_write/read.py b/cfdm/read_write/read.py index 6979b1a3c0..4d8ec83115 100644 --- a/cfdm/read_write/read.py +++ b/cfdm/read_write/read.py @@ -227,9 +227,8 @@ def read( .. versionadded:: (cfdm) 1.8.3 mask: `bool`, optional - If False then do not mask by convention the data of field - and metadata constructs. By default all data is masked by - convention. + If True (the default) then mask by convention the data of + field and metadata constructs. The masking by convention of a netCDF array depends on the values of any of the netCDF variable attributes diff --git a/cfdm/read_write/write.py b/cfdm/read_write/write.py index 63f0601bbd..b54aacb7d2 100644 --- a/cfdm/read_write/write.py +++ b/cfdm/read_write/write.py @@ -457,13 +457,12 @@ def write( and attributes. warn_valid: `bool`, optional - If False then do not print a warning when writing + If True (the default) then print a warning when writing "out-of-range" data, as indicated by the values, if present, of any of the ``valid_min``, ``valid_max`` or ``valid_range`` properties on field and metadata - constructs that have data. By default a warning is printed - if any such construct has any of these properties in - combination with out-of-range data. + constructs that have data. If False the warning + is not printed. The consequence of writing out-of-range data values is that, by default, these values will be masked when the