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

wandb/sdk/data_types/audio.py

@@ -15,15 +15,7 @@ if TYPE_CHECKING:
 
 
 class Audio(BatchableMedia):
-    """Wandb class for audio clips.
-
-    Args:
-        data_or_path: (string or numpy array) A path to an audio file
-            or a numpy array of audio data.
-        sample_rate: (int) Sample rate, required when passing in raw
-            numpy array of audio data.
-        caption: (string) Caption to display with audio.
-    """
+    """W&B class for audio clips."""
 
     _log_type = "audio-file"
 
@@ -38,7 +30,13 @@ class Audio(BatchableMedia):
         sample_rate: Optional[int] = None,
         caption: Optional[str] = None,
     ):
-        """Accept a path to an audio file or a numpy array of audio data."""
+        """Accept a path to an audio file or a numpy array of audio data.
+
+        Args:
+            data_or_path: A path to an audio file or a NumPy array of audio data.
+            sample_rate: Sample rate, required when passing in raw NumPy array of audio data.
+            caption: Caption to display with audio.
+        """
         super().__init__(caption=caption)
         self._duration = None
         self._sample_rate = sample_rate
@@ -72,10 +70,18 @@ class Audio(BatchableMedia):
 
     @classmethod
     def get_media_subdir(cls):
+        """Get media subdirectory.
+
+        <!-- lazydoc-ignore-classmethod: internal -->
+        """
         return os.path.join("media", "audio")
 
     @classmethod
     def from_json(cls, json_obj, source_artifact):
