PR #17953: [keras/utils] Standardise docstring usage of "Default to"

Imported from GitHub PR #17953

This is one of many PRs. Discussion + request to split into multiple PRs @ #17748
Copybara import of the project:

--
6893bd5 by Samuel Marks <[email protected]>:

[keras/utils/audio_dataset.py,keras/utils/conv_utils.py,keras/utils/data_utils.py,keras/utils/dataset_utils.py,keras/utils/feature_space.py,keras/utils/generic_utils.py,keras/utils/image_dataset.py,keras/utils/image_utils.py,keras/utils/layer_utils.py,keras/utils/losses_utils.py,keras/utils/metrics_utils.py,keras/utils/text_dataset.py] Standardise docstring usage of "Default to"

Merging this change closes #17953

FUTURE_COPYBARA_INTEGRATE_REVIEW=#17953 from SamuelMarks:keras.utils-defaults-to 4cbcdf8
PiperOrigin-RevId: 535277920

Author: SamuelMarks

keras/utils/conv_utils.py

@@ -63,8 +63,8 @@ def normalize_tuple(value, n, name, allow_zero=False):
       n: The size of the tuple to be returned.
       name: The name of the argument being validated, e.g. "strides" or
         "kernel_size". This is only used to format error messages.
-      allow_zero: Default to False. A ValueError will raised if zero is received
-        and this param is False.
+      allow_zero: A ValueError will be raised if zero is received
+        and this param is False. Defaults to `False`.
 
     Returns:
       A tuple of n integers.

keras/utils/data_utils.py

