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

wandb/sdk/artifacts/artifact_file_cache.py

@@ -9,6 +9,7 @@ import os
 import shutil
 import subprocess
 import sys
+from functools import lru_cache
 from pathlib import Path
 from tempfile import NamedTemporaryFile
 from typing import IO, ContextManager, Iterator, Protocol
@@ -236,12 +237,15 @@ class ArtifactFileCache:
             ) from e
 
 
-_artifact_file_cache: ArtifactFileCache | None = None
+# Memo `ArtifactFileCache` instances while avoiding reliance on global
+# variable(s).  Notes:
+# - @lru_cache should be thread-safe.
+# - We don't memoize `get_artifact_file_cache` directly, as the cache_dir
+#   may change at runtime.  This is likely rare in practice, though.
+@lru_cache(maxsize=1)
+def _build_artifact_file_cache(cache_dir: StrPath) -> ArtifactFileCache:
+    return ArtifactFileCache(cache_dir)
 
 
 def get_artifact_file_cache() -> ArtifactFileCache:
-    global _artifact_file_cache
-    cache_dir = env.get_cache_dir() / "artifacts"
-    if _artifact_file_cache is None or _artifact_file_cache._cache_dir != cache_dir:
-        _artifact_file_cache = ArtifactFileCache(cache_dir)
-    return _artifact_file_cache
+    return _build_artifact_file_cache(env.get_cache_dir() / "artifacts")

wandb/sdk/artifacts/artifact_manifest.py

@@ -50,10 +50,12 @@ class ArtifactManifest:
 
     def add_entry(self, entry: ArtifactManifestEntry, overwrite: bool = False) -> None:
         path = entry.path
-        if not overwrite:
-            prev_entry = self.entries.get(path)
-            if prev_entry and (entry.digest != prev_entry.digest):
-                raise ValueError(f"Cannot add the same path twice: {path!r}")
+        if (
+            (not overwrite)
+            and (old_entry := self.entries.get(path))
+            and (entry.digest != old_entry.digest)
+        ):
+            raise ValueError(f"Cannot add the same path twice: {path!r}")
         self.entries[path] = entry
 
     def remove_entry(self, entry: ArtifactManifestEntry) -> None:
@@ -67,9 +69,8 @@ class ArtifactManifest:
 
     def get_entries_in_directory(self, directory: str) -> list[ArtifactManifestEntry]:
         return [
-            self.entries[entry_key]
-            for entry_key in self.entries
-            if entry_key.startswith(
-                directory + "/"
-            )  # entries use forward slash even for windows
+            entry
+            for key, entry in self.entries.items()
+            # entry keys (paths) use forward slash even for windows
+            if key.startswith(f"{directory}/")
         ]

wandb/sdk/artifacts/artifact_manifest_entry.py

@@ -40,6 +40,9 @@ if TYPE_CHECKING:
         local_path: str
 
 
+_WB_ARTIFACT_SCHEME = "wandb-artifact"
+
+
 class ArtifactManifestEntry:
     """A single entry in an artifact manifest."""
 
@@ -221,15 +224,11 @@ class ArtifactManifestEntry:
             derived_artifact.add_reference(ref_url)
             ```
         """
-        if self._parent_artifact is None:
-            raise NotImplementedError
-        assert self._parent_artifact.id is not None
-        return (
-            "wandb-artifact://"
-            + b64_to_hex_id(B64MD5(self._parent_artifact.id))
-            + "/"
-            + self.path
-        )
+        if (parent_artifact := self.parent_artifact()) is None:
+            raise ValueError("Parent artifact is not set")
+        elif (parent_id := parent_artifact.id) is None:
+            raise ValueError("Parent artifact ID is not set")
+        return f"{_WB_ARTIFACT_SCHEME}://{b64_to_hex_id(B64MD5(parent_id))}/{self.path}"
 
     def to_json(self) -> ArtifactManifestEntryDict:
         contents: ArtifactManifestEntryDict = {
@@ -251,7 +250,7 @@ class ArtifactManifestEntry:
         return contents
 
     def _is_artifact_reference(self) -> bool:
-        return self.ref is not None and urlparse(self.ref).scheme == "wandb-artifact"
+        return self.ref is not None and urlparse(self.ref).scheme == _WB_ARTIFACT_SCHEME
 
     def _referenced_artifact_id(self) -> str | None:
         if not self._is_artifact_reference():

wandb/sdk/artifacts/artifact_manifests/artifact_manifest_v1.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from operator import itemgetter
 from typing import Any, Mapping
 
 from wandb.sdk.artifacts.artifact_manifest import ArtifactManifest
@@ -64,7 +65,7 @@ class ArtifactManifestV1(ArtifactManifest):
         contents.
         """
         contents = {}
-        for entry in sorted(self.entries.values(), key=lambda k: k.path):
+        for name, entry in sorted(self.entries.items(), key=itemgetter(0)):
             json_entry: dict[str, Any] = {
                 "digest": entry.digest,
             }
@@ -76,7 +77,7 @@ class ArtifactManifestV1(ArtifactManifest):
                 json_entry["extra"] = entry.extra
             if entry.size is not None:
                 json_entry["size"] = entry.size
-            contents[entry.path] = json_entry
+            contents[name] = json_entry
         return {
             "version": self.__class__.version(),
             "storagePolicy": self.storage_policy.name(),
@@ -87,6 +88,7 @@ class ArtifactManifestV1(ArtifactManifest):
     def digest(self) -> HexMD5:
         hasher = _md5()
         hasher.update(b"wandb-artifact-manifest-v1\n")
-        for name, entry in sorted(self.entries.items(), key=lambda kv: kv[0]):
+        # sort by key (path)
+        for name, entry in sorted(self.entries.items(), key=itemgetter(0)):
             hasher.update(f"{name}:{entry.digest}\n".encode())
         return HexMD5(hasher.hexdigest())

wandb/sdk/artifacts/storage_handlers/http_handler.py

@@ -42,7 +42,7 @@ class HTTPHandler(StorageHandler):
 
         path, hit, cache_open = self._cache.check_etag_obj_path(
             URIStr(manifest_entry.ref),
-            ETag(manifest_entry.digest),  # TODO(spencerpearson): unsafe cast
+            ETag(manifest_entry.digest),
             manifest_entry.size if manifest_entry.size is not None else 0,
         )
         if hit:

wandb/sdk/artifacts/storage_handlers/s3_handler.py

@@ -94,7 +94,7 @@ class S3Handler(StorageHandler):
 
         path, hit, cache_open = self._cache.check_etag_obj_path(
             URIStr(manifest_entry.ref),
-            ETag(manifest_entry.digest),  # TODO(spencerpearson): unsafe cast
+            ETag(manifest_entry.digest),
             manifest_entry.size if manifest_entry.size is not None else 0,
         )
         if hit:

wandb/sdk/artifacts/storage_policies/wandb_storage_policy.py

@@ -167,7 +167,7 @@ class WandbStoragePolicy(StoragePolicy):
             self._cache._override_cache_path = dest_path
 
         path, hit, cache_open = self._cache.check_md5_obj_path(
-            B64MD5(manifest_entry.digest),  # TODO(spencerpearson): unsafe cast
+            B64MD5(manifest_entry.digest),
             manifest_entry.size if manifest_entry.size is not None else 0,
         )
         if hit:

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]
@@ -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.
@@ -357,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/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: