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

wandb/sdk/wandb_settings.py

@@ -162,7 +162,7 @@ class Settings(BaseModel, validate_assignment=True):
     This class manages configuration settings for the W&B SDK,
     ensuring type safety and validation of all settings. Settings are accessible
     as attributes and can be initialized programmatically, through environment
-    variables (WANDB_ prefix), and via configuration files.
+    variables (`WANDB_ prefix`), and with configuration files.
 
     The settings are organized into three categories:
     1. Public settings: Core configuration options that users can safely modify to customize
@@ -230,7 +230,7 @@ class Settings(BaseModel, validate_assignment=True):
     """The type of console capture to be applied.
 
     Possible values are:
-     "auto" - Automatically selects the console capture method based on the
+      "auto" - Automatically selects the console capture method based on the
       system environment and settings.
 
       "off" - Disables console capture.
@@ -955,6 +955,10 @@ class Settings(BaseModel, validate_assignment=True):
 
         @model_validator(mode="after")
         def validate_mutual_exclusion_of_branching_args(self) -> Self:
+            """Check if `fork_from`, `resume`, and `resume_from` are mutually exclusive.
+
+            <!-- lazydoc-ignore: internal -->
+            """
             if (
                 sum(
                     o is not None
@@ -1002,6 +1006,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("api_key", mode="after")
     @classmethod
     def validate_api_key(cls, value):
+        """Validate the API key.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if value is not None and (len(value) > len(value.strip())):
             raise UsageError("API key cannot start or end with whitespace")
         return value
@@ -1009,6 +1017,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("base_url", mode="after")
     @classmethod
     def validate_base_url(cls, value):
+        """Validate the base URL.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         validate_url(value)
         # wandb.ai-specific checks
         if re.match(r".*wandb\.ai[^\.]*$", value) and "api." not in value:
@@ -1023,6 +1035,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("code_dir", mode="before")
     @classmethod
     def validate_code_dir(cls, value):
+        """Validate the code directory.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1031,6 +1047,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("console", mode="after")
     @classmethod
     def validate_console(cls, value, values):
+        """Validate the console capture method.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if value != "auto":
             return value
 
@@ -1039,6 +1059,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("x_executable", mode="before")
     @classmethod
     def validate_x_executable(cls, value):
+        """Validate the Python executable path.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1054,6 +1078,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("x_file_stream_max_line_bytes", mode="after")
     @classmethod
     def validate_file_stream_max_line_bytes(cls, value):
+        """Validate the maximum line length for filestream JSONL files.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if value is not None and value < 1:
             raise ValueError("File stream max line bytes must be greater than 0")
         return value
@@ -1061,6 +1089,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("x_files_dir", mode="before")
     @classmethod
     def validate_x_files_dir(cls, value):
+        """Validate the files directory.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1069,6 +1101,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("fork_from", mode="before")
     @classmethod
     def validate_fork_from(cls, value, values) -> Optional[RunMoment]:
+        """Validate the fork_from field.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         run_moment = cls._runmoment_preprocessor(value)
 
         if hasattr(values, "data"):
@@ -1093,6 +1129,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("http_proxy", mode="after")
     @classmethod
     def validate_http_proxy(cls, value):
+        """Validate the HTTP proxy.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if value is None:
             return None
         validate_url(value)
@@ -1101,6 +1141,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("https_proxy", mode="after")
     @classmethod
     def validate_https_proxy(cls, value):
+        """Validate the HTTPS proxy.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if value is None:
             return None
         validate_url(value)
@@ -1109,11 +1153,19 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("ignore_globs", mode="after")
     @classmethod
     def validate_ignore_globs(cls, value):
+        """Validate the ignore globs.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         return tuple(value) if not isinstance(value, tuple) else value
 
     @field_validator("program", mode="before")
     @classmethod
     def validate_program(cls, value):
+        """Validate the program path.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1122,6 +1174,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("program_abspath", mode="before")
     @classmethod
     def validate_program_abspath(cls, value):
+        """Validate the absolute program path.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1130,6 +1186,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("program_relpath", mode="before")
     @classmethod
     def validate_program_relpath(cls, value):
