wandb 0.20.2rc20250616__py3-none-macosx_11_0_arm64.whl → 0.21.1__py3-none-macosx_11_0_arm64.whl

wandb/__init__.pyi

@@ -12,20 +12,20 @@ For reference documentation, see https://docs.wandb.com/ref/python.
 from __future__ import annotations
 
 __all__ = (
-    "__version__",
+    "__version__",  # doc:exclude
     "init",
     "finish",
     "setup",
     "login",
-    "save",
+    "save",  # doc:exclude
     "sweep",
     "controller",
     "agent",
-    "config",
-    "log",
-    "summary",
+    "config",  # doc:exclude
+    "log",  # doc:exclude
+    "summary",  # doc:exclude
     "Api",
-    "Graph",
+    "Graph",  # doc:exclude
     "Image",
     "Plotly",
     "Video",
@@ -36,26 +36,27 @@ __all__ = (
     "Object3D",
     "Molecule",
     "Histogram",
-    "ArtifactTTL",
-    "log_artifact",
-    "use_artifact",
-    "log_model",
-    "use_model",
-    "link_model",
-    "define_metric",
-    "Error",
-    "termsetup",
-    "termlog",
-    "termerror",
-    "termwarn",
+    "ArtifactTTL",  # doc:exclude
+    "log_artifact",  # doc:exclude
+    "use_artifact",  # doc:exclude
+    "log_model",  # doc:exclude
+    "use_model",  # doc:exclude
+    "link_model",  # doc:exclude
+    "define_metric",  # doc:exclude
+    "Error",  # doc:exclude
+    "termsetup",  # doc:exclude
+    "termlog",  # doc:exclude
+    "termerror",  # doc:exclude
+    "termwarn",  # doc:exclude
     "Artifact",
     "Settings",
     "teardown",
-    "watch",
-    "unwatch",
-    "plot",
+    "watch",  # doc:exclude
+    "unwatch",  # doc:exclude
+    "plot",  # doc:exclude
     "plot_table",
     "restore",
+    "Run",
 )
 
 import os
@@ -106,7 +107,7 @@ if TYPE_CHECKING:
     import wandb
     from wandb.plot import CustomChart
 
-__version__: str = "0.20.2rc20250616"
+__version__: str = "0.21.1"
 
 run: Run | None
 config: wandb_config.Config
@@ -155,45 +156,45 @@ def setup(settings: Settings | None = None) -> _WandbSetup:
             overridden by subsequent `wandb.init()` calls.
 
     Example:
-        ```python
-        import multiprocessing
-
-        import wandb
-
-        def run_experiment(params):
-            with wandb.init(config=params):
-                # Run experiment
-                pass
-
-        if __name__ == "__main__":
-            # Start backend and set global config
-            wandb.setup(settings={"project": "my_project"})
-
-            # Define experiment parameters
-            experiment_params = [
-                {"learning_rate": 0.01, "epochs": 10},
-                {"learning_rate": 0.001, "epochs": 20},
-            ]
-
-            # Start multiple processes, each running a separate experiment
-            processes = []
-            for params in experiment_params:
-                p = multiprocessing.Process(target=run_experiment, args=(params,))
-                p.start()
-                processes.append(p)
-
-            # Wait for all processes to complete
-            for p in processes:
-                p.join()
-
-            # Optional: Explicitly shut down the backend
-            wandb.teardown()
-        ```
+    ```python
+    import multiprocessing
+
+    import wandb
+
+    def run_experiment(params):
+        with wandb.init(config=params):
+            # Run experiment
+            pass
+
+    if __name__ == "__main__":
+        # Start backend and set global config
+        wandb.setup(settings={"project": "my_project"})
+
+        # Define experiment parameters
+        experiment_params = [
+            {"learning_rate": 0.01, "epochs": 10},
+            {"learning_rate": 0.001, "epochs": 20},
+        ]
+
+        # Start multiple processes, each running a separate experiment
+        processes = []
+        for params in experiment_params:
+            p = multiprocessing.Process(target=run_experiment, args=(params,))
+            p.start()
+            processes.append(p)
+
+        # Wait for all processes to complete
+        for p in processes:
+            p.join()
+
+        # Optional: Explicitly shut down the backend
+        wandb.teardown()
+    ```
     """
     ...
 
 def teardown(exit_code: int | None = None) -> None:
-    """Waits for wandb to finish and frees resources.
+    """Waits for W&B to finish and frees resources.
 
     Completes any runs that were not explicitly finished
     using `run.finish()` and waits for all data to be uploaded.
@@ -219,7 +220,7 @@ def init(
     allow_val_change: bool | None = None,
     group: str | None = None,
     job_type: str | None = None,
-    mode: Literal["online", "offline", "disabled"] | None = None,
+    mode: Literal["online", "offline", "disabled", "shared"] | None = None,
     force: bool | None = None,
     anonymous: Literal["never", "allow", "must"] | None = None,
     reinit: (
@@ -249,53 +250,17 @@ def init(
 
     `wandb.init()` spawns a new background process to log data to a run, and it
     also syncs data to https://wandb.ai by default, so you can see your results
-    in real-time.
-
-    Call `wandb.init()` to start a run before logging data with `wandb.log()`.
-    When you're done logging data, call `wandb.finish()` to end the run. If you
-    don't call `wandb.finish()`, the run will end when your script exits.
-
-    For more on using `wandb.init()`, including detailed examples, check out our
-    [guide and FAQs](https://docs.wandb.ai/guides/track/launch).
-
-    Examples:
-        ### Explicitly set the entity and project and choose a name for the run:
-
-        ```python
-        import wandb
-
-        run = wandb.init(
-            entity="geoff",
-            project="capsules",
-            name="experiment-2021-10-31",
-        )
-
-        # ... your training code here ...
-
-        run.finish()
-        ```
-
-        ### Add metadata about the run using the `config` argument:
+    in real-time. When you're done logging data, call `wandb.Run.finish()` to end the run.
+    If you don't call `run.finish()`, the run will end when your script exits.
 
-        ```python
-        import wandb
-
-        config = {"lr": 0.01, "batch_size": 32}
-        with wandb.init(config=config) as run:
-            run.config.update({"architecture": "resnet", "depth": 34})
-
-            # ... your training code here ...
-        ```
-
-        Note that you can use `wandb.init()` as a context manager to automatically
-        call `wandb.finish()` at the end of the block.
+    Run IDs must not contain any of the following special characters `/ \ # ? % :`
 
     Args:
-        entity: The username or team name under which the runs will be logged.
-            The entity must already exist, so ensure you’ve created your account
+        entity: The username or team name the runs are logged to.
+            The entity must already exist, so ensure you create your account
             or team in the UI before starting to log runs. If not specified, the
             run will default your default entity. To change the default entity,
-            go to [your settings](https://wandb.ai/settings) and update the
+            go to your settings and update the
             "Default location to create new projects" under "Default team".
         project: The name of the project under which this run will be logged.
             If not specified, we use a heuristic to infer the project name based
@@ -307,9 +272,8 @@ def init(
             to the `./wandb` directory. Note that this does not affect the
             location where artifacts are stored when calling `download()`.
         id: A unique identifier for this run, used for resuming. It must be unique
-            within the project and cannot be reused once a run is deleted. The
-            identifier must not contain any of the following special characters:
-            `/ \ # ? % :`. For a short descriptive name, use the `name` field,
+            within the project and cannot be reused once a run is deleted. For
+            a short descriptive name, use the `name` field,
             or for saving hyperparameters to compare across runs, use `config`.
         name: A short display name for this run, which appears in the UI to help
             you identify it. By default, we generate a random two-word name
@@ -325,7 +289,7 @@ def init(
             the UI.
             If resuming a run, the tags provided here will replace any existing
             tags. To add tags to a resumed run without overwriting the current
-            tags, use `run.tags += ["new_tag"]` after calling `run = wandb.init()`.
+            tags, use `run.tags += ("new_tag",)` after calling `run = wandb.init()`.
         config: Sets `wandb.config`, a dictionary-like object for storing input
             parameters to your run, such as model hyperparameters or data
             preprocessing settings.
@@ -350,54 +314,56 @@ def init(
             multiple jobs that train and evaluate a model on different test sets.
             Grouping allows you to manage related runs collectively in the UI,
             making it easy to toggle and review results as a unified experiment.
-            For more information, refer to our
-            [guide to grouping runs](https://docs.wandb.com/guides/runs/grouping).
         job_type: Specify the type of run, especially helpful when organizing runs
             within a group as part of a larger experiment. For example, in a group,
             you might label runs with job types such as "train" and "eval".
             Defining job types enables you to easily filter and group similar runs
             in the UI, facilitating direct comparisons.
         mode: Specifies how run data is managed, with the following options:
-            - `"online"` (default): Enables live syncing with W&B when a network
-                connection is available, with real-time updates to visualizations.
-            - `"offline"`: Suitable for air-gapped or offline environments; data
-                is saved locally and can be synced later. Ensure the run folder
-                is preserved to enable future syncing.
-            - `"disabled"`: Disables all W&B functionality, making the run’s methods
-                no-ops. Typically used in testing to bypass W&B operations.
+        - `"online"` (default): Enables live syncing with W&B when a network
+            connection is available, with real-time updates to visualizations.
+        - `"offline"`: Suitable for air-gapped or offline environments; data
+            is saved locally and can be synced later. Ensure the run folder
+            is preserved to enable future syncing.
+        - `"disabled"`: Disables all W&B functionality, making the run’s methods
+            no-ops. Typically used in testing to bypass W&B operations.
+        - `"shared"`: (This is an experimental feature). Allows multiple processes,
+            possibly on different machines, to simultaneously log to the same run.
+            In this approach you use a primary node and one or more worker nodes
+            to log data to the same run. Within the primary node you
+            initialize a run. For each worker node, initialize a run
+            using the run ID used by the primary node.
         force: Determines if a W&B login is required to run the script. If `True`,
             the user must be logged in to W&B; otherwise, the script will not
             proceed. If `False` (default), the script can proceed without a login,
             switching to offline mode if the user is not logged in.
         anonymous: Specifies the level of control over anonymous data logging.
             Available options are:
-            - `"never"` (default): Requires you to link your W&B account before
-                tracking the run. This prevents unintentional creation of anonymous
-                runs by ensuring each run is associated with an account.
-            - `"allow"`: Enables a logged-in user to track runs with their account,
-                but also allows someone running the script without a W&B account
-                to view the charts and data in the UI.
-            - `"must"`: Forces the run to be logged to an anonymous account, even
-                if the user is logged in.
+        - `"never"` (default): Requires you to link your W&B account before
+            tracking the run. This prevents unintentional creation of anonymous
+            runs by ensuring each run is associated with an account.
+        - `"allow"`: Enables a logged-in user to track runs with their account,
+            but also allows someone running the script without a W&B account
+            to view the charts and data in the UI.
+        - `"must"`: Forces the run to be logged to an anonymous account, even
+            if the user is logged in.
         reinit: Shorthand for the "reinit" setting. Determines the behavior of
             `wandb.init()` when a run is active.
         resume: Controls the behavior when resuming a run with the specified `id`.
             Available options are:
-            - `"allow"`: If a run with the specified `id` exists, it will resume
-                from the last step; otherwise, a new run will be created.
-            - `"never"`: If a run with the specified `id` exists, an error will
-                be raised. If no such run is found, a new run will be created.
-            - `"must"`: If a run with the specified `id` exists, it will resume
-                from the last step. If no run is found, an error will be raised.
-            - `"auto"`: Automatically resumes the previous run if it crashed on
-                this machine; otherwise, starts a new run.
-            - `True`: Deprecated. Use `"auto"` instead.
-            - `False`: Deprecated. Use the default behavior (leaving `resume`
-                unset) to always start a new run.
-            Note: If `resume` is set, `fork_from` and `resume_from` cannot be
+        - `"allow"`: If a run with the specified `id` exists, it will resume
+            from the last step; otherwise, a new run will be created.
+        - `"never"`: If a run with the specified `id` exists, an error will
+            be raised. If no such run is found, a new run will be created.
+        - `"must"`: If a run with the specified `id` exists, it will resume
+            from the last step. If no run is found, an error will be raised.
+        - `"auto"`: Automatically resumes the previous run if it crashed on
+            this machine; otherwise, starts a new run.
+        - `True`: Deprecated. Use `"auto"` instead.
+        - `False`: Deprecated. Use the default behavior (leaving `resume`
+            unset) to always start a new run.
+            If `resume` is set, `fork_from` and `resume_from` cannot be
             used. When `resume` is unset, the system will always start a new run.
-            For more details, see our
-            [guide to resuming runs](https://docs.wandb.com/guides/runs/resuming).
         resume_from: Specifies a moment in a previous run to resume a run from,
             using the format `{run_id}?_step={step}`. This allows users to truncate
             the history logged to a run at an intermediate step and resume logging
@@ -406,7 +372,7 @@ def init(
             take precedence.
             `resume`, `resume_from` and `fork_from` cannot be used together, only
             one of them can be used at a time.
-            Note: This feature is in beta and may change in the future.
+            Note that this feature is in beta and may change in the future.
         fork_from: Specifies a point in a previous run from which to fork a new
             run, using the format `{id}?_step={step}`. This creates a new run that
             resumes logging from the specified step in the target run’s history.
@@ -415,35 +381,45 @@ def init(
             `fork_from` argument, an error will be raised if they are the same.
             `resume`, `resume_from` and `fork_from` cannot be used together, only
             one of them can be used at a time.
-            Note: This feature is in beta and may change in the future.
+            Note that this feature is in beta and may change in the future.
         save_code: Enables saving the main script or notebook to W&B, aiding in
             experiment reproducibility and allowing code comparisons across runs in
             the UI. By default, this is disabled, but you can change the default to
-            enable on your [settings page](https://wandb.ai/settings).
+            enable on your settings page.
         tensorboard: Deprecated. Use `sync_tensorboard` instead.
         sync_tensorboard: Enables automatic syncing of W&B logs from TensorBoard
             or TensorBoardX, saving relevant event files for viewing in the W&B UI.
             saving relevant event files for viewing in the W&B UI. (Default: `False`)
         monitor_gym: Enables automatic logging of videos of the environment when
-            using OpenAI Gym. For additional details, see our
-            [guide for gym integration](https://docs.wandb.com/guides/integrations/openai-gym).
+            using OpenAI Gym.
         settings: Specifies a dictionary or `wandb.Settings` object with advanced
             settings for the run.
 
     Returns:
-        A `Run` object, which is a handle to the current run. Use this object
-        to perform operations like logging data, saving files, and finishing
-        the run. See the [Run API](https://docs.wandb.ai/ref/python/run) for
-        more details.
+        A `Run` object.
 
     Raises:
         Error: If some unknown or internal error happened during the run
             initialization.
         AuthenticationError: If the user failed to provide valid credentials.
-        CommError: If there was a problem communicating with the W&B server.
-        UsageError: If the user provided invalid arguments to the function.
-        KeyboardInterrupt: If the user interrupts the run initialization process.
-            If the user interrupts the run initialization process.
+        CommError: If there was a problem communicating with the WandB server.
+        UsageError: If the user provided invalid arguments.
+        KeyboardInterrupt: If user interrupts the run.
+
+    Examples:
+    `wandb.init()` returns a `Run` object. Use the run object to log data,
+    save artifacts, and manage the run lifecycle.
+
+    ```python
+    import wandb
+
+    config = {"lr": 0.01, "batch_size": 32}
+    with wandb.init(config=config) as run:
+        # Log accuracy and loss to the run
+        acc = 0.95  # Example accuracy
+        loss = 0.05  # Example loss
+        run.log({"accuracy": acc, "loss": loss})
+    ```
     """
     ...
 
@@ -486,25 +462,26 @@ def login(
     `verify=True`.
 
     Args:
-        anonymous: (string, optional) Can be "must", "allow", or "never".
+        anonymous: Set to "must", "allow", or "never".
             If set to "must", always log a user in anonymously. If set to
             "allow", only create an anonymous user if the user
             isn't already logged in. If set to "never", never log a
-            user anonymously. Default set to "never".
-        key: (string, optional) The API key to use.
-        relogin: (bool, optional) If true, will re-prompt for API key.
-        host: (string, optional) The host to connect to.
-        force: (bool, optional) If true, will force a relogin.
-        timeout: (int, optional) Number of seconds to wait for user input.
-        verify: (bool) Verify the credentials with the W&B server.
-        referrer: (string, optional) The referrer to use in the URL login request.
+            user anonymously. Default set to "never". Defaults to `None`.
+        key: The API key to use.
+        relogin: If true, will re-prompt for API key.
+        host: The host to connect to.
+        force: If true, will force a relogin.
+        timeout: Number of seconds to wait for user input.
+        verify: Verify the credentials with the W&B server.
+        referrer: The referrer to use in the URL login request.
+
 
     Returns:
-        bool: if key is configured
+        bool: If `key` is configured.
 
     Raises:
-        AuthenticationError - if api_key fails verification with the server
-        UsageError - if api_key cannot be configured and no tty
+        AuthenticationError: If `api_key` fails verification with the server.
+        UsageError: If `api_key` cannot be configured and no tty.
     """
     ...
 
@@ -516,91 +493,94 @@ def log(
     """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
+
+    with wandb.init() as run:
+        run.log({"train-loss": 0.5, "accuracy": 0.9})
+    ```
 
-    Visualize logged data in the workspace at [wandb.ai](https://wandb.ai),
+    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:
@@ -618,59 +598,64 @@ def log(
             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
+
+    ```python
+    import wandb
 
-        ### Basic usage
-        ```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(
@@ -683,14 +668,15 @@ def log(
             image = wandb.Image(pil_image, caption=f"random field {i}")
             examples.append(image)
         run.log({"examples": examples})
-        ```
+    ```
 
-        ### Video from numpy
-        ```python
-        import numpy as np
-        import wandb
+    Video from NumPy
+
+    ```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,
@@ -699,35 +685,38 @@ def log(
             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": [
@@ -737,11 +726,11 @@ def log(
                 ]
             }
         )
-        ```
+    ```
 
     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.
     """
     ...
 
@@ -760,42 +749,48 @@ def save(
 
     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:
-
-    ```
-    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.
+    structure beneath it is preserved.
 
-    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()
+    ```
     """
     ...
 
@@ -813,11 +808,12 @@ def sweep(
     Make note the unique identifier, `sweep_id`, that is returned.
     At a later step provide the `sweep_id` to a sweep agent.
 
+    See [Sweep configuration structure](https://docs.wandb.ai/guides/sweeps/define-sweep-configuration)
+    for information on how to define your sweep.
+
     Args:
       sweep: The configuration of a hyperparameter search.
-        (or configuration generator). See
-        [Sweep configuration structure](https://docs.wandb.ai/guides/sweeps/define-sweep-configuration)
-        for information on how to define your sweep.
+        (or configuration generator).
         If you provide a callable, ensure that the callable does
         not take arguments and that it returns a dictionary that
         conforms to the W&B sweep config spec.
@@ -832,7 +828,7 @@ def sweep(
       prior_runs: The run IDs of existing runs to add to this sweep.
 
     Returns:
-      sweep_id: str. A unique identifier for the sweep.
+      str: A unique identifier for the sweep.
     """
     ...
 
@@ -843,16 +839,16 @@ def controller(
 ) -> _WandbController:
     """Public sweep controller constructor.
 
-    Usage:
-        ```python
-        import wandb
+    Examples:
+    ```python
+    import wandb
 
-        tuner = wandb.controller(...)
-        print(tuner.sweep_config)
-        print(tuner.sweep_id)
-        tuner.configure_search(...)
-        tuner.configure_stopping(...)
-        ```
+    tuner = wandb.controller(...)
+    print(tuner.sweep_config)
+    print(tuner.sweep_id)
+    tuner.configure_search(...)
+    tuner.configure_stopping(...)
+    ```
     """
     ...
 
@@ -895,23 +891,26 @@ def define_metric(
     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
@@ -967,19 +966,43 @@ def use_artifact(
     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()
+    ```
     """
     ...
 
@@ -990,39 +1013,24 @@ def log_model(
 ) -> 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
@@ -1033,40 +1041,18 @@ def use_model(name: str) -> FilePathStr:
     """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",
-        )
-
-        run.use_model(
-            name="my_project/my_model_artifact:v0",
-        )
-
-        run.use_model(
-            name="my_entity/my_project/my_model_artifact:<digest>",
-        )
-        ```
+        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
 
-        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'.
     """
     ...
 
@@ -1078,66 +1064,43 @@ def link_model(
 ) -> 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`.
     """
     ...
 
@@ -1153,27 +1116,50 @@ def plot_table(
     This function creates a custom chart based on a Vega-Lite specification and
     a data table represented by a `wandb.Table` object. The specification needs
     to be predefined and stored in the W&B backend. The function returns a custom
-    chart object that can be logged to W&B using `wandb.log()`.
+    chart object that can be logged to W&B using `wandb.Run.log()`.
 
     Args:
-        vega_spec_name (str): The name or identifier of the Vega-Lite spec
+        vega_spec_name: The name or identifier of the Vega-Lite spec
             that defines the visualization structure.
-        data_table (wandb.Table): A `wandb.Table` object containing the data to be
+        data_table: A `wandb.Table` object containing the data to be
             visualized.
-        fields (dict[str, Any]): A mapping between the fields in the Vega-Lite spec and the
+        fields: A mapping between the fields in the Vega-Lite spec and the
             corresponding columns in the data table to be visualized.
-        string_fields (dict[str, Any] | None): A dictionary for providing values for any string constants
+        string_fields: A dictionary for providing values for any string constants
             required by the custom visualization.
-        split_table (bool): Whether the table should be split into a separate section
+        split_table: Whether the table should be split into a separate section
             in the W&B UI. If `True`, the table will be displayed in a section named
             "Custom Chart Tables". Default is `False`.
 
     Returns:
         CustomChart: A custom chart object that can be logged to W&B. To log the
-            chart, pass it to `wandb.log()`.
+            chart, pass the chart object as argument to `wandb.Run.log()`.
 
     Raises:
         wandb.Error: If `data_table` is not a `wandb.Table` object.
+
+    Example:
+    ```python
+    # Create a custom chart using a Vega-Lite spec and the data table.
+    import wandb
+
+    data = [[1, 1], [2, 2], [3, 3], [4, 4], [5, 5]]
+    table = wandb.Table(data=data, columns=["x", "y"])
+    fields = {"x": "x", "y": "y", "title": "MY TITLE"}
+
+    with wandb.init() as run:
+        # Training code goes here
+
+        # Create a custom title with `string_fields`.
+        my_custom_chart = wandb.plot_table(
+            vega_spec_name="wandb/line/v0",
+            data_table=table,
+            fields=fields,
+            string_fields={"title": "Title"},
+        )
+
+        run.log({"custom_chart": my_custom_chart})
+    ```
     """
     ...
 
@@ -1185,29 +1171,22 @@ def watch(
     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`.
     """
     ...
@@ -1218,8 +1197,7 @@ def unwatch(
     """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.
     """
     ...
 
@@ -1235,18 +1213,18 @@ 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.
     """
     ...