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

wandb/sdk/wandb_settings.py

@@ -156,13 +156,21 @@ def _path_convert(*args: str) -> str:
     return os.path.expanduser(os.path.join(*args))
 
 
+CLIENT_ONLY_SETTINGS = (
+    "reinit",
+    "max_end_of_run_history_metrics",
+    "max_end_of_run_summary_metrics",
+)
+"""Python-only keys that are not fields on the settings proto."""
+
+
 class Settings(BaseModel, validate_assignment=True):
     """Settings for the W&B SDK.
 
     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 +238,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.
@@ -469,6 +477,12 @@ class Settings(BaseModel, validate_assignment=True):
     settings_system: Optional[str] = None
     """Path to the system-wide settings file."""
 
+    max_end_of_run_history_metrics: int = 10
+    """Maximum number of history sparklines to display at the end of a run."""
+
+    max_end_of_run_summary_metrics: int = 10
+    """Maximum number of summary metrics to display at the end of a run."""
+
     show_colors: Optional[bool] = None
     """Whether to use colored output in the console.
 
@@ -955,6 +969,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 +1020,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-classmethod: 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 +1031,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-classmethod: internal -->
+        """
         validate_url(value)
         # wandb.ai-specific checks
         if re.match(r".*wandb\.ai[^\.]*$", value) and "api." not in value:
@@ -1023,6 +1049,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-classmethod: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1031,6 +1061,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-classmethod: internal -->
+        """
         if value != "auto":
             return value
 
@@ -1039,6 +1073,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-classmethod: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1054,6 +1092,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-classmethod: 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 +1103,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-classmethod: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1069,6 +1115,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-classmethod: internal -->
+        """
         run_moment = cls._runmoment_preprocessor(value)
 
         if hasattr(values, "data"):
@@ -1093,6 +1143,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-classmethod: internal -->
+        """
         if value is None:
             return None
         validate_url(value)
@@ -1101,6 +1155,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-classmethod: internal -->
+        """
         if value is None:
             return None
         validate_url(value)
@@ -1109,11 +1167,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-classmethod: 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-classmethod: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1122,6 +1188,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-classmethod: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1130,6 +1200,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-classmethod: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1138,6 +1212,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-classmethod: internal -->
+        """
         if value is None:
             return None
         invalid_chars_list = list("/\\#?%:")
@@ -1155,6 +1233,10 @@ class Settings(BaseModel, validate_assignment=True):
     @field_validator("resume", mode="before")
     @classmethod
     def validate_resume(cls, value):
+        """Validate the resume behavior.
+
+        <!-- lazydoc-ignore-classmethod: internal -->
+        """
         if value is False:
             return None
         if value is True:
@@ -1164,6 +1246,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-classmethod: internal -->
+        """
         run_moment = cls._runmoment_preprocessor(value)
 
         if hasattr(values, "data"):
@@ -1186,6 +1272,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-classmethod: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1194,6 +1284,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-classmethod: internal -->
+        """
         if value is None:
             return None
 
@@ -1213,6 +1307,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-classmethod: internal -->
+        """
         if value is None:
             return None
         elif isinstance(value, pathlib.Path):
@@ -1223,6 +1321,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-classmethod: internal -->
+        """
         if value < 0:
             raise UsageError("Service wait time cannot be negative")
         return value
@@ -1230,6 +1332,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-classmethod: internal -->
+        """
         if value is None:
             return value
         wandb.termwarn(
@@ -1248,6 +1354,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-classmethod: internal -->
+        """
         if isinstance(value, str):
             return json.loads(value)
         return value
@@ -1255,6 +1365,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-classmethod: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1263,6 +1377,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-classmethod: internal -->
+        """
         if isinstance(value, str):
             return json.loads(value)
         return value
@@ -1270,6 +1388,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-classmethod: internal -->
+        """
         if isinstance(value, str):
             return json.loads(value)
         return value
@@ -1277,6 +1399,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-classmethod: internal -->
+        """
         if isinstance(value, str):
             return json.loads(value)
         return value
@@ -1284,6 +1410,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-classmethod: internal -->
+        """
         if value < 0.1:
             raise UsageError("Stats sampling interval cannot be less than 0.1 seconds")
         return value
@@ -1291,6 +1421,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-classmethod: internal -->
+        """
         if value is None:
             return None
         if len(value) == 0:
@@ -1304,6 +1438,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-classmethod: internal -->
+        """
         # TODO: add native support for pathlib.Path
         if isinstance(value, pathlib.Path):
             return str(value)
@@ -1503,6 +1641,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 +1677,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 +1692,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]
@@ -1729,8 +1871,7 @@ class Settings(BaseModel, validate_assignment=True):
         """Generate a protobuf representation of the settings."""
         settings_proto = wandb_settings_pb2.Settings()
         for k, v in self.model_dump(exclude_none=True).items():
-            # Client-only settings that don't exist on the protobuf.
-            if k in ("reinit",):
+            if k in CLIENT_ONLY_SETTINGS:
                 continue
 
             # Special case for x_stats_open_metrics_filters.