+        """Validate the relative program path.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1138,6 +1198,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("project", mode="after")
     @classmethod
     def validate_project(cls, value, values):
+        """Validate the project name.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if value is None:
             return None
         invalid_chars_list = list("/\\#?%:")
@@ -1155,6 +1219,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("resume", mode="before")
     @classmethod
     def validate_resume(cls, value):
+        """Validate the resume behavior.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if value is False:
             return None
         if value is True:
@@ -1164,6 +1232,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("resume_from", mode="before")
     @classmethod
     def validate_resume_from(cls, value, values) -> Optional[RunMoment]:
+        """Validate the resume_from field.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         run_moment = cls._runmoment_preprocessor(value)
 
         if hasattr(values, "data"):
@@ -1186,6 +1258,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("root_dir", mode="before")
     @classmethod
     def validate_root_dir(cls, value):
+        """Validate the root directory.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1194,6 +1270,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("run_id", mode="after")
     @classmethod
     def validate_run_id(cls, value, values):
+        """Validate the run ID.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if value is None:
             return None
 
@@ -1213,6 +1293,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("settings_system", mode="after")
     @classmethod
     def validate_settings_system(cls, value):
+        """Validate the system settings file path.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if value is None:
             return None
         elif isinstance(value, pathlib.Path):
@@ -1223,6 +1307,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("x_service_wait", mode="after")
     @classmethod
     def validate_service_wait(cls, value):
+        """Validate the service wait time.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if value < 0:
             raise UsageError("Service wait time cannot be negative")
         return value
@@ -1230,6 +1318,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("start_method", mode="after")
     @classmethod
     def validate_start_method(cls, value):
+        """Validate the start method for subprocesses.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if value is None:
             return value
         wandb.termwarn(
@@ -1248,6 +1340,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("x_stats_gpu_device_ids", mode="before")
     @classmethod
     def validate_x_stats_gpu_device_ids(cls, value):
+        """Validate the GPU device IDs.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if isinstance(value, str):
             return json.loads(value)
         return value
@@ -1255,6 +1351,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("x_stats_neuron_monitor_config_path", mode="before")
     @classmethod
     def validate_x_stats_neuron_monitor_config_path(cls, value):
+        """Validate the path to the neuron-monitor config file.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1263,6 +1363,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("x_stats_open_metrics_endpoints", mode="before")
     @classmethod
     def validate_stats_open_metrics_endpoints(cls, value):
+        """Validate the OpenMetrics endpoints.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if isinstance(value, str):
             return json.loads(value)
         return value
@@ -1270,6 +1374,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("x_stats_open_metrics_filters", mode="before")
     @classmethod
     def validate_stats_open_metrics_filters(cls, value):
+        """Validate the OpenMetrics filters.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if isinstance(value, str):
             return json.loads(value)
         return value
@@ -1277,6 +1385,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("x_stats_open_metrics_http_headers", mode="before")
     @classmethod
     def validate_stats_open_metrics_http_headers(cls, value):
+        """Validate the OpenMetrics HTTP headers.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if isinstance(value, str):
             return json.loads(value)
         return value
@@ -1284,6 +1396,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("x_stats_sampling_interval", mode="after")
     @classmethod
     def validate_stats_sampling_interval(cls, value):
+        """Validate the stats sampling interval.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if value < 0.1:
             raise UsageError("Stats sampling interval cannot be less than 0.1 seconds")
         return value
@@ -1291,6 +1407,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("sweep_id", mode="after")
     @classmethod
     def validate_sweep_id(cls, value):
+        """Validate the sweep ID.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if value is None:
             return None
         if len(value) == 0:
@@ -1304,6 +1424,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("sweep_param_path", mode="before")
     @classmethod
     def validate_sweep_param_path(cls, value):
+        """Validate the sweep parameter path.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1503,6 +1627,7 @@ class Settings(BaseModel, validate_assignment=True):
     @computed_field  # type: ignore[prop-decorator]
     @property
     def run_mode(self) -> Literal["run", "offline-run"]:
+        """The mode of the run. Can be either "run" or "offline-run"."""
         return "run" if not self._offline else "offline-run"
 
     @computed_field  # type: ignore[prop-decorator]
@@ -1538,6 +1663,7 @@ class Settings(BaseModel, validate_assignment=True):
     @computed_field  # type: ignore[prop-decorator]
     @property
     def sync_dir(self) -> str:
+        """The directory for storing the run's files."""
         return _path_convert(
             self.wandb_dir,
             f"{self.run_mode}-{self.timespec}-{self.run_id}",
@@ -1552,11 +1678,13 @@ class Settings(BaseModel, validate_assignment=True):
     @computed_field  # type: ignore[prop-decorator]
     @property
     def sync_symlink_latest(self) -> str:
+        """Path to the symlink to the most recent run's transaction log file."""
         return _path_convert(self.wandb_dir, "latest-run")
 
     @computed_field  # type: ignore[prop-decorator]
     @property
     def timespec(self) -> str:
+        """The time specification for the run."""
         return self._start_datetime
 
     @computed_field  # type: ignore[prop-decorator]

wandb/sdk/wandb_setup.py

@@ -419,49 +419,49 @@ def setup(settings: Settings | None = None) -> _WandbSetup:
             overridden by subsequent `wandb.init()` calls.
 
     Example:
-        ```python
-        import multiprocessing
+    ```python
+    import multiprocessing
 
-        import wandb
+    import wandb
 
 
-        def run_experiment(params):
-            with wandb.init(config=params):
-                # Run experiment
-                pass
+    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"})
+    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},
-            ]
+        # 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)
+        # 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()
+        # Wait for all processes to complete
+        for p in processes:
+            p.join()
 
-            # Optional: Explicitly shut down the backend
-            wandb.teardown()
-        ```
+        # Optional: Explicitly shut down the backend
+        wandb.teardown()
+    ```
     """
     return _setup(settings=settings)
 
 
 @wb_logging.log_to_all_runs()
 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.

wandb/sdk/wandb_sweep.py

@@ -45,11 +45,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.
@@ -64,7 +65,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.
     """
     if callable(sweep):
         sweep = sweep()
