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

wandb/sdk/wandb_init.py

@@ -340,7 +340,7 @@ class _WandbInit:
     def _load_autoresume_run_id(self, resume_file: pathlib.Path) -> str | None:
         """Returns the run_id stored in the auto-resume file, if any.
 
-        Returns None if the file does not exist or is not in a valid format.
+        Returns `None` if the file does not exist or is not in a valid format.
 
         Args:
             resume_file: The file path to use for resume='auto' mode.
@@ -1258,7 +1258,7 @@ def init(  # noqa: C901
     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: (
@@ -1288,53 +1288,17 @@ def init(  # noqa: C901
 
     `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.
+    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.
 
-    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:
-
-        ```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
@@ -1346,9 +1310,8 @@ def init(  # noqa: C901
             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
@@ -1389,54 +1352,56 @@ def init(  # noqa: C901
             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
@@ -1445,7 +1410,7 @@ def init(  # noqa: C901
             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.
@@ -1454,35 +1419,45 @@ def init(  # noqa: C901
             `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})
+    ```
     """
     wandb._assert_is_user_process()  # type: ignore
 

wandb/sdk/wandb_login.py

@@ -55,25 +55,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.
     """
     _handle_host_wandb_setting(host)
     return _login(
@@ -258,7 +259,8 @@ class _WandbLogin:
 
         if not is_api_key_valid:
             raise AuthenticationError(
-                "API key verification failed. Make sure your API key is valid."
+                f"API key verification failed for host {self._settings.base_url}."
+                " Make sure your API key is valid."
             )
 
 
@@ -272,6 +274,7 @@ def _login(
     timeout: Optional[int] = None,
     verify: bool = False,
     referrer: str = "models",
+    update_api_key: bool = True,
     _silent: Optional[bool] = None,
     _disable_warning: Optional[bool] = None,
 ) -> bool:
@@ -318,7 +321,8 @@ def _login(
         wlogin._verify_login(key)
 
     if not key_is_pre_configured:
-        wlogin.try_save_api_key(key)
+        if update_api_key:
+            wlogin.try_save_api_key(key)
         wlogin.update_session(key, status=key_status)
         wlogin._update_global_anonymous_setting()
 

wandb/sdk/wandb_metric.py

@@ -100,6 +100,8 @@ class Metric:
                 m.summary.none = True
             if "best" in summary_set:
                 m.summary.best = True
+            if "first" in summary_set:
+                m.summary.first = True
         if self._goal == "min":
             m.goal = m.GOAL_MINIMIZE
         if self._goal == "max":