@@ -247,7 +247,7 @@ def get_file(
             The default `'auto'` corresponds to `['tar', 'zip']`.
             None or an empty list will return no matches found.
         cache_dir: Location to store cached files, when None it
-            defaults to the default directory `~/.keras/`.
+            defaults to `~/.keras/`.
 
     Returns:
         Path to the downloaded file.
@@ -1063,14 +1063,16 @@ def pad_sequences(
         maxlen: Optional Int, maximum length of all sequences. If not provided,
             sequences will be padded to the length of the longest individual
             sequence.
-        dtype: (Optional, defaults to `"int32"`). Type of the output sequences.
+        dtype: (Optional). Type of the output sequences.
             To pad sequences with variable length strings, you can use `object`.
-        padding: String, "pre" or "post" (optional, defaults to `"pre"`):
-            pad either before or after each sequence.
-        truncating: String, "pre" or "post" (optional, defaults to `"pre"`):
+            Defaults to `"int32"`.
+        padding: String, "pre" or "post" (optional):
+            pad either before or after each sequence. Defaults to `"pre"`.
+        truncating: String, "pre" or "post" (optional):
             remove values from sequences larger than
             `maxlen`, either at the beginning or at the end of the sequences.
-        value: Float or String, padding value. (Optional, defaults to 0.)
+            Defaults to `"pre"`.
+        value: Float or String, padding value. (Optional). Defaults to `0.`.
 
     Returns:
         Numpy array with shape `(len(sequences), maxlen)`

keras/utils/generic_utils.py

@@ -187,7 +187,7 @@ def update(self, current, values=None, finalize=None):
               as-is. Else, an average of the metric over time will be
               displayed.
             finalize: Whether this is the last update for the progress bar. If
-              `None`, defaults to `current >= self.target`.
+              `None`, uses `current >= self.target`. Defaults to `None`.
         """
         if finalize is None:
             if self.target is None:

keras/utils/image_dataset.py

@@ -100,13 +100,13 @@ def image_dataset_from_directory(
         color_mode: One of `"grayscale"`, `"rgb"`, `"rgba"`.
             Defaults to `"rgb"`. Whether the images will be converted to
             have 1, 3, or 4 channels.
-        batch_size: Size of the batches of data. Defaults to 32.
+        batch_size: Size of the batches of data.
             If `None`, the data will not be batched
-            (the dataset will yield individual samples).
+            (the dataset will yield individual samples). Defaults to 32.
         image_size: Size to resize images to after they are read from disk,
-            specified as `(height, width)`. Defaults to `(256, 256)`.
+            specified as `(height, width)`.
             Since the pipeline processes batches of images that must all have
-            the same size, this must be provided.
+            the same size, this must be provided. Defaults to `(256, 256)`.
         shuffle: Whether to shuffle the data. Defaults to `True`.
             If set to `False`, sorts the data in alphanumeric order.
         seed: Optional random seed for shuffling and transformations.

keras/utils/image_utils.py

@@ -120,9 +120,9 @@ def smart_resize(x, size, interpolation="bilinear"):
         format `(height, width, channels)` or `(batch_size, height, width,
         channels)`.
       size: Tuple of `(height, width)` integer. Target size.
-      interpolation: String, interpolation to use for resizing. Defaults to
-        `'bilinear'`. Supports `bilinear`, `nearest`, `bicubic`, `area`,
-        `lanczos3`, `lanczos5`, `gaussian`, `mitchellcubic`.
+      interpolation: String, interpolation to use for resizing. Supports
+        `bilinear`, `nearest`, `bicubic`, `area`, `lanczos3`, `lanczos5`,
+        `gaussian`, `mitchellcubic`. Defaults to `'bilinear'`.
 
     Returns:
       Array with shape `(size[0], size[1], channels)`. If the input image was a
@@ -216,14 +216,14 @@ def array_to_img(x, data_format=None, scale=True, dtype=None):
     Args:
         x: Input data, in any form that can be converted to a Numpy array.
         data_format: Image data format, can be either `"channels_first"` or
-          `"channels_last"`. Defaults to `None`, in which case the global
+          `"channels_last"`. None means the global
           setting `tf.keras.backend.image_data_format()` is used (unless you
-          changed it, it defaults to `"channels_last"`).
+          changed it, it uses `"channels_last"`). Defaults to `None`.
         scale: Whether to rescale the image such that minimum and maximum values
           are 0 and 255 respectively. Defaults to `True`.
-        dtype: Dtype to use. Default to `None`, in which case the global setting
-          `tf.keras.backend.floatx()` is used (unless you changed it, it
-          defaults to `"float32"`)
+        dtype: Dtype to use. None makes the global setting
+          `tf.keras.backend.floatx()` to be used (unless you changed it, it
+          uses `"float32"`). Defaults to `None`.
 
     Returns:
         A PIL Image instance.
@@ -298,12 +298,12 @@ def img_to_array(img, data_format=None, dtype=None):
     Args:
         img: Input PIL Image instance.
         data_format: Image data format, can be either `"channels_first"` or
-          `"channels_last"`. Defaults to `None`, in which case the global
+          `"channels_last"`. None means the global
           setting `tf.keras.backend.image_data_format()` is used (unless you
-          changed it, it defaults to `"channels_last"`).
-        dtype: Dtype to use. Default to `None`, in which case the global setting
-          `tf.keras.backend.floatx()` is used (unless you changed it, it
-          defaults to `"float32"`).
+          changed it, it uses `"channels_last"`). Defaults to `None`.
+        dtype: Dtype to use. None makes the global setting
+          `tf.keras.backend.floatx()` to be used (unless you changed it, it
+          uses `"float32"`). Defaults to `None`.
 
     Returns:
         A 3D Numpy array.

keras/utils/layer_utils.py

@@ -335,11 +335,12 @@ def print_summary(
             It will be called on each line of the summary.
             You can set it to a custom function
             in order to capture the string summary.
-            It defaults to `print` (prints to stdout).
+            When `None`, uses `print` (prints to stdout).
+            Defaults to `None`.
         expand_nested: Whether to expand the nested models.
-            If not provided, defaults to `False`.
+            Defaults to `False`.
         show_trainable: Whether to show if a layer is trainable.
-            If not provided, defaults to `False`.
+            Defaults to `False`.
         layer_range: List or tuple containing two strings,
             the starting layer name and ending layer name (both inclusive),
             indicating the range of layers to be printed in the summary. The
@@ -1042,9 +1043,9 @@ def warmstart_embedding_matrix(
           embedding matrix.
         new_embeddings_initializer: Initializer for embedding vectors for
           previously unseen terms to be added to the new embedding matrix (see
-          `keras.initializers`). Defaults to "uniform". new_embedding matrix
+          `keras.initializers`). new_embedding matrix
           needs to be specified with "constant" initializer.
-          matrix. Default value is None.
+          matrix. None means "uniform". Default value is None.
 
     Returns:
       tf.tensor of remapped embedding layer matrix

keras/utils/losses_utils.py

@@ -32,11 +32,11 @@ class ReductionV2:
     Contains the following values:
 
     * `AUTO`: Indicates that the reduction option will be determined by the
-      usage context. For almost all cases this defaults to
-      `SUM_OVER_BATCH_SIZE`. When used with `tf.distribute.Strategy`, outside of
-      built-in training loops such as `tf.keras` `compile` and `fit`, we expect
-      reduction value to be `SUM` or `NONE`. Using `AUTO` in that case will
-      raise an error.
+      usage context. For almost all cases this uses `SUM_OVER_BATCH_SIZE`.
+      When used with `tf.distribute.Strategy`, outside of built-in training
+      loops such as `tf.keras` `compile` and `fit`, we expect reduction
+      value to be `SUM` or `NONE`. Using `AUTO` in that case will raise an
+      error.
     * `NONE`: No **additional** reduction is applied to the output of the
       wrapped loss function. When non-scalar losses are returned to Keras
       functions like `fit`/`evaluate`, the unreduced vector loss is passed to

keras/utils/metrics_utils.py

@@ -979,7 +979,7 @@ def sparse_top_k_categorical_matches(y_true, y_pred, k=5):
       y_true: tensor of true targets.
       y_pred: tensor of predicted targets.
       k: (Optional) Number of top elements to look at for computing accuracy.
-        Defaults to 5.
+        Defaults to `5`.
 
     Returns:
       Match tensor: 1.0 for label-prediction match, 0.0 for mismatch.