@@ -99,16 +100,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(...)
+    ```
 
     """
     from ..wandb_controller import _WandbController

wandb/sdk/wandb_watch.py

@@ -17,15 +17,13 @@ from .lib import telemetry
 if TYPE_CHECKING:
     import torch  # type: ignore [import-not-found]
 
-    from wandb.sdk.wandb_run import Run
-
 logger = logging.getLogger("wandb")
 
 _global_watch_idx = 0
 
 
 def _watch(
-    run: Run,
+    run: wandb.Run,
     models: torch.nn.Module | Sequence[torch.nn.Module],
     criterion: torch.F | None = None,
     log: Literal["gradients", "parameters", "all"] | None = "gradients",
@@ -39,7 +37,7 @@ def _watch(
     extended to support arbitrary machine learning models in the future.
 
     Args:
-        run (wandb.sdk.wandb_run.Run): The run object to log to.
+        run (wandb.Run): The run object to log to.
         models (Union[torch.nn.Module, Sequence[torch.nn.Module]]):
             A single model or a sequence of models to be monitored.
         criterion (Optional[torch.F]):
@@ -122,12 +120,12 @@ def _watch(
 
 
 def _unwatch(
-    run: Run, models: torch.nn.Module | Sequence[torch.nn.Module] | None = None
+    run: wandb.Run, models: torch.nn.Module | Sequence[torch.nn.Module] | None = None
 ) -> None:
     """Remove pytorch model topology, gradient and parameter hooks.
 
     Args:
-        run (wandb.sdk.wandb_run.Run):
+        run (wandb.Run):
             The run object to log to.
         models (torch.nn.Module | Sequence[torch.nn.Module]):
             Optional list of pytorch models that have had watch called on them

wandb/sync/sync.py

@@ -54,6 +54,7 @@ class SyncThread(threading.Thread):
         log_path=None,
         append=None,
         skip_console=None,
+        replace_tags=None,
     ):
         threading.Thread.__init__(self)
         # mark this process as internal
@@ -71,6 +72,7 @@ class SyncThread(threading.Thread):
         self._log_path = log_path
         self._append = append
         self._skip_console = skip_console
+        self._replace_tags = replace_tags or {}
 
         self._tmp_dir = tempfile.TemporaryDirectory()
         atexit.register(self._tmp_dir.cleanup)
@@ -94,6 +96,11 @@ class SyncThread(threading.Thread):
                 pb.run.entity = self._entity
             if self._job_type:
                 pb.run.job_type = self._job_type
+            # Replace tags if specified
+            if self._replace_tags:
+                new_tags = [self._replace_tags.get(tag, tag) for tag in pb.run.tags]
+                pb.run.ClearField("tags")
+                pb.run.tags.extend(new_tags)
             pb.control.req_resp = True
         elif record_type in ("output", "output_raw") and self._skip_console:
             return pb, exit_pb, True
@@ -338,6 +345,7 @@ class SyncManager:
         log_path=None,
         append=None,
         skip_console=None,
+        replace_tags=None,
     ):
         self._sync_list = []
         self._thread = None
@@ -353,6 +361,7 @@ class SyncManager:
         self._log_path = log_path
         self._append = append
         self._skip_console = skip_console
+        self._replace_tags = replace_tags or {}
 
     def status(self):
         pass
@@ -376,6 +385,7 @@ class SyncManager:
             log_path=self._log_path,
             append=self._append,
             skip_console=self._skip_console,
+            replace_tags=self._replace_tags,
         )
         self._thread.start()
 

wandb/util.py

@@ -341,6 +341,63 @@ def get_local_path_or_none(path_or_uri: str) -> Optional[str]:
         return None
 
 
+def check_windows_valid_filename(path: Union[int, str]) -> bool:
+    r"""Verify that the given path does not contain any invalid characters for a Windows filename.
+
+    Windows filenames cannot contain the following characters:
+    < > : " \ / | ? *
+
+    For more details, refer to the official documentation:
+    https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions
+
+    Args:
+        path: The file path to check, which can be either an integer or a string.
+
+    Returns:
+        bool: True if the path does not contain any invalid characters, False otherwise.
+    """
+    return not bool(re.search(r'[<>:"\\?*]', path))  # type: ignore
+
+
+def make_file_path_upload_safe(path: str) -> str:
+    r"""Makes the provide path safe for file upload.
+
+    The filename is made safe by:
+    1. Removing any leading slashes to prevent writing to absolute paths
+    2. Replacing '.' and '..' with underscores to prevent directory traversal attacks
+
+    Raises:
+        ValueError: If running on Windows and the key contains invalid filename characters
+                   (\, :, *, ?, ", <, >, |)
+    """
+    sys_platform = platform.system()
+    if sys_platform == "Windows" and not check_windows_valid_filename(path):
+        raise ValueError(
+            f"Path {path} is invalid. Please remove invalid filename characters"
+            r' (\, :, *, ?, ", <, >, |)'
+        )
+
+    # On Windows, convert forward slashes to backslashes.
+    # This ensures that the key is a valid filename on Windows.
+    if sys_platform == "Windows":
+        path = str(path).replace("/", os.sep)
+
+    # Avoid writing to absolute paths by striping any leading slashes.
+    # The key has already been validated for windows operating systems in util.check_windows_valid_filename
+    # This ensures the key does not contain invalid characters for windows, such as '\' or ':'.
+    # So we can check only for '/' in the key.
+    path = path.lstrip(os.sep)
+
+    # Avoid directory traversal by replacing dots with underscores.
+    paths = path.split(os.sep)
+    safe_paths = [
+        p.replace(".", "_") if p in (os.curdir, os.pardir) else p for p in paths
+    ]
+
+    # Recombine the key into a relative path.
+    return os.sep.join(safe_paths)
+
+
 def make_tarfile(
     output_filename: str,
     source_dir: str,

wandb/wandb_run.py

@@ -1,7 +1,6 @@
 """Compatibility wandb_run module.
 
-In the future use:
-    from wandb.sdk.wandb_run import Run
+Please use `wandb.Run` instead.
 """
 
 from wandb.sdk.wandb_run import Run

{wandb-0.21.0.dist-info → wandb-0.21.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: wandb
-Version: 0.21.0
+Version: 0.21.1
 Summary: A CLI and library for interacting with the Weights & Biases API.
 Project-URL: Source, https://github.com/wandb/wandb
 Project-URL: Bug Reports, https://github.com/wandb/wandb/issues