wandb 0.19.0rc1__py3-none-macosx_10_13_x86_64.whl → 0.19.1rc1__py3-none-macosx_10_13_x86_64.whl

wandb/__init__.py

@@ -10,7 +10,7 @@ For reference documentation, see https://docs.wandb.com/ref/python.
 """
 from __future__ import annotations
 
-__version__ = "0.19.0rc1"
+__version__ = "0.19.1rc1"
 
 
 from wandb.errors import Error

wandb/__init__.pyi

@@ -103,7 +103,7 @@ if TYPE_CHECKING:
     import wandb
     from wandb.plot import CustomChart
 
-__version__: str = "0.19.0rc1"
+__version__: str = "0.19.1rc1"
 
 run: Run | None
 config: wandb_config.Config
@@ -140,13 +140,11 @@ def setup(
 
         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"})
@@ -188,237 +186,239 @@ def teardown(exit_code: int | None = None) -> None:
     ...
 
 def init(
-    job_type: str | None = None,
-    dir: StrPath | None = None,
-    config: dict | str | None = None,
-    project: str | None = None,
     entity: str | None = None,
-    reinit: bool | None = None,
-    tags: Sequence[str] | None = None,
-    group: str | None = None,
+    project: str | None = None,
+    dir: StrPath | None = None,
+    id: str | None = None,
     name: str | None = None,
     notes: str | None = None,
+    tags: Sequence[str] | None = None,
+    config: dict[str, Any] | str | None = None,
     config_exclude_keys: list[str] | None = None,
     config_include_keys: list[str] | None = None,
-    anonymous: str | None = None,
-    mode: str | None = None,
     allow_val_change: bool | None = None,
-    resume: bool | str | None = None,
+    group: str | None = None,
+    job_type: str | None = None,
+    mode: Literal["online", "offline", "disabled"] | None = None,
     force: bool | None = None,
-    tensorboard: bool | None = None,  # alias for sync_tensorboard
+    anonymous: Literal["never", "allow", "must"] | None = None,
+    reinit: bool | None = None,
+    resume: bool | Literal["allow", "never", "must", "auto"] | None = None,
+    resume_from: str | None = None,
+    fork_from: str | None = None,
+    save_code: bool | None = None,
+    tensorboard: bool | None = None,
     sync_tensorboard: bool | None = None,
     monitor_gym: bool | None = None,
-    save_code: bool | None = None,
-    id: str | None = None,
-    fork_from: str | None = None,
-    resume_from: str | None = None,
     settings: Settings | dict[str, Any] | None = None,
 ) -> Run:
     r"""Start a new run to track and log to W&B.
 
-    In an ML training pipeline, you could add `wandb.init()`
-    to the beginning of your training script as well as your evaluation
-    script, and each piece would be tracked as a run in W&B.
+    In an ML training pipeline, you could add `wandb.init()` to the beginning of
+    your training script as well as your evaluation script, and each piece would
+    be tracked as a run in W&B.
 
     `wandb.init()` spawns a new background process to log data to a run, and it
-    also syncs data to wandb.ai by default, so you can see live visualizations.
-
-    Call `wandb.init()` to start a run before logging data with `wandb.log()`:
-    <!--yeadoc-test:init-method-log-->
-    ```python
-    import wandb
+    also syncs data to https://wandb.ai by default, so you can see your results
+    in real-time.
 
-    wandb.init()
-    # ... calculate metrics, generate media
-    wandb.log({"accuracy": 0.9})
-    ```
+    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.
 
