wandb 0.21.0__py3-none-win32.whl → 0.21.1__py3-none-win32.whl

wandb/sdk/wandb_run.py

@@ -131,6 +131,7 @@ if TYPE_CHECKING:
         input_types: dict[str, Any]
         output_types: dict[str, Any]
         runtime: str | None
+        services: dict[str, str]
 
 
 logger = logging.getLogger("wandb")
@@ -474,62 +475,47 @@ class RunStatus:
 
 
 class Run:
-    """A unit of computation logged by wandb. Typically, this is an ML experiment.
+    """A unit of computation logged by W&B. Typically, this is an ML experiment.
 
-    Create a run with `wandb.init()`:
-    ```python
-    import wandb
+    Call [`wandb.init()`](https://docs.wandb.ai/ref/python/init/) to create a
+    new run. `wandb.init()` starts a new run and returns a `wandb.Run` object.
+    Each run is associated with a unique ID (run ID). W&B recommends using
+    a context (`with` statement) manager to automatically finish the run.
 
-    run = wandb.init()
-    ```
+    For distributed training experiments, you can either track each process
+    separately using one run per process or track all processes to a single run.
+    See [Log distributed training experiments](https://docs.wandb.ai/guides/track/log/distributed-training)
+    for more information.
 
-    There is only ever at most one active `wandb.Run` in any process,
-    and it is accessible as `wandb.run`:
-    ```python
-    import wandb
+    You can log data to a run with `wandb.Run.log()`. Anything you log using
+    `wandb.Run.log()` is sent to that run. See
+    [Create an experiment](https://docs.wandb.ai/guides/track/launch) or
+    [`wandb.init`](https://docs.wandb.ai/ref/python/init/) API reference page
+    or more information.
 
-    assert wandb.run is None
+    There is a another `Run` object in the
+    [`wandb.apis.public`](https://docs.wandb.ai/ref/python/public-api/api/)
+    namespace. Use this object is to interact with runs that have already been
+    created.
 
-    wandb.init()
+    Attributes:
+        summary: (Summary) A summary of the run, which is a dictionary-like
+            object. For more information, see
+            [Log summary metrics](https://docs.wandb.ai/guides/track/log/log-summary/).
 
-    assert wandb.run is not None
-    ```
-    anything you log with `wandb.log` will be sent to that run.
+    Examples:
+    Create a run with `wandb.init()`:
 
-    If you want to start more runs in the same script or notebook, you'll need to
-    finish the run that is in-flight. Runs can be finished with `wandb.finish` or
-    by using them in a `with` block:
     ```python
     import wandb
 
-    wandb.init()
-    wandb.finish()
-
-    assert wandb.run is None
-
-    with wandb.init() as run:
-        pass  # log data here
-
-    assert wandb.run is None
+    # Start a new run and log some data
+    # Use context manager (`with` statement) to automatically finish the run
+    with wandb.init(entity="entity", project="project") as run:
+        run.log({"accuracy": acc, "loss": loss})
     ```
 
-    See the documentation for `wandb.init` for more on creating runs, or check out
-    [our guide to `wandb.init`](https://docs.wandb.ai/guides/track/launch).
-
-    In distributed training, you can either create a single run in the rank 0 process
-    and then log information only from that process, or you can create a run in each process,
-    logging from each separately, and group the results together with the `group` argument
-    to `wandb.init`. For more details on distributed training with W&B, check out
-    [our guide](https://docs.wandb.ai/guides/track/log/distributed-training).
-
-    Currently, there is a parallel `Run` object in the `wandb.Api`. Eventually these
-    two objects will be merged.
-
-    Attributes:
-        summary: (Summary) Single values set for each `wandb.log()` key. By
-            default, summary is set to the last value logged. You can manually
-            set summary to the best value, like max accuracy, instead of the
-            final value.
+    <!-- lazydoc-ignore-init: internal -->
     """
 
     _telemetry_obj: telemetry.TelemetryRecord
@@ -850,6 +836,7 @@ class Run:
     @_log_to_run
     @_attach
     def config_static(self) -> wandb_config.ConfigStatic:
+        """Static config object associated with this run."""
         return wandb_config.ConfigStatic(self._config)
 
     @property
@@ -957,7 +944,10 @@ class Run:
     @_log_to_run
     @_attach
     def starting_step(self) -> int:
-        """The first step of the run."""
+        """The first step of the run.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         return self._starting_step
 
     @property
@@ -973,7 +963,9 @@ class Run:
     def step(self) -> int:
         """Current value of the step.
 
-        This counter is incremented by `wandb.log`.
+        This counter is incremented by `wandb.Run.log()`.
+
+        <!-- lazydoc-ignore: internal -->
         """
         return self._step
 
@@ -981,26 +973,30 @@ class Run:
     @_log_to_run
     @_attach
     def offline(self) -> bool:
+        """True if the run is offline, False otherwise."""
         return self._settings._offline
 
     @property
     @_log_to_run
     @_attach
     def disabled(self) -> bool:
+        """True if the run is disabled, False otherwise."""
         return self._settings._noop
 
     @property
     @_log_to_run
     @_attach
     def group(self) -> str:
-        """Name of the group associated with the run.
+        """Returns the name of the group associated with this run.
 
-        Setting a group helps the W&B UI organize runs in a sensible way.
+        Grouping runs together allows related experiments to be organized and
+        visualized collectively in the W&B UI. This is especially useful for
+        scenarios such as distributed training or cross-validation, where
+        multiple runs should be viewed and managed as a unified experiment.
 
-        If you are doing a distributed training you should give all of the
-            runs in the training the same group.
-        If you are doing cross-validation you should give all the cross-validation
-            folds the same group.
+        In shared mode, where all processes share the same run object,
+        setting a group is usually unnecessary, since there is only one
+        run and no grouping is required.
         """
         return self._settings.run_group or ""
 
@@ -1008,13 +1004,24 @@ class Run:
     @_log_to_run
     @_attach
     def job_type(self) -> str:
+        """Name of the job type associated with the run.
+
+        View a run's job type in the run's Overview page in the W&B App.
+
+        You can use this to categorize runs by their job type, such as
+        "training", "evaluation", or "inference". This is useful for organizing
+        and filtering runs in the W&B UI, especially when you have multiple
+        runs with different job types in the same project. For more
+        information, see [Organize runs](https://docs.wandb.ai/guides/runs/#organize-runs).
+        """
         return self._settings.run_job_type or ""
 
     def project_name(self) -> str:
-        """Name of the W&B project associated with the run.
+        """This method is deprecated and will be removed in a future release. Use `run.project` instead.
+
+        Name of the W&B project associated with the run.
 
-        Note: this method is deprecated and will be removed in a future release.
-        Please use `run.project` instead.
+        <!-- lazydoc-ignore: internal -->
         """
         deprecate.deprecate(
             field_name=Deprecated.run__project_name,
@@ -1035,12 +1042,12 @@ class Run:
 
     @_log_to_run
     def get_project_url(self) -> str | None:
-        """URL of the W&B project associated with the run, if there is one.
+        """This method is deprecated and will be removed in a future release. Use `run.project_url` instead.
 
+        URL of the W&B project associated with the run, if there is one.
         Offline runs do not have a project URL.
 
-        Note: this method is deprecated and will be removed in a future release.
-        Please use `run.project_url` instead.
+        <!-- lazydoc-ignore: internal -->
         """
         deprecate.deprecate(
             field_name=Deprecated.run__get_project_url,
@@ -1087,28 +1094,36 @@ class Run:
                 many runs to share the same artifact. Specifying name allows you to achieve that.
             include_fn: A callable that accepts a file path and (optionally) root path and
                 returns True when it should be included and False otherwise. This
-                defaults to: `lambda path, root: path.endswith(".py")`
+                defaults to `lambda path, root: path.endswith(".py")`.
             exclude_fn: A callable that accepts a file path and (optionally) root path and
                 returns `True` when it should be excluded and `False` otherwise. This
                 defaults to a function that excludes all files within `<root>/.wandb/`
                 and `<root>/wandb/` directories.
 
         Examples:
-            Basic usage
-            ```python
+        Basic usage
+
+        ```python
+        import wandb
+
+        with wandb.init() as run:
             run.log_code()
-            ```
+        ```
 
-            Advanced usage
-            ```python
+        Advanced usage
+
+        ```python
+        import wandb
+
+        with wandb.init() as run:
             run.log_code(
-                "../",
+                root="../",
                 include_fn=lambda path: path.endswith(".py") or path.endswith(".ipynb"),
                 exclude_fn=lambda path, root: os.path.relpath(path, root).startswith(
                     "cache/"
                 ),
             )
-            ```
+        ```
 
         Returns:
             An `Artifact` object if code was logged
@@ -1161,12 +1176,12 @@ class Run:
 
     @_log_to_run
     def get_sweep_url(self) -> str | None:
-        """The URL of the sweep associated with the run, if there is one.
+        """This method is deprecated and will be removed in a future release. Use `run.sweep_url` instead.
 
+        The URL of the sweep associated with the run, if there is one.
         Offline runs do not have a sweep URL.
 
-        Note: this method is deprecated and will be removed in a future release.
-        Please use `run.sweep_url` instead.
+        <!-- lazydoc-ignore: internal -->
         """
         deprecate.deprecate(
             field_name=Deprecated.run__get_sweep_url,
@@ -1191,12 +1206,11 @@ class Run:
 
     @_log_to_run
     def get_url(self) -> str | None:
-        """URL of the W&B run, if there is one.
+        """This method is deprecated and will be removed in a future release. Use `run.url` instead.
 
-        Offline runs do not have a URL.
+        URL of the W&B run, if there is one. Offline runs do not have a URL.
 
-        Note: this method is deprecated and will be removed in a future release.
-        Please use `run.url` instead.
+        <!-- lazydoc-ignore: internal -->
         """
         deprecate.deprecate(
             field_name=Deprecated.run__get_url,
@@ -1319,7 +1333,7 @@ class Run:
     @_log_to_run
     @_attach
     def display(self, height: int = 420, hidden: bool = False) -> bool:
-        """Display this run in jupyter."""
+        """Display this run in Jupyter."""
         if self._settings.silent:
             return False
 
@@ -1338,7 +1352,10 @@ class Run:
     @_log_to_run
     @_attach
     def to_html(self, height: int = 420, hidden: bool = False) -> str:
-        """Generate HTML containing an iframe displaying the current run."""
+        """Generate HTML containing an iframe displaying the current run.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         url = self._settings.run_url + "?jupyter=true"
         style = f"border:none;width:100%;height:{height}px;"
         prefix = ""
@@ -1489,7 +1506,7 @@ class Run:
     ) -> dict[str, Any]:
         """Process and replace chart objects with their underlying table values.
 
-        This processes the chart objects passed to `run.log()`, replacing their entries
+        This processes the chart objects passed to `wandb.Run.log()`, replacing their entries
         in the given dictionary (which is saved to the run's history) and adding them
         to the run's config.
 
@@ -1745,91 +1762,94 @@ class Run:
         """Upload run data.
 
         Use `log` to log data from runs, such as scalars, images, video,
-        histograms, plots, and tables.
+        histograms, plots, and tables. See [Log objects and media](https://docs.wandb.ai/guides/track/log) for
+        code snippets, best practices, and more.
 
-        See our [guides to logging](https://docs.wandb.ai/guides/track/log) for
-        live examples, code snippets, best practices, and more.
+        Basic usage:
 
-        The most basic usage is `run.log({"train-loss": 0.5, "accuracy": 0.9})`.
-        This will save the loss and accuracy to the run's history and update
-        the summary values for these metrics.
+        ```python
+        import wandb
 
-        Visualize logged data in the workspace at [wandb.ai](https://wandb.ai),
+        with wandb.init() as run:
+            run.log({"train-loss": 0.5, "accuracy": 0.9})
+        ```
+
+        The previous code snippet saves the loss and accuracy to the run's
+        history and updates the summary values for these metrics.
+
+        Visualize logged data in a workspace at [wandb.ai](https://wandb.ai),
         or locally on a [self-hosted instance](https://docs.wandb.ai/guides/hosting)
-        of the W&B app, or export data to visualize and explore locally, e.g. in
-        Jupyter notebooks, with [our API](https://docs.wandb.ai/guides/track/public-api-guide).
-
-        Logged values don't have to be scalars. Logging any wandb object is supported.
-        For example `run.log({"example": wandb.Image("myimage.jpg")})` will log an
-        example image which will be displayed nicely in the W&B UI.
-        See the [reference documentation](https://docs.wandb.com/ref/python/data-types)
-        for all of the different supported types or check out our
-        [guides to logging](https://docs.wandb.ai/guides/track/log) for examples,
-        from 3D molecular structures and segmentation masks to PR curves and histograms.
-        You can use `wandb.Table` to log structured data. See our
-        [guide to logging tables](https://docs.wandb.ai/guides/models/tables/tables-walkthrough)
-        for details.
-
-        The W&B UI organizes metrics with a forward slash (`/`) in their name
+        of the W&B app, or export data to visualize and explore locally, such as in a
+        Jupyter notebook, with the [Public API](https://docs.wandb.ai/guides/track/public-api-guide).
+
+        Logged values don't have to be scalars. You can log any
+        [W&B supported Data Type](https://docs.wandb.ai/ref/python/data-types/)
+        such as images, audio, video, and more. For example, you can use
+        `wandb.Table` to log structured data. See
+        [Log tables, visualize and query data](https://docs.wandb.ai/guides/models/tables/tables-walkthrough)
+        tutorial for more details.
+
+        W&B organizes metrics with a forward slash (`/`) in their name
         into sections named using the text before the final slash. For example,
         the following results in two sections named "train" and "validate":
 
-        ```
-        run.log(
-            {
-                "train/accuracy": 0.9,
-                "train/loss": 30,
-                "validate/accuracy": 0.8,
-                "validate/loss": 20,
-            }
-        )
+        ```python
+        with wandb.init() as run:
+            # Log metrics in the "train" section.
+            run.log(
+                {
+                    "train/accuracy": 0.9,
+                    "train/loss": 30,
+                    "validate/accuracy": 0.8,
+                    "validate/loss": 20,
+                }
+            )
         ```
 
         Only one level of nesting is supported; `run.log({"a/b/c": 1})`
         produces a section named "a/b".
 
-        `run.log` is not intended to be called more than a few times per second.
+        `run.log()` is not intended to be called more than a few times per second.
         For optimal performance, limit your logging to once every N iterations,
         or collect data over multiple iterations and log it in a single step.
 
-        ### The W&B step
-
-        With basic usage, each call to `log` creates a new "step".
+        By default, each call to `log` creates a new "step".
         The step must always increase, and it is not possible to log
-        to a previous step.
+        to a previous step. You can use any metric as the X axis in charts.
+        See [Custom log axes](https://docs.wandb.ai/guides/track/log/customize-logging-axes/)
+        for more details.
 
-        Note that you can use any metric as the X axis in charts.
         In many cases, it is better to treat the W&B step like
         you'd treat a timestamp rather than a training step.
 
+        ```python
+        with wandb.init() as run:
+            # Example: log an "epoch" metric for use as an X axis.
+            run.log({"epoch": 40, "train-loss": 0.5})
         ```
-        # Example: log an "epoch" metric for use as an X axis.
-        run.log({"epoch": 40, "train-loss": 0.5})
-        ```
-
-        See also [define_metric](https://docs.wandb.ai/ref/python/run#define_metric).
 
-        It is possible to use multiple `log` invocations to log to
+        It is possible to use multiple `wandb.Run.log()` invocations to log to
         the same step with the `step` and `commit` parameters.
         The following are all equivalent:
 
-        ```
-        # Normal usage:
-        run.log({"train-loss": 0.5, "accuracy": 0.8})
-        run.log({"train-loss": 0.4, "accuracy": 0.9})
-
-        # Implicit step without auto-incrementing:
-        run.log({"train-loss": 0.5}, commit=False)
-        run.log({"accuracy": 0.8})
-        run.log({"train-loss": 0.4}, commit=False)
-        run.log({"accuracy": 0.9})
-
-        # Explicit step:
-        run.log({"train-loss": 0.5}, step=current_step)
-        run.log({"accuracy": 0.8}, step=current_step)
-        current_step += 1
-        run.log({"train-loss": 0.4}, step=current_step)
-        run.log({"accuracy": 0.9}, step=current_step)
+        ```python
+        with wandb.init() as run:
+            # Normal usage:
+            run.log({"train-loss": 0.5, "accuracy": 0.8})
+            run.log({"train-loss": 0.4, "accuracy": 0.9})
+
+            # Implicit step without auto-incrementing:
+            run.log({"train-loss": 0.5}, commit=False)
+            run.log({"accuracy": 0.8})
+            run.log({"train-loss": 0.4}, commit=False)
+            run.log({"accuracy": 0.9})
+
+            # Explicit step:
+            run.log({"train-loss": 0.5}, step=current_step)
+            run.log({"accuracy": 0.8}, step=current_step)
+            current_step += 1
+            run.log({"train-loss": 0.4}, step=current_step)
+            run.log({"accuracy": 0.9}, step=current_step)
         ```
 
         Args:
@@ -1847,59 +1867,64 @@ class Run:
                 otherwise, the default is `commit=False`.
 
         Examples:
-            For more and more detailed examples, see
-            [our guides to logging](https://docs.wandb.com/guides/track/log).
+        For more and more detailed examples, see
+        [our guides to logging](https://docs.wandb.com/guides/track/log).
+
+        Basic usage
 
-            ### Basic usage
-            ```python
-            import wandb
+        ```python
+        import wandb
+
+        with wandb.init() as run:
+            run.log({"train-loss": 0.5, "accuracy": 0.9
+        ```
 
-            run = wandb.init()
-            run.log({"accuracy": 0.9, "epoch": 5})
-            ```
+        Incremental logging
 
-            ### Incremental logging
-            ```python
-            import wandb
+        ```python
+        import wandb
 
-            run = wandb.init()
+        with wandb.init() as run:
             run.log({"loss": 0.2}, commit=False)
             # Somewhere else when I'm ready to report this step:
             run.log({"accuracy": 0.8})
-            ```
+        ```
+
+        Histogram
 
-            ### Histogram
-            ```python
-            import numpy as np
-            import wandb
+        ```python
+        import numpy as np
+        import wandb
 
-            # sample gradients at random from normal distribution
-            gradients = np.random.randn(100, 100)
-            run = wandb.init()
+        # sample gradients at random from normal distribution
+        gradients = np.random.randn(100, 100)
+        with wandb.init() as run:
             run.log({"gradients": wandb.Histogram(gradients)})
-            ```
+        ```
 
-            ### Image from numpy
-            ```python
-            import numpy as np
-            import wandb
+        Image from NumPy
 
-            run = wandb.init()
+        ```python
+        import numpy as np
+        import wandb
+
+        with wandb.init() as run:
             examples = []
             for i in range(3):
                 pixels = np.random.randint(low=0, high=256, size=(100, 100, 3))
                 image = wandb.Image(pixels, caption=f"random field {i}")
                 examples.append(image)
             run.log({"examples": examples})
-            ```
+        ```
 
-            ### Image from PIL
-            ```python
-            import numpy as np
-            from PIL import Image as PILImage
-            import wandb
+        Image from PIL
 
-            run = wandb.init()
+        ```python
+        import numpy as np
+        from PIL import Image as PILImage
+        import wandb
+
+        with wandb.init() as run:
             examples = []
             for i in range(3):
                 pixels = np.random.randint(
@@ -1912,14 +1937,15 @@ class Run:
                 image = wandb.Image(pil_image, caption=f"random field {i}")
                 examples.append(image)
             run.log({"examples": examples})
-            ```
+        ```
+
+        Video from NumPy
 
-            ### Video from numpy
-            ```python
-            import numpy as np
-            import wandb
+        ```python
+        import numpy as np
+        import wandb
 
-            run = wandb.init()
+        with wandb.init() as run:
             # axes are (time, channel, height, width)
             frames = np.random.randint(
                 low=0,
@@ -1928,35 +1954,38 @@ class Run:
                 dtype=np.uint8,
             )
             run.log({"video": wandb.Video(frames, fps=4)})
-            ```
+        ```
+
+        Matplotlib plot
 
-            ### Matplotlib Plot
-            ```python
-            from matplotlib import pyplot as plt
-            import numpy as np
-            import wandb
+        ```python
+        from matplotlib import pyplot as plt
+        import numpy as np
+        import wandb
 
-            run = wandb.init()
+        with wandb.init() as run:
             fig, ax = plt.subplots()
             x = np.linspace(0, 10)
             y = x * x
             ax.plot(x, y)  # plot y = x^2
             run.log({"chart": fig})
-            ```
+        ```
+
+        PR Curve
 
-            ### PR Curve
-            ```python
-            import wandb
+        ```python
+        import wandb
 
-            run = wandb.init()
+        with wandb.init() as run:
             run.log({"pr": wandb.plot.pr_curve(y_test, y_probas, labels)})
-            ```
+        ```
 
-            ### 3D Object
-            ```python
-            import wandb
+        3D Object
 
-            run = wandb.init()
+        ```python
+        import wandb
+
+        with wandb.init() as run:
             run.log(
                 {
                     "generated_samples": [
@@ -1966,11 +1995,11 @@ class Run:
                     ]
                 }
             )
-            ```
+        ```
 
         Raises:
-            wandb.Error: if called before `wandb.init`
-            ValueError: if invalid data is passed
+            wandb.Error: If called before `wandb.init()`.
+            ValueError: If invalid data is passed.
 
         """
         if step is not None:
@@ -2005,42 +2034,48 @@ class Run:
 
         A `base_path` may be provided to control the directory structure of
         uploaded files. It should be a prefix of `glob_str`, and the directory
-        structure beneath it is preserved. It's best understood through
-        examples:
+        structure beneath it is preserved.
 
-        ```
-        wandb.save("these/are/myfiles/*")
-        # => Saves files in a "these/are/myfiles/" folder in the run.
-
-        wandb.save("these/are/myfiles/*", base_path="these")
-        # => Saves files in an "are/myfiles/" folder in the run.
-
-        wandb.save("/User/username/Documents/run123/*.txt")
-        # => Saves files in a "run123/" folder in the run. See note below.
-
-        wandb.save("/User/username/Documents/run123/*.txt", base_path="/User")
-        # => Saves files in a "username/Documents/run123/" folder in the run.
-
-        wandb.save("files/*/saveme.txt")
-        # => Saves each "saveme.txt" file in an appropriate subdirectory
-        #    of "files/".
-        ```
-
-        Note: when given an absolute path or glob and no `base_path`, one
+        When given an absolute path or glob and no `base_path`, one
         directory level is preserved as in the example above.
 
         Args:
             glob_str: A relative or absolute path or Unix glob.
             base_path: A path to use to infer a directory structure; see examples.
             policy: One of `live`, `now`, or `end`.
-                * live: upload the file as it changes, overwriting the previous version
-                * now: upload the file once now
-                * end: upload file when the run ends
+            - live: upload the file as it changes, overwriting the previous version
+            - now: upload the file once now
+            - end: upload file when the run ends
 
         Returns:
             Paths to the symlinks created for the matched files.
 
             For historical reasons, this may return a boolean in legacy code.
+
+        ```python
+        import wandb
+
+        run = wandb.init()
+
+        run.save("these/are/myfiles/*")
+        # => Saves files in a "these/are/myfiles/" folder in the run.
+
+        run.save("these/are/myfiles/*", base_path="these")
+        # => Saves files in an "are/myfiles/" folder in the run.
+
+        run.save("/User/username/Documents/run123/*.txt")
+        # => Saves files in a "run123/" folder in the run. See note below.
+
+        run.save("/User/username/Documents/run123/*.txt", base_path="/User")
+        # => Saves files in a "username/Documents/run123/" folder in the run.
+
+        run.save("files/*/saveme.txt")
+        # => Saves each "saveme.txt" file in an appropriate subdirectory
+        #    of "files/".
+
+        # Explicitly finish the run since a context manager is not used.
+        run.finish()
+        ```
         """
         if isinstance(glob_str, bytes):
             # Preserved for backward compatibility: allow bytes inputs.
@@ -2194,6 +2229,7 @@ class Run:
         - Crashed: Run that stopped sending heartbeats unexpectedly.
         - Finished: Run completed successfully (`exit_code=0`) with all data synced.
         - Failed: Run completed with errors (`exit_code!=0`).
+        - Killed: Run was forcibly stopped before it could finish.
 
         Args:
             exit_code: Integer indicating the run's exit status. Use 0 for success,
@@ -2694,15 +2730,10 @@ class Run:
                 ),
             )
 
-        # Print some final statistics.
         poll_exit_handle = self._backend.interface.deliver_poll_exit()
         result = poll_exit_handle.wait_or(timeout=None)
-        progress.print_sync_dedupe_stats(
-            self._printer,
-            result.response.poll_exit_response,
-        )
-
         self._poll_exit_response = result.response.poll_exit_response
+
         internal_messages_handle = self._backend.interface.deliver_internal_messages()
         result = internal_messages_handle.wait_or(timeout=None)
         self._internal_messages_response = result.response.internal_messages_response
@@ -2748,23 +2779,26 @@ class Run:
         goal: str | None = None,
         overwrite: bool | None = None,
     ) -> wandb_metric.Metric:
-        """Customize metrics logged with `wandb.log()`.
+        """Customize metrics logged with `wandb.Run.log()`.
 
         Args:
             name: The name of the metric to customize.
             step_metric: The name of another metric to serve as the X-axis
                 for this metric in automatically generated charts.
             step_sync: Automatically insert the last value of step_metric into
-                `run.log()` if it is not provided explicitly. Defaults to True
+                `wandb.Run.log()` if it is not provided explicitly. Defaults to True
                  if step_metric is specified.
             hidden: Hide this metric from automatic plots.
             summary: Specify aggregate metrics added to summary.
                 Supported aggregations include "min", "max", "mean", "last",
-                "best", "copy" and "none". "best" is used together with the
-                goal parameter. "none" prevents a summary from being generated.
-                "copy" is deprecated and should not be used.
+                "first", "best", "copy" and "none". "none" prevents a summary
+                from being generated. "best" is used together with the goal
+                parameter, "best" is deprecated and should not be used, use
+                "min" or "max" instead. "copy" is deprecated and should not be
+                used.
             goal: Specify how to interpret the "best" summary type.
-                Supported options are "minimize" and "maximize".
+                Supported options are "minimize" and "maximize". "goal" is
+                deprecated and should not be used, use "min" or "max" instead.
             overwrite: If false, then this call is merged with previous
                 `define_metric` calls for the same metric by using their
                 values for any unspecified parameters. If true, then
@@ -2837,7 +2871,7 @@ class Run:
         if summary:
             summary_items = [s.lower() for s in summary.split(",")]
             summary_ops = []
-            valid = {"min", "max", "mean", "best", "last", "copy", "none"}
+            valid = {"min", "max", "mean", "best", "last", "copy", "none", "first"}
             # TODO: deprecate copy and best
             for i in summary_items:
                 if i not in valid:
@@ -2888,29 +2922,22 @@ class Run:
         idx: int | None = None,
         log_graph: bool = False,
     ) -> None:
-        """Hooks into the given PyTorch model(s) to monitor gradients and the model's computational graph.
+        """Hook into given PyTorch model to monitor gradients and the model's computational graph.
 
-        This function can track parameters, gradients, or both during training. It should be
-        extended to support arbitrary machine learning models in the future.
+        This function can track parameters, gradients, or both during training.
 
         Args:
-            models (Union[torch.nn.Module, Sequence[torch.nn.Module]]):
-                A single model or a sequence of models to be monitored.
-            criterion (Optional[torch.F]):
-                The loss function being optimized (optional).
-            log (Optional[Literal["gradients", "parameters", "all"]]):
-                Specifies whether to log "gradients", "parameters", or "all".
-                Set to None to disable logging. (default="gradients")
-            log_freq (int):
-                Frequency (in batches) to log gradients and parameters. (default=1000)
-            idx (Optional[int]):
-                Index used when tracking multiple models with `wandb.watch`. (default=None)
-            log_graph (bool):
-                Whether to log the model's computational graph. (default=False)
+            models: A single model or a sequence of models to be monitored.
+            criterion: The loss function being optimized (optional).
+            log: Specifies whether to log "gradients", "parameters", or "all".
+                Set to None to disable logging. (default="gradients").
+            log_freq: Frequency (in batches) to log gradients and parameters. (default=1000)
+            idx: Index used when tracking multiple models with `wandb.watch`. (default=None)
+            log_graph: Whether to log the model's computational graph. (default=False)
 
         Raises:
             ValueError:
-                If `wandb.init` has not been called or if any of the models are not instances
+                If `wandb.init()` has not been called or if any of the models are not instances
                 of `torch.nn.Module`.
         """
         wandb.sdk._watch(self, models, criterion, log, log_freq, idx, log_graph)
@@ -2923,8 +2950,7 @@ class Run:
         """Remove pytorch model topology, gradient and parameter hooks.
 
         Args:
-            models (torch.nn.Module | Sequence[torch.nn.Module]):
-                Optional list of pytorch models that have had watch called on them
+            models: Optional list of pytorch models that have had watch called on them.
         """
         wandb.sdk._unwatch(self, models=models)
 
@@ -2939,7 +2965,7 @@ class Run:
     ) -> Artifact | None:
         """Link the given artifact to a portfolio (a promoted collection of artifacts).
 
-        The linked artifact will be visible in the UI for the specified portfolio.
+        Linked artifacts are visible in the UI for the specified portfolio.
 
         Args:
             artifact: the (public or local) artifact which will be linked
@@ -2987,19 +3013,46 @@ class Run:
         Call `download` or `file` on the returned object to get the contents locally.
 
         Args:
-            artifact_or_name: (str or Artifact) An artifact name.
-                May be prefixed with project/ or entity/project/.
-                If no entity is specified in the name, the Run or API setting's entity is used.
-                Valid names can be in the following forms:
-                    - name:version
-                    - name:alias
-                You can also pass an Artifact object created by calling `wandb.Artifact`
-            type: (str, optional) The type of artifact to use.
-            aliases: (list, optional) Aliases to apply to this artifact
+            artifact_or_name: The name of the artifact to use. May be prefixed
+                with the name of the project the artifact was logged to
+                ("<entity>" or "<entity>/<project>"). If no
+                entity is specified in the name, the Run or API setting's entity is used.
+                Valid names can be in the following forms
+            - name:version
+            - name:alias
+            type: The type of artifact to use.
+            aliases: Aliases to apply to this artifact
             use_as: This argument is deprecated and does nothing.
 
         Returns:
             An `Artifact` object.
+
+        Examples:
+        ```python
+        import wandb
+
+        run = wandb.init(project="<example>")
+
+        # Use an artifact by name and alias
+        artifact_a = run.use_artifact(artifact_or_name="<name>:<alias>")
+
+        # Use an artifact by name and version
+        artifact_b = run.use_artifact(artifact_or_name="<name>:v<version>")
+
+        # Use an artifact by entity/project/name:alias
+        artifact_c = run.use_artifact(
+            artifact_or_name="<entity>/<project>/<name>:<alias>"
+        )
+
+        # Use an artifact by entity/project/name:version
+        artifact_d = run.use_artifact(
+            artifact_or_name="<entity>/<project>/<name>:v<version>"
+        )
+
+        # Explicitly finish the run since a context manager is not used.
+        run.finish()
+        ```
+
         """
         if self._settings._offline:
             raise TypeError("Cannot use artifact when in offline mode.")
@@ -3128,24 +3181,20 @@ class Run:
         This is useful when distributed jobs need to all contribute to the same artifact.
 
         Args:
-            artifact_or_path: (str or Artifact) A path to the contents of this artifact,
+            artifact_or_path: A path to the contents of this artifact,
                 can be in the following forms:
-                    - `/local/directory`
-                    - `/local/directory/file.txt`
-                    - `s3://bucket/path`
-                You can also pass an Artifact object created by calling
-                `wandb.Artifact`.
-            name: (str, optional) An artifact name. May be prefixed with entity/project.
-                Valid names can be in the following forms:
-                    - name:version
-                    - name:alias
-                    - digest
-                This will default to the basename of the path prepended with the current
-                run id  if not specified.
-            type: (str) The type of artifact to log, examples include `dataset`, `model`
-            aliases: (list, optional) Aliases to apply to this artifact,
-                defaults to `["latest"]`
-            distributed_id: (string, optional) Unique string that all distributed jobs share. If None,
+            - `/local/directory`
+            - `/local/directory/file.txt`
+            - `s3://bucket/path`
+            name: An artifact name. May be prefixed with "entity/project". Defaults
+                to the basename of the path prepended with the current run ID
+                if not specified. Valid names can be in the following forms:
+            - name:version
+            - name:alias
+            - digest
+            type: The type of artifact to log. Common examples include `dataset`, `model`.
+            aliases: Aliases to apply to this artifact, defaults to `["latest"]`.
+            distributed_id: Unique string that all distributed jobs share. If None,
                 defaults to the run's group name.
 
         Returns:
@@ -3182,24 +3231,24 @@ class Run:
         Subsequent "upserts" with the same distributed ID will result in a new version.
 
         Args:
-            artifact_or_path: (str or Artifact) A path to the contents of this artifact,
+            artifact_or_path: A path to the contents of this artifact,
                 can be in the following forms:
                     - `/local/directory`
                     - `/local/directory/file.txt`
                     - `s3://bucket/path`
                 You can also pass an Artifact object created by calling
                 `wandb.Artifact`.
-            name: (str, optional) An artifact name. May be prefixed with entity/project.
+            name: An artifact name. May be prefixed with entity/project.
                 Valid names can be in the following forms:
                     - name:version
                     - name:alias
                     - digest
                 This will default to the basename of the path prepended with the current
                 run id  if not specified.
-            type: (str) The type of artifact to log, examples include `dataset`, `model`
-            aliases: (list, optional) Aliases to apply to this artifact,
+            type: The type of artifact to log, examples include `dataset`, `model`
+            aliases: Aliases to apply to this artifact,
                 defaults to `["latest"]`
-            distributed_id: (string, optional) Unique string that all distributed jobs share. If None,
+            distributed_id: Unique string that all distributed jobs share. If None,
                 defaults to the run's group name.
 
         Returns:
@@ -3379,39 +3428,24 @@ class Run:
     ) -> None:
         """Logs a model artifact containing the contents inside the 'path' to a run and marks it as an output to this run.
 
+        The name of model artifact can only contain alphanumeric characters,
+        underscores, and hyphens.
+
         Args:
             path: (str) A path to the contents of this model,
                 can be in the following forms:
                     - `/local/directory`
                     - `/local/directory/file.txt`
                     - `s3://bucket/path`
-            name: (str, optional) A name to assign to the model artifact that the file contents will be added to.
-                The string must contain only the following alphanumeric characters: dashes, underscores, and dots.
-                This will default to the basename of the path prepended with the current
-                run id  if not specified.
-            aliases: (list, optional) Aliases to apply to the created model artifact,
+            name: A name to assign to the model artifact that
+                the file contents will be added to. This will default to the
+                basename of the path prepended with the current run id if
+                not specified.
+            aliases: Aliases to apply to the created model artifact,
                     defaults to `["latest"]`
 
-        Examples:
-            ```python
-            run.log_model(
-                path="/local/directory",
-                name="my_model_artifact",
-                aliases=["production"],
-            )
-            ```
-
-            Invalid usage
-            ```python
-            run.log_model(
-                path="/local/directory",
-                name="my_entity/my_project/my_model_artifact",
-                aliases=["production"],
-            )
-            ```
-
         Raises:
-            ValueError: if name has invalid special characters
+            ValueError: If name has invalid special characters.
 
         Returns:
             None
@@ -3427,40 +3461,18 @@ class Run:
         """Download the files logged in a model artifact 'name'.
 
         Args:
-            name: (str) A model artifact name. 'name' must match the name of an existing logged
-                model artifact.
-                May be prefixed with entity/project/. Valid names
-                can be in the following forms:
-                    - model_artifact_name:version
-                    - model_artifact_name:alias
-
-        Examples:
-            ```python
-            run.use_model(
-                name="my_model_artifact:latest",
-            )
+            name: A model artifact name. 'name' must match the name of an existing logged
+                model artifact. May be prefixed with `entity/project/`. Valid names
+                can be in the following forms
+            - model_artifact_name:version
+            - model_artifact_name:alias
 
-            run.use_model(
-                name="my_project/my_model_artifact:v0",
-            )
-
-            run.use_model(
-                name="my_entity/my_project/my_model_artifact:<digest>",
-            )
-            ```
-
-            Invalid usage
-            ```python
-            run.use_model(
-                name="my_entity/my_project/my_model_artifact",
-            )
-            ```
+        Returns:
+            path (str): Path to downloaded model artifact file(s).
 
         Raises:
-            AssertionError: if model artifact 'name' is of a type that does not contain the substring 'model'.
-
-        Returns:
-            path: (str) path to downloaded model artifact file(s).
+            AssertionError: If model artifact 'name' is of a type that does
+                not contain the substring 'model'.
         """
         if self._settings._offline:
             # Downloading artifacts is not supported when offline.
@@ -3494,66 +3506,43 @@ class Run:
     ) -> Artifact | None:
         """Log a model artifact version and link it to a registered model in the model registry.
 
-        The linked model version will be visible in the UI for the specified registered model.
+        Linked model versions are visible in the UI for the specified registered model.
 
-        Steps:
-            - Check if 'name' model artifact has been logged. If so, use the artifact version that matches the files
-            located at 'path' or log a new version. Otherwise log files under 'path' as a new model artifact, 'name'
-            of type 'model'.
-            - Check if registered model with name 'registered_model_name' exists in the 'model-registry' project.
-            If not, create a new registered model with name 'registered_model_name'.
-            - Link version of model artifact 'name' to registered model, 'registered_model_name'.
-            - Attach aliases from 'aliases' list to the newly linked model artifact version.
+        This method will:
+        - Check if 'name' model artifact has been logged. If so, use the artifact version that matches the files
+        located at 'path' or log a new version. Otherwise log files under 'path' as a new model artifact, 'name'
+        of type 'model'.
+        - Check if registered model with name 'registered_model_name' exists in the 'model-registry' project.
+        If not, create a new registered model with name 'registered_model_name'.
+        - Link version of model artifact 'name' to registered model, 'registered_model_name'.
+        - Attach aliases from 'aliases' list to the newly linked model artifact version.
 
         Args:
-            path: (str) A path to the contents of this model,
-                can be in the following forms:
-                    - `/local/directory`
-                    - `/local/directory/file.txt`
-                    - `s3://bucket/path`
-            registered_model_name: (str) - the name of the registered model that the model is to be linked to.
-                A registered model is a collection of model versions linked to the model registry, typically representing a
-                team's specific ML Task. The entity that this registered model belongs to will be derived from the run
-            name: (str, optional) - the name of the model artifact that files in 'path' will be logged to. This will
-                default to the basename of the path prepended with the current run id  if not specified.
-            aliases: (List[str], optional) - alias(es) that will only be applied on this linked artifact
-                inside the registered model.
-                The alias "latest" will always be applied to the latest version of an artifact that is linked.
-
-        Examples:
-            ```python
-            run.link_model(
-                path="/local/directory",
-                registered_model_name="my_reg_model",
-                name="my_model_artifact",
-                aliases=["production"],
-            )
-            ```
-
-            Invalid usage
-            ```python
-            run.link_model(
-                path="/local/directory",
-                registered_model_name="my_entity/my_project/my_reg_model",
-                name="my_model_artifact",
-                aliases=["production"],
-            )
-
-            run.link_model(
-                path="/local/directory",
-                registered_model_name="my_reg_model",
-                name="my_entity/my_project/my_model_artifact",
-                aliases=["production"],
-            )
-            ```
+            path: (str) A path to the contents of this model, can be in the
+                following forms:
+            - `/local/directory`
+            - `/local/directory/file.txt`
+            - `s3://bucket/path`
+            registered_model_name: The name of the registered model that the
+                model is to be linked to. A registered model is a collection of
+                model versions linked to the model registry, typically
+                representing a team's specific ML Task. The entity that this
+                registered model belongs to will be derived from the run.
+            name: The name of the model artifact that files in 'path' will be
+                logged to. This will default to the basename of the path
+                prepended with the current run id  if not specified.
+            aliases: Aliases that will only be applied on this linked artifact
+                inside the registered model. The alias "latest" will always be
+                applied to the latest version of an artifact that is linked.
 
         Raises:
-            AssertionError: if registered_model_name is a path or
-                if model artifact 'name' is of a type that does not contain the substring 'model'
-            ValueError: if name has invalid special characters
+            AssertionError: If registered_model_name is a path or
+                if model artifact 'name' is of a type that does not contain
+                the substring 'model'.
+            ValueError: If name has invalid special characters.
 
         Returns:
-            The linked artifact if linking was successful, otherwise None.
+            The linked artifact if linking was successful, otherwise `None`.
         """
         name_parts = registered_model_name.split("/")
         if len(name_parts) != 1:
@@ -3596,13 +3585,13 @@ class Run:
         level: str | AlertLevel | None = None,
         wait_duration: int | float | timedelta | None = None,
     ) -> None:
-        """Launch an alert with the given title and text.
+        """Create an alert with the given title and text.
 
         Args:
-            title: (str) The title of the alert, must be less than 64 characters long.
-            text: (str) The text body of the alert.
-            level: (str or AlertLevel, optional) The alert level to use, either: `INFO`, `WARN`, or `ERROR`.
-            wait_duration: (int, float, or timedelta, optional) The time to wait (in seconds) before sending another
+            title: The title of the alert, must be less than 64 characters long.
+            text: The text body of the alert.
+            level: The alert level to use, either: `INFO`, `WARN`, or `ERROR`.
+            wait_duration: The time to wait (in seconds) before sending another
                 alert with this title.
         """
         level = level or AlertLevel.INFO
@@ -3714,24 +3703,27 @@ class Run:
         self._printer.display(f"Tracking run with wandb version {wandb.__version__}")
 
     def _header_sync_info(self) -> None:
+        sync_location_msg = f"Run data is saved locally in {self._printer.files(self._settings.sync_dir)}"
+
         if self._settings._offline:
-            self._printer.display(
-                [
-                    f"W&B syncing is set to {self._printer.code('`offline`')}"
-                    f" in this directory. Run {self._printer.code('`wandb online`')}"
-                    f" or set {self._printer.code('WANDB_MODE=online')}"
-                    " to enable cloud syncing.",
-                ]
+            offline_warning = (
+                f"W&B syncing is set to {self._printer.code('`offline`')} "
+                f"in this directory. Run {self._printer.code('`wandb online`')} "
+                f"or set {self._printer.code('WANDB_MODE=online')} "
+                "to enable cloud syncing."
             )
+            self._printer.display([offline_warning, sync_location_msg])
         else:
-            sync_dir = self._settings.sync_dir
-            info = [f"Run data is saved locally in {self._printer.files(sync_dir)}"]
+            messages = [sync_location_msg]
+
             if not self._printer.supports_html:
-                info.append(
+                disable_sync_msg = (
                     f"Run {self._printer.code('`wandb offline`')} to turn off syncing."
                 )
+                messages.append(disable_sync_msg)
+
             if not self._settings.quiet and not self._settings.silent:
-                self._printer.display(info)
+                self._printer.display(messages)
 
     def _header_run_info(self) -> None:
         settings, printer = self._settings, self._printer
@@ -3985,19 +3977,19 @@ def restore(
     By default, will only download the file if it doesn't already exist.
 
     Args:
-        name: the name of the file
-        run_path: optional path to a run to pull files from, i.e. `username/project_name/run_id`
+        name: The name of the file.
+        run_path: Optional path to a run to pull files from, i.e. `username/project_name/run_id`
             if wandb.init has not been called, this is required.
-        replace: whether to download the file even if it already exists locally
-        root: the directory to download the file to.  Defaults to the current
+        replace: Whether to download the file even if it already exists locally
+        root: The directory to download the file to.  Defaults to the current
             directory or the run directory if wandb.init was called.
 
     Returns:
-        None if it can't find the file, otherwise a file object open for reading
+        None if it can't find the file, otherwise a file object open for reading.
 
     Raises:
-        wandb.CommError: if we can't connect to the wandb backend
-        ValueError: if the file is not found or can't find run_path
+        CommError: If W&B can't connect to the W&B backend.
+        ValueError: If the file is not found or can't find run_path.
     """
     is_disabled = wandb.run is not None and wandb.run.disabled
     run = None if is_disabled else wandb.run