+        """Deserialize JSON object into it's class representation.
+
+        <!-- lazydoc-ignore-classmethod: internal -->
+        """
         return cls(
             source_artifact.get_entry(json_obj["path"]).download(),
             caption=json_obj["caption"],
@@ -84,6 +90,10 @@ class Audio(BatchableMedia):
     def bind_to_run(
         self, run, key, step, id_=None, ignore_copy_err: Optional[bool] = None
     ):
+        """Bind this object to a run.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if self.path_is_reference(self._path):
             raise ValueError(
                 "Audio media created by a reference to external storage cannot currently be added to a run"
@@ -92,6 +102,10 @@ class Audio(BatchableMedia):
         return super().bind_to_run(run, key, step, id_, ignore_copy_err)
 
     def to_json(self, run):
+        """Returns the JSON representation expected by the backend.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         json_dict = super().to_json(run)
         json_dict.update(
             {
@@ -102,6 +116,10 @@ class Audio(BatchableMedia):
 
     @classmethod
     def seq_to_json(cls, seq, run, key, step):
+        """Convert a sequence of Audio objects to a JSON representation.
+
+        <!-- lazydoc-ignore-classmethod: internal -->
+        """
         audio_list = list(seq)
 
         util.get_module(
@@ -129,14 +147,20 @@ class Audio(BatchableMedia):
 
     @classmethod
     def durations(cls, audio_list):
+        """Calculate the duration of the audio files."""
         return [a._duration for a in audio_list]
 
     @classmethod
     def sample_rates(cls, audio_list):
+        """Get sample rates of the audio files."""
         return [a._sample_rate for a in audio_list]
 
     @classmethod
     def captions(cls, audio_list):
+        """Get the captions of the audio files.
+
+        <!-- lazydoc-ignore-classmethod: internal -->
+        """
         captions = [a._caption for a in audio_list]
         if all(c is None for c in captions):
             return False
@@ -144,6 +168,10 @@ class Audio(BatchableMedia):
             return ["" if c is None else c for c in captions]
 
     def resolve_ref(self):
+        """Resolve the reference to the actual file path.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if self.path_is_reference(self._path):
             # this object was already created using a ref:
             return self._path

wandb/sdk/data_types/base_types/media.py

@@ -1,7 +1,6 @@
 import hashlib
 import os
 import pathlib
-import platform
 import re
 import shutil
 from typing import TYPE_CHECKING, Any, Dict, Optional, Sequence, Type, Union, cast
@@ -18,39 +17,12 @@ if TYPE_CHECKING:  # pragma: no cover
 
     from wandb.sdk.artifacts.artifact import Artifact
 
-    from ...wandb_run import Run as LocalRun
-
-
-SYS_PLATFORM = platform.system()
-
-
-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 _wb_filename(
     key: Union[str, int], step: Union[str, int], id: Union[str, int], extension: str
 ) -> str:
     r"""Generates a safe filename/path for storing media files, using the provided key, step, and id.
 
-    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
-
     If the key contains slashes (e.g. 'images/cats/fluffy.jpg'), subdirectories will be created:
         media/
           images/
@@ -70,28 +42,7 @@ def _wb_filename(
         ValueError: If running on Windows and the key contains invalid filename characters
                    (\\, :, *, ?, ", <, >, |)
     """
-    if SYS_PLATFORM == "Windows" and not check_windows_valid_filename(key):
-        raise ValueError(
-            f'Media {key} is invalid. Please remove invalid filename characters (\\, :, *, ?, ", <, >, |)'
-        )
-
-    # On Windows, convert forward slashes to backslashes.
-    # This ensures that the key is a valid filename on Windows.
-    if SYS_PLATFORM == "Windows":
-        key = str(key).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.
-    key = str(key).lstrip(os.sep)
-
-    # Avoid directory traversal by replacing dots with underscores.
-    keys = key.split(os.sep)
-    keys = [k.replace(".", "_") if k in (os.curdir, os.pardir) else k for k in keys]
-
-    # Recombine the key into a relative path.
-    key = os.sep.join(keys)
+    key = util.make_file_path_upload_safe(str(key))
 
     return f"{str(key)}_{str(step)}_{str(id)}{extension}"
 
@@ -104,7 +55,7 @@ class Media(WBValue):
     """
 
     _path: Optional[str]
-    _run: Optional["LocalRun"]
+    _run: Optional["wandb.Run"]
     _caption: Optional[str]
     _is_tmp: Optional[bool]
     _extension: Optional[str]
@@ -127,9 +78,9 @@ class Media(WBValue):
         self._path = path
         self._is_tmp = is_tmp
         self._extension = extension
-        assert extension is None or path.endswith(
-            extension
-        ), f'Media file extension "{extension}" must occur at the end of path "{path}".'
+        assert extension is None or path.endswith(extension), (
+            f'Media file extension "{extension}" must occur at the end of path "{path}".'
+        )
 
         with open(self._path, "rb") as f:
             self._sha256 = hashlib.sha256(f.read()).hexdigest()
@@ -156,7 +107,7 @@ class Media(WBValue):
 
     def bind_to_run(
         self,
-        run: "LocalRun",
+        run: "wandb.Run",
         key: Union[int, str],
         step: Union[int, str],
         id_: Optional[Union[int, str]] = None,
@@ -205,7 +156,7 @@ class Media(WBValue):
             self._path = new_path
             run._publish_file(media_path)
 
-    def to_json(self, run: Union["LocalRun", "Artifact"]) -> dict:
+    def to_json(self, run: Union["wandb.Run", "Artifact"]) -> dict:
         """Serialize the object into a JSON blob.
 
         Uses run or artifact to store additional data. If `run_or_artifact` is a
@@ -223,14 +174,13 @@ class Media(WBValue):
         # into Media itself we should get rid of them
         from wandb import Image
         from wandb.data_types import Audio
-        from wandb.sdk.wandb_run import Run
 
         json_obj: Dict[str, Any] = {}
 
         if self._caption is not None:
             json_obj["caption"] = self._caption
 
-        if isinstance(run, Run):
+        if isinstance(run, wandb.Run):
             json_obj.update(
                 {
                     "_type": "file",  # TODO(adrian): This isn't (yet) a real media type we support on the frontend.
@@ -247,11 +197,13 @@ class Media(WBValue):
                 json_obj["_latest_artifact_path"] = artifact_entry_latest_url
 
             if artifact_entry_url is None or self.is_bound():
-                assert self.is_bound(), f"Value of type {type(self).__name__} must be bound to a run with bind_to_run() before being serialized to JSON."
+                assert self.is_bound(), (
+                    f"Value of type {type(self).__name__} must be bound to a run with bind_to_run() before being serialized to JSON."
+                )
 
-                assert (
-                    self._run is run
-                ), "We don't support referring to media files across runs."
+                assert self._run is run, (
+                    "We don't support referring to media files across runs."
+                )
 
                 # The following two assertions are guaranteed to pass
                 # by definition is_bound, but are needed for
@@ -355,7 +307,7 @@ class BatchableMedia(Media):
     def seq_to_json(
         cls: Type["BatchableMedia"],
         seq: Sequence["BatchableMedia"],
-        run: "LocalRun",
+        run: "wandb.Run",
         key: str,
         step: Union[int, str],
     ) -> dict:

wandb/sdk/data_types/base_types/wb_value.py

@@ -218,17 +218,17 @@ class WBValue:
     def _set_artifact_source(
         self, artifact: "Artifact", name: Optional[str] = None
     ) -> None:
-        assert (
-            self._artifact_source is None
-        ), f"Cannot update artifact_source. Existing source: {self._artifact_source.artifact}/{self._artifact_source.name}"
+        assert self._artifact_source is None, (
+            f"Cannot update artifact_source. Existing source: {self._artifact_source.artifact}/{self._artifact_source.name}"
+        )
         self._artifact_source = _WBValueArtifactSource(artifact, name)
 
     def _set_artifact_target(
         self, artifact: "Artifact", name: Optional[str] = None
     ) -> None:
-        assert (
-            self._artifact_target is None
-        ), f"Cannot update artifact_target. Existing target: {self._artifact_target.artifact}/{self._artifact_target.name}"
+        assert self._artifact_target is None, (
+            f"Cannot update artifact_target. Existing target: {self._artifact_target.artifact}/{self._artifact_target.name}"
+        )
         self._artifact_target = _WBValueArtifactTarget(artifact, name)
 
     def _get_artifact_entry_ref_url(self) -> Optional[str]:

wandb/sdk/data_types/graph.py

@@ -243,25 +243,29 @@ class Node(WBValue):
 
 
 class Graph(Media):
-    """Wandb class for graphs.
+    """W&B class for graphs.
 
-    This class is typically used for saving and displaying neural net models.  It
-    represents the graph as an array of nodes and edges.  The nodes can have
+    This class is typically used for saving and displaying neural net models.
+    It represents the graph as an array of nodes and edges. The nodes can have
     labels that can be visualized by wandb.
 
-    Examples:
-        Import a keras model:
-        ```
-        Graph.from_keras(keras_model)
-        ```
-
     Attributes:
         format (string): Format to help wandb display the graph nicely.
-        nodes ([wandb.Node]): List of wandb.Nodes
+        nodes ([wandb.Node]): List of `wandb.Nodes`.
         nodes_by_id (dict): dict of ids -> nodes
-        edges ([(wandb.Node, wandb.Node)]): List of pairs of nodes interpreted as edges
-        loaded (boolean): Flag to tell whether the graph is completely loaded
-        root (wandb.Node): root node of the graph
+        edges ([(wandb.Node, wandb.Node)]): List of pairs of nodes interpreted
+            as edges.
+        loaded (boolean): Flag to tell whether the graph is completely loaded.
+        root (wandb.Node): Root node of the graph.
+
+    Examples:
+    Import a keras model.
+
+    ```python
+    import wandb
+
+    wandb.Graph.from_keras(keras_model)
+    ```
     """
 
     _log_type = "graph-file"
@@ -287,6 +291,10 @@ class Graph(Media):
         }
 
     def bind_to_run(self, *args, **kwargs):
+        """Bind this object to a run.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         data = self._to_graph_json()
         tmp_path = os.path.join(MEDIA_TMP.name, runid.generate_id() + ".graph.json")
         data = _numpy_arrays_to_lists(data)
@@ -299,9 +307,17 @@ class Graph(Media):
 
     @classmethod
     def get_media_subdir(cls):
+        """Get media subdirectory.
+
+        "<!-- lazydoc-ignore-classmethod: internal -->
+        """
         return os.path.join("media", "graph")
 
     def to_json(self, run):
+        """Returns the JSON representation expected by the backend.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         json_dict = super().to_json(run)
         json_dict["_type"] = self._log_type
         return json_dict
@@ -310,12 +326,20 @@ class Graph(Media):
         return self.nodes_by_id[nid]
 
     def pprint(self):
+        """Pretty print the graph.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         for edge in self.edges:
             pprint.pprint(edge.attributes)  # noqa: T203
         for node in self.nodes:
             pprint.pprint(node.attributes)  # noqa: T203
 
     def add_node(self, node=None, **node_kwargs):
+        """Add a node to the graph.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if node is None:
             node = Node(**node_kwargs)
         elif node_kwargs:
@@ -328,6 +352,10 @@ class Graph(Media):
         return node
 
     def add_edge(self, from_node, to_node):
+        """Add an edge to the graph.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         edge = Edge(from_node, to_node)
         self.edges.append(edge)
 
@@ -335,7 +363,13 @@ class Graph(Media):
 
     @classmethod
     def from_keras(cls, model):
-        # TODO: his method requires a refactor to work with the keras 3.
+        """Create a graph from a Keras model.
+
+        This method is not supported for Keras 3.0.0 and above.
+        Requires a refactor.
+
+        "<!-- lazydoc-ignore-classmethod: internal -->
+        """
         graph = cls()
         # Shamelessly copied (then modified) from keras/keras/utils/layer_utils.py
         sequential_like = cls._is_sequential(model)

wandb/sdk/data_types/helper_types/bounding_boxes_2d.py

@@ -310,9 +310,7 @@ class BoundingBoxes2D(JSONMetadata):
         return True
 
     def to_json(self, run_or_artifact: Union["LocalRun", "Artifact"]) -> dict:
-        from wandb.sdk.wandb_run import Run
-
-        if isinstance(run_or_artifact, Run):
+        if isinstance(run_or_artifact, wandb.Run):
             return super().to_json(run_or_artifact)
         elif isinstance(run_or_artifact, wandb.Artifact):
             # TODO (tim): I would like to log out a proper dictionary representing this object, but don't

wandb/sdk/data_types/helper_types/image_mask.py

@@ -209,11 +209,9 @@ class ImageMask(Media):
         )
 
     def to_json(self, run_or_artifact: Union["LocalRun", "Artifact"]) -> dict:
-        from wandb.sdk.wandb_run import Run
-
         json_dict = super().to_json(run_or_artifact)
 
-        if isinstance(run_or_artifact, Run):
+        if isinstance(run_or_artifact, wandb.Run):
             json_dict["_type"] = self.type_name()
             return json_dict
         elif isinstance(run_or_artifact, wandb.Artifact):

wandb/sdk/data_types/histogram.py

@@ -16,32 +16,14 @@ if TYPE_CHECKING:  # pragma: no cover
 
 
 class Histogram(WBValue):
-    """wandb class for histograms.
+    """W&B class for histograms.
 
     This object works just like numpy's histogram function
     https://docs.scipy.org/doc/numpy/reference/generated/numpy.histogram.html
 
-    Examples:
-        Generate histogram from a sequence
-        ```python
-        wandb.Histogram([1, 2, 3])
-        ```
-
-        Efficiently initialize from np.histogram.
-        ```python
-        hist = np.histogram(data)
-        wandb.Histogram(np_histogram=hist)
-        ```
-
-    Args:
-        sequence: (array_like) input data for histogram
-        np_histogram: (numpy histogram) alternative input of a precomputed histogram
-        num_bins: (int) Number of bins for the histogram.  The default number of bins
-            is 64.  The maximum number of bins is 512
-
     Attributes:
-        bins: ([float]) edges of bins
-        histogram: ([int]) number of elements falling in each bin
+        bins ([float]): Edges of bins
+        histogram  ([int]): Number of elements falling in each bin.
     """
 
     MAX_LENGTH: int = 512
@@ -53,6 +35,33 @@ class Histogram(WBValue):
         np_histogram: Optional["NumpyHistogram"] = None,
         num_bins: int = 64,
     ) -> None:
+        """Initialize a Histogram object.
+
+        Args:
+        sequence: Input data for histogram.
+        np_histogram: Alternative input of a precomputed histogram.
+        num_bins: Number of bins for the histogram.  The default number of bins
+            is 64. The maximum number of bins is 512.
+
+        Examples:
+        Generate histogram from a sequence.
+
+        ```python
+        import wandb
+
+        wandb.Histogram([1, 2, 3])
+        ```
+
+        Efficiently initialize from np.histogram.
+
+        ```python
+        import numpy as np
+        import wandb
+
+        hist = np.histogram(data)
+        wandb.Histogram(np_histogram=hist)
+        ```
+        """
         if np_histogram:
             if len(np_histogram) == 2:
                 self.histogram = (
@@ -83,6 +92,10 @@ class Histogram(WBValue):
             raise ValueError("len(bins) must be len(histogram) + 1")
 
     def to_json(self, run: Optional[Union["LocalRun", "Artifact"]] = None) -> dict:
+        """Returns the JSON representation expected by the backend.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         return {"_type": self._log_type, "values": self.histogram, "bins": self.bins}
 
     def __sizeof__(self) -> int:

wandb/sdk/data_types/html.py

@@ -17,7 +17,7 @@ if TYPE_CHECKING:  # pragma: no cover
 
 
 class Html(BatchableMedia):
-    """A class for logging HTML content to W&B."""
+    """W&B class for logging HTML content to W&B."""
 
     _log_type = "html-file"
 
@@ -29,27 +29,30 @@ class Html(BatchableMedia):
     ) -> None:
         """Creates a W&B HTML object.
 
+        Args:
+            data:
+                A string that is a path to a file with the extension ".html",
+                or a string or IO object containing literal HTML.
+            inject: Add a stylesheet to the HTML object. If set
+                to False the HTML will pass through unchanged.
+            data_is_not_path: If set to False, the data will be
+                treated as a path to a file.
+
+        Examples:
         It can be initialized by providing a path to a file:
-        ```
+
+        ```python
         with wandb.init() as run:
             run.log({"html": wandb.Html("./index.html")})
         ```
 
         Alternatively, it can be initialized by providing literal HTML,
         in either a string or IO object:
-        ```
+
+        ```python
         with wandb.init() as run:
             run.log({"html": wandb.Html("<h1>Hello, world!</h1>")})
         ```
-
-        Args:
-            data:
-                A string that is a path to a file with the extension ".html",
-                or a string or IO object containing literal HTML.
-            inject: Add a stylesheet to the HTML object. If set
-                to False the HTML will pass through unchanged.
-            data_is_not_path: If set to False, the data will be
-                treated as a path to a file.
         """
         super().__init__()
         data_is_path = (
@@ -84,6 +87,10 @@ class Html(BatchableMedia):
             self._set_file(data_path, is_tmp=False)
 
     def inject_head(self) -> None:
+        """Inject a <head> tag into the HTML.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         join = ""
         if "<head>" in self.html:
             parts = self.html.split("<head>", 1)
@@ -102,9 +109,17 @@ class Html(BatchableMedia):
 
     @classmethod
     def get_media_subdir(cls: Type["Html"]) -> str:
+        """Get media subdirectory.
+
+        "<!-- lazydoc-ignore-classmethod: internal -->
+        """
         return os.path.join("media", "html")
 
     def to_json(self, run_or_artifact: Union["LocalRun", "Artifact"]) -> dict:
+        """Returns the JSON representation expected by the backend.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         json_dict = super().to_json(run_or_artifact)
         json_dict["_type"] = self._log_type
         return json_dict
@@ -113,6 +128,10 @@ class Html(BatchableMedia):
     def from_json(
         cls: Type["Html"], json_obj: dict, source_artifact: "Artifact"
     ) -> "Html":
+        """Deserialize a JSON object into it's class representation.
+
+        "<!-- lazydoc-ignore-classmethod: internal -->
+        """
         return cls(source_artifact.get_entry(json_obj["path"]).download(), inject=False)
 
     @classmethod
@@ -123,6 +142,10 @@ class Html(BatchableMedia):
         key: str,
         step: Union[int, str],
     ) -> dict:
+        """Convert a sequence of HTML objects to a JSON representation.
+
+        "<!-- lazydoc-ignore-classmethod: internal -->
+        """
         base_path = os.path.join(run.dir, cls.get_media_subdir())
         filesystem.mkdir_exists_ok(base_path)