-    `wandb.init()` returns a run object, and you can also access the run object
-    via `wandb.run`:
-    <!--yeadoc-test:init-and-assert-global-->
-    ```python
-    import wandb
+    For more on using `wandb.init()`, including detailed examples, check out our
+    [guide and FAQs](https://docs.wandb.ai/guides/track/launch).
 
-    run = wandb.init()
+    Examples:
+        ### Explicitly set the entity and project and choose a name for the run:
 
-    assert run is wandb.run
-    ```
+        ```python
+        import wandb
 
-    At the end of your script, we will automatically call `wandb.finish` to
-    finalize and cleanup the run. However, if you call `wandb.init` from a
-    child process, you must explicitly call `wandb.finish` at the end of the
-    child process.
+        run = wandb.init(
+            entity="geoff",
+            project="capsules",
+            name="experiment-2021-10-31",
+        )
 
-    For more on using `wandb.init()`, including detailed examples, check out our
-    [guide and FAQs](https://docs.wandb.ai/guides/track/launch).
+        # ... your training code here ...
 
-    Args:
-        project: (str, optional) The name of the project where you're sending
-            the new run. If the project is not specified, we will try to infer
-            the project name from git root or the current program file. If we
-            can't infer the project name, we will default to `"uncategorized"`.
-        entity: (str, optional) An entity is a username or team name where
-            you're sending runs. This entity must exist before you can send runs
-            there, so make sure to create your account or team in the UI before
-            starting to log runs.
-            If you don't specify an entity, the run will be sent to your default
-            entity. Change your default entity
-            in [your settings](https://wandb.ai/settings) under "default location
-            to create new projects".
-        config: (dict, argparse, absl.flags, str, optional)
-            This sets `wandb.config`, a dictionary-like object for saving inputs
-            to your job, like hyperparameters for a model or settings for a data
-            preprocessing job. The config will show up in a table in the UI that
-            you can use to group, filter, and sort runs. Keys should not contain
-            `.` in their names, and values should be under 10 MB.
-            If dict, argparse or absl.flags: will load the key value pairs into
-                the `wandb.config` object.
-            If str: will look for a yaml file by that name, and load config from
-                that file into the `wandb.config` object.
-        save_code: (bool, optional) Turn this on to save the main script or
-            notebook to W&B. This is valuable for improving experiment
-            reproducibility and to diff code across experiments in the UI. By
-            default this is off, but you can flip the default behavior to on
-            in [your settings page](https://wandb.ai/settings).
-        group: (str, optional) Specify a group to organize individual runs into
-            a larger experiment. For example, you might be doing cross
-            validation, or you might have multiple jobs that train and evaluate
-            a model against different test sets. Group gives you a way to
-            organize runs together into a larger whole, and you can toggle this
-            on and off in the UI. For more details, see our
-            [guide to grouping runs](https://docs.wandb.com/guides/runs/grouping).
-        job_type: (str, optional) Specify the type of run, which is useful when
-            you're grouping runs together into larger experiments using group.
-            For example, you might have multiple jobs in a group, with job types
-            like train and eval. Setting this makes it easy to filter and group
-            similar runs together in the UI so you can compare apples to apples.
-        tags: (list, optional) A list of strings, which will populate the list
-            of tags on this run in the UI. Tags are useful for organizing runs
-            together, or applying temporary labels like "baseline" or
-            "production". It's easy to add and remove tags in the UI, or filter
-            down to just runs with a specific tag.
-            If you are resuming a run, its tags will be overwritten by the tags
-            you pass to `wandb.init()`. If you want to add tags to a resumed run
-            without overwriting its existing tags, use `run.tags += ["new_tag"]`
-            after `wandb.init()`.
-        name: (str, optional) A short display name for this run, which is how
-            you'll identify this run in the UI. By default, we generate a random
-            two-word name that lets you easily cross-reference runs from the
-            table to charts. Keeping these run names short makes the chart
-            legends and tables easier to read. If you're looking for a place to
-            save your hyperparameters, we recommend saving those in config.
-        notes: (str, optional) A longer description of the run, like a `-m` commit
-            message in git. This helps you remember what you were doing when you
-            ran this run.
-        dir: (str or pathlib.Path, optional) An absolute path to a directory where
-            metadata will be stored. When you call `download()` on an artifact,
-            this is the directory where downloaded files will be saved. By default,
-            this is the `./wandb` directory.
-        resume: (bool, str, optional) Sets the resuming behavior. Options:
-            `"allow"`, `"must"`, `"never"`, `"auto"` or `None`. Defaults to `None`.
-            Cases:
-            - `None` (default): If the new run has the same ID as a previous run,
-                this run overwrites that data.
-            - `"auto"` (or `True`): if the previous run on this machine crashed,
-                automatically resume it. Otherwise, start a new run.
-            - `"allow"`: if id is set with `init(id="UNIQUE_ID")` or
-                `WANDB_RUN_ID="UNIQUE_ID"` and it is identical to a previous run,
-                wandb will automatically resume the run with that id. Otherwise,
-                wandb will start a new run.
-            - `"never"`: if id is set with `init(id="UNIQUE_ID")` or
-                `WANDB_RUN_ID="UNIQUE_ID"` and it is identical to a previous run,
-                wandb will crash.
-            - `"must"`: if id is set with `init(id="UNIQUE_ID")` or
-                `WANDB_RUN_ID="UNIQUE_ID"` and it is identical to a previous run,
-                wandb will automatically resume the run with the id. Otherwise,
-                wandb will crash.
-            See [our guide to resuming runs](https://docs.wandb.com/guides/runs/resuming)
-            for more.
-        reinit: (bool, optional) Allow multiple `wandb.init()` calls in the same
-            process. (default: `False`)
-        config_exclude_keys: (list, optional) string keys to exclude from
-            `wandb.config`.
-        config_include_keys: (list, optional) string keys to include in
-            `wandb.config`.
-        anonymous: (str, optional) Controls anonymous data logging. Options:
-            - `"never"` (default): requires you to link your W&B account before
-                tracking the run, so you don't accidentally create an anonymous
-                run.
-            - `"allow"`: lets a logged-in user track runs with their account, but
-                lets someone who is running the script without a W&B account see
-                the charts in the UI.
-            - `"must"`: sends the run to an anonymous account instead of to a
-                signed-up user account.
-        mode: (str, optional) Can be `"online"`, `"offline"` or `"disabled"`. Defaults to
-            online.
-        allow_val_change: (bool, optional) Whether to allow config values to
-            change after setting the keys once. By default, we throw an exception
-            if a config value is overwritten. If you want to track something
-            like a varying learning rate at multiple times during training, use
-            `wandb.log()` instead. (default: `False` in scripts, `True` in Jupyter)
-        force: (bool, optional) If `True`, this crashes the script if a user isn't
-            logged in to W&B. If `False`, this will let the script run in offline
-            mode if a user isn't logged in to W&B. (default: `False`)
-        sync_tensorboard: (bool, optional) Synchronize wandb logs from tensorboard or
-            tensorboardX and save the relevant events file. (default: `False`)
-        tensorboard: (bool, optional) Alias for `sync_tensorboard`, deprecated.
-        monitor_gym: (bool, optional) Automatically log videos of environment when
-            using OpenAI Gym. (default: `False`)
-            See [our guide to this integration](https://docs.wandb.com/guides/integrations/openai-gym).
-        id: (str, optional) A unique ID for this run, used for resuming. It must
-            be unique in the project, and if you delete a run you can't reuse
-            the ID. Use the `name` field for a short descriptive name, or `config`
-            for saving hyperparameters to compare across runs. The ID cannot
-            contain the following special characters: `/\#?%:`.
-            See [our guide to resuming runs](https://docs.wandb.com/guides/runs/resuming).
-        fork_from: (str, optional) A string with the format `{run_id}?_step={step}` describing
-            a moment in a previous run to fork a new run from. Creates a new run that picks up
-            logging history from the specified run at the specified moment. The target run must
-            be in the current project. Example: `fork_from="my-run-id?_step=1234"`.
-        resume_from: (str, optional) A string with the format `{run_id}?_step={step}` describing
-            a moment in a previous run to resume a run from. This allows users to truncate
-            the history logged to a run at an intermediate step and resume logging from that step.
-            It uses run forking under the hood. The target run must be in the
-            current project. Example: `resume_from="my-run-id?_step=1234"`.
-        settings: (dict, wandb.Settings, optional) Settings to use for this run. (default: None)
+        run.finish()
+        ```
 
-    Examples:
-    ### Set where the run is logged
+        ### Add metadata about the run using the `config` argument:
 
-    You can change where the run is logged, just like changing
-    the organization, repository, and branch in git:
-    ```python
-    import wandb
+        ```python
+        import wandb
 
-    user = "geoff"
-    project = "capsules"
-    display_name = "experiment-2021-10-31"
+        config = {"lr": 0.01, "batch_size": 32}
+        with wandb.init(config=config) as run:
+            run.config.update({"architecture": "resnet", "depth": 34})
 
-    wandb.init(entity=user, project=project, name=display_name)
-    ```
+            # ... your training code here ...
+        ```
 
-    ### Add metadata about the run to the config
+        Note that you can use `wandb.init()` as a context manager to automatically
+        call `wandb.finish()` at the end of the block.
 
-    Pass a dictionary-style object as the `config` keyword argument to add
-    metadata, like hyperparameters, to your run.
-    <!--yeadoc-test:init-set-config-->
-    ```python
-    import wandb
+    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
+            or team in the UI before starting to log runs. If not specified, the
+            run will default your defualt entity. To change the default entity,
+            go to [your settings](https://wandb.ai/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
+            on the system, such as checking the git root or the current program
+            file. If we can't infer the project name, the project will default to
+            `"uncategorized"`.
+        dir: An absolute path to the directory where metadata and downloaded
+            files will be stored. When calling `download()` on an artifact, files
+            will be saved to this directory. If not specified, this defaults to
+            the `./wandb` directory.
+        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,
+            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
+            allowing easy cross-reference runs from table to charts. Keeping these
+            run names brief enhances readability in chart legends and tables. For
+            saving hyperparameters, we recommend using the `config` field.
+        notes: A detailed description of the run, similar to a commit message in
+            Git. Use this argument to capture any context or details that may
+            help you recall the purpose or setup of this run in the future.
+        tags: A list of tags to label this run in the UI. Tags are helpful for
+            organizing runs or adding temporary identifiers like "baseline" or
+            "production." You can easily add, remove tags, or filter by tags in
+            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()`.
+        config: Sets `wandb.config`, a dictionary-like object for storing input
+            parameters to your run, such as model hyperparameters or data
+            preprocessing settings.
+            The config appears in the UI in an overview page, allowing you to
+            group, filter, and sort runs based on these parameters.
+            Keys should not contain periods (`.`), and values should be
+            smaller than 10 MB.
+            If a dictionary, `argparse.Namespace`, or `absl.flags.FLAGS` is
+            provided, the key-value pairs will be loaded directly into
+            `wandb.config`.
+            If a string is provided, it is interpreted as a path to a YAML file,
+            from which configuration values will be loaded into `wandb.config`.
+        config_exclude_keys: A list of specific keys to exclude from `wandb.config`.
+        config_include_keys: A list of specific keys to include in `wandb.config`.
+        allow_val_change: Controls whether config values can be modified after their
+            initial set. By default, an exception is raised if a config value is
+            overwritten. For tracking variables that change during training, such as
+            a learning rate, consider using `wandb.log()` instead. By default, this
+            is `False` in scripts and `True` in Notebook environments.
+        group: Specify a group name to organize individual runs as part of a larger
+            experiment. This is useful for cases like cross-validation or running
+            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.
+        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.
+        reinit: Determines if multiple `wandb.init()` calls can start new runs
+            within the same process. By default (`False`), if an active run
+            exists, calling `wandb.init()` returns the existing run instead of
+            creating a new one. When `reinit=True`, the active run is finished
+            before a new run is initialized. In notebook environments, runs are
+            reinitialized by default unless `reinit` is explicitly set to `False`.
+        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
+            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
+            from that step. The target run must be in the same project.
+            If an `id` argument is also provided, the `resume_from` argument will
+            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.
+        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.
+            The target run must be part of the current project.
+            If an `id` argument is also provided, it must be different from the
+            `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.
+        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).
+        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).
+        settings: Specifies a dictionary or `wandb.Settings` object with advanced
+            settings for the run.
 
-    config = {"lr": 3e-4, "batch_size": 32}
-    config.update({"architecture": "resnet", "depth": 34})
-    wandb.init(config=config)
-    ```
+    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.
 
     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 WandB server.
-        UsageError: if the user provided invalid arguments.
-        KeyboardInterrupt: if user interrupts the run.
-
-    Returns:
-        A `Run` object.
+        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.
     """
     ...
 
@@ -520,12 +520,14 @@ def log(
     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,
-    })
+    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})`

wandb/apis/attrs.py

@@ -1,7 +1,8 @@
 from typing import Any, MutableMapping
 
 import wandb
-from wandb.sdk.lib import ipython
+
+from ..sdk.lib import ipython
 
 
 class Attrs:
@@ -14,14 +15,24 @@ class Attrs:
 
     def display(self, height=420, hidden=False) -> bool:
         """Display this object in jupyter."""
+        if wandb.run and wandb.run._settings.silent:
+            return False
+
+        if not ipython.in_jupyter():
+            return False
+
         html = self.to_html(height, hidden)
         if html is None:
             wandb.termwarn("This object does not support `.display()`")
             return False
-        if ipython.in_jupyter():
-            ipython.display_html(html)
+
+        try:
+            from IPython import display
+
+            display.display(display.HTML(html))
             return True
-        else:
+
+        except ImportError:
             wandb.termwarn(".display() only works in jupyter environments")
             return False
 

wandb/apis/public/api.py

@@ -912,7 +912,12 @@ class Api:
             ```
             api.runs(
                 path="my_entity/my_project",
-                filters={"$or": [{"config.experiment_name": "foo"}, {"config.experiment_name": "bar"}]}
+                filters={
+                    "$or": [
+                        {"config.experiment_name": "foo"},
+                        {"config.experiment_name": "bar"},
+                    ]
+                },
             )
             ```
 
@@ -920,15 +925,14 @@ class Api:
             ```
             api.runs(
                 path="my_entity/my_project",
-                filters={"config.experiment_name": {"$regex": "b.*"}}
+                filters={"config.experiment_name": {"$regex": "b.*"}},
             )
             ```
 
             Find runs in my_project where the run name matches a regex (anchors are not supported)
             ```
             api.runs(
-                path="my_entity/my_project",
-                filters={"display_name": {"$regex": "^foo.*"}}
+                path="my_entity/my_project", filters={"display_name": {"$regex": "^foo.*"}}
             )
             ```