wandb 0.20.2rc20250616__py3-none-macosx_10_14_x86_64.whl → 0.21.0__py3-none-macosx_10_14_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.20.2rc20250616"
+__version__ = "0.21.0"
 
 
 from wandb.errors import Error

wandb/__init__.pyi

@@ -12,20 +12,20 @@ For reference documentation, see https://docs.wandb.com/ref/python.
 from __future__ import annotations
 
 __all__ = (
-    "__version__",
+    "__version__",  # doc:exclude
     "init",
     "finish",
     "setup",
     "login",
-    "save",
+    "save",  # doc:exclude
     "sweep",
     "controller",
     "agent",
-    "config",
-    "log",
-    "summary",
+    "config",  # doc:exclude
+    "log",  # doc:exclude
+    "summary",  # doc:exclude
     "Api",
-    "Graph",
+    "Graph",  # doc:exclude
     "Image",
     "Plotly",
     "Video",
@@ -36,26 +36,27 @@ __all__ = (
     "Object3D",
     "Molecule",
     "Histogram",
-    "ArtifactTTL",
-    "log_artifact",
-    "use_artifact",
-    "log_model",
-    "use_model",
-    "link_model",
-    "define_metric",
-    "Error",
-    "termsetup",
-    "termlog",
-    "termerror",
-    "termwarn",
+    "ArtifactTTL",  # doc:exclude
+    "log_artifact",  # doc:exclude
+    "use_artifact",  # doc:exclude
+    "log_model",  # doc:exclude
+    "use_model",  # doc:exclude
+    "link_model",  # doc:exclude
+    "define_metric",  # doc:exclude
+    "Error",  # doc:exclude
+    "termsetup",  # doc:exclude
+    "termlog",  # doc:exclude
+    "termerror",  # doc:exclude
+    "termwarn",  # doc:exclude
     "Artifact",
     "Settings",
     "teardown",
-    "watch",
-    "unwatch",
-    "plot",
+    "watch",  # doc:exclude
+    "unwatch",  # doc:exclude
+    "plot",  # doc:exclude
     "plot_table",
     "restore",
+    "Run",
 )
 
 import os
@@ -106,7 +107,7 @@ if TYPE_CHECKING:
     import wandb
     from wandb.plot import CustomChart
 
-__version__: str = "0.20.2rc20250616"
+__version__: str = "0.21.0"
 
 run: Run | None
 config: wandb_config.Config
@@ -325,7 +326,7 @@ def init(
             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()`.
+            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.

wandb/apis/internal.py

@@ -211,6 +211,9 @@ class Api:
     def upsert_run_queue(self, *args, **kwargs):
         return self.api.upsert_run_queue(*args, **kwargs)
 
+    def create_custom_chart(self, *args, **kwargs):
+        return self.api.create_custom_chart(*args, **kwargs)
+
     def update_launch_agent_status(self, *args, **kwargs):
         return self.api.update_launch_agent_status(*args, **kwargs)
 

wandb/apis/paginator.py

@@ -13,6 +13,8 @@ from typing import (
     overload,
 )
 
+import wandb
+
 if TYPE_CHECKING:
     from wandb_graphql.language.ast import Document
 
@@ -112,14 +114,25 @@ class Paginator(Iterator[T]):
 class SizedPaginator(Paginator[T], Sized):
     """A Paginator for objects with a known total count."""
 
+    @property
+    def length(self) -> int | None:
+        wandb.termwarn(
+            (
+                "`.length` is deprecated and will be removed in a future version. "
+                "Use `len(...)` instead."
+            ),
+            repeat=False,
+        )
+        return len(self)
+
     def __len__(self) -> int:
-        if self.length is None:
+        if self._length is None:
             self._load_page()
-        if self.length is None:
+        if self._length is None:
             raise ValueError("Object doesn't provide length")
-        return self.length
+        return self._length
 
     @property
     @abstractmethod
-    def length(self) -> int | None:
+    def _length(self) -> int | None:
         raise NotImplementedError

wandb/apis/public/api.py

@@ -467,6 +467,85 @@ class Api:
             _default_resource_config=config,
         )
 
+    def create_custom_chart(
+        self,
+        entity: str,
+        name: str,
+        display_name: str,
+        spec_type: Literal["vega2"],
+        access: Literal["private", "public"],
+        spec: Union[str, dict],
+    ) -> str:
+        """Create a custom chart preset and return its id.
+
+        Args:
+            entity: The entity (user or team) that owns the chart
+            name: Unique identifier for the chart preset
+            display_name: Human-readable name shown in the UI
+            spec_type: Type of specification. Must be "vega2" for Vega-Lite v2 specifications.
+            access: Access level for the chart:
+                - "private": Chart is only accessible to the entity that created it
+                - "public": Chart is publicly accessible
+            spec: The Vega/Vega-Lite specification as a dictionary or JSON string
+
+        Returns:
+            The ID of the created chart preset in the format "entity/name"
+
+        Raises:
+            wandb.Error: If chart creation fails
+            UnsupportedError: If the server doesn't support custom charts
+
+        Example:
+            ```python
+            import wandb
+
+            api = wandb.Api()
+
+            # Define a simple bar chart specification
+            vega_spec = {
+                "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
+                "mark": "bar",
+                "data": {"name": "wandb"},
+                "encoding": {
+                    "x": {"field": "${field:x}", "type": "ordinal"},
+                    "y": {"field": "${field:y}", "type": "quantitative"},
+                },
+            }
+
+            # Create the custom chart
+            chart_id = api.create_custom_chart(
+                entity="my-team",
+                name="my-bar-chart",
+                display_name="My Custom Bar Chart",
+                spec_type="vega2",
+                access="private",
+                spec=vega_spec,
+            )
+
+            # Use with wandb.plot_table()
+            chart = wandb.plot_table(
+                vega_spec_name=chart_id,
+                data_table=my_table,
+                fields={"x": "category", "y": "value"},
+            )
+            ```
+        """
+        # Convert user-facing lowercase access to backend uppercase
+        backend_access = access.upper()
+
+        api = InternalApi(retry_timedelta=RETRY_TIMEDELTA)
+        result = api.create_custom_chart(
+            entity=entity,
+            name=name,
+            display_name=display_name,
+            spec_type=spec_type,
+            access=backend_access,
+            spec=spec,
+        )
+        if result is None or result.get("chart") is None:
+            raise wandb.Error("failed to create custom chart")
+        return result["chart"]["id"]
+
     def upsert_run_queue(
         self,
         name: str,
@@ -713,7 +792,7 @@ class Api:
                 return public.BetaReport(
                     self.client,
                     {
-                        "display_name": urllib.parse.unquote(name.replace("-", " ")),
+                        "displayName": urllib.parse.unquote(name.replace("-", " ")),
                         "id": id,
                         "spec": "{}",
                     },
@@ -1514,7 +1593,9 @@ class Api:
 
             Find all collections in the registries with the name "my_collection" and the tag "my_tag"
             ```python
-            api.registries().collections(filter={"name": "my_collection", "tag": "my_tag"})
+            api.registries().collections(
+                filter={"name": "my_collection", "tag": "my_tag"}
+            )
             ```
 
             Find all artifact versions in the registries with a collection name that contains "my_collection" and a version that has the alias "best"

wandb/apis/public/artifacts.py

@@ -100,7 +100,7 @@ class ArtifactTypes(Paginator["ArtifactType"]):
         self.last_response = ArtifactTypesFragment.model_validate(conn)
 
     @property
-    def length(self) -> None:
+    def _length(self) -> None:
         # TODO
         return None
 
@@ -240,9 +240,9 @@ class ArtifactCollections(SizedPaginator["ArtifactCollection"]):
         self.last_response = ArtifactCollectionsFragment.model_validate(conn)
 
     @property
-    def length(self):
+    def _length(self) -> int:
         if self.last_response is None:
-            return None
+            self._load_page()
         return self.last_response.total_count
 
     @property
@@ -608,9 +608,9 @@ class Artifacts(SizedPaginator["Artifact"]):
         self.last_response = ArtifactsFragment.model_validate(conn)
 
     @property
-    def length(self) -> int | None:
+    def _length(self) -> int:
         if self.last_response is None:
-            return None
+            self._load_page()
         return self.last_response.total_count
 
     @property
@@ -698,9 +698,9 @@ class RunArtifacts(SizedPaginator["Artifact"]):
         self.last_response = self._response_cls.model_validate(inner_data)
 
     @property
-    def length(self) -> int | None:
+    def _length(self) -> int:
         if self.last_response is None:
-            return None
+            self._load_page()
         return self.last_response.total_count
 
     @property
@@ -799,7 +799,9 @@ class ArtifactFiles(SizedPaginator["public.File"]):
         return [self.artifact.entity, self.artifact.project, self.artifact.name]
 
     @property
-    def length(self) -> int:
+    def _length(self) -> int:
+        if self.last_response is None:
+            self._load_page()
         return self.artifact.file_count
 
     @property

wandb/apis/public/files.py

@@ -72,11 +72,11 @@ class Files(SizedPaginator["File"]):
         super().__init__(client, variables, per_page)
 
     @property
-    def length(self):
-        if self.last_response:
-            return self.last_response["project"]["run"]["fileCount"]
-        else:
-            return None
+    def _length(self):
+        if not self.last_response:
+            self._load_page()
+
+        return self.last_response["project"]["run"]["fileCount"]
 
     @property
     def more(self):

wandb/apis/public/projects.py

@@ -9,6 +9,7 @@ from wandb.apis import public
 from wandb.apis.attrs import Attrs
 from wandb.apis.normalize import normalize_exceptions
 from wandb.apis.paginator import Paginator
+from wandb.apis.public.api import RetryingClient
 from wandb.sdk.lib import ipython
 
 PROJECT_FRAGMENT = """fragment ProjectFragment on Project {
@@ -43,7 +44,19 @@ class Projects(Paginator["Project"]):
         """.format(PROJECT_FRAGMENT)
     )
 
-    def __init__(self, client, entity, per_page=50):
+    def __init__(
+        self,
+        client: RetryingClient,
+        entity: str,
+        per_page: int = 50,
+    ) -> "Projects":
+        """An iterable collection of `Project` objects.
+
+        Args:
+            client: The API client used to query W&B.
+            entity: The entity which owns the projects.
+            per_page: The number of projects to fetch per request to the API.
+        """
         self.client = client
         self.entity = entity
         variables = {
@@ -83,7 +96,31 @@ class Projects(Paginator["Project"]):
 class Project(Attrs):
     """A project is a namespace for runs."""
 
-    def __init__(self, client, entity, project, attrs):
+    QUERY = gql(
+        """
+        query Project($project: String!, $entity: String!) {
+            project(name: $project, entityName: $entity) {
+                id
+            }
+        }
+        """
+    )
+
+    def __init__(
+        self,
+        client: RetryingClient,
+        entity: str,
+        project: str,
+        attrs: dict,
+    ) -> "Project":
+        """A single project associated with an entity.
+
+        Args:
+            client: The API client used to query W&B.
+            entity: The entity which owns the project.
+            project: The name of the project to query.
+            attrs: The attributes of the project.
+        """
         super().__init__(dict(attrs))
         self.client = client
         self.name = project
@@ -143,7 +180,7 @@ class Project(Attrs):
         )
         variable_values = {"project": self.name, "entity": self.entity}
         ret = self.client.execute(query, variable_values)
-        if ret["project"]["totalSweeps"] < 1:
+        if not ret.get("project") or ret["project"]["totalSweeps"] < 1:
             return []
 
         return [
@@ -178,6 +215,10 @@ class Project(Attrs):
         variable_values = {"projectName": self.name, "entityName": self.entity}
         try:
             data = self.client.execute(self._PROJECT_ID, variable_values)
+
+            if not data.get("project") or not data["project"].get("id"):
+                raise ValueError(f"Project {self.name} not found")
+
             self._attrs["id"] = data["project"]["id"]
             return self._attrs["id"]
         except (HTTPError, LookupError, TypeError) as e:

wandb/apis/public/reports.py

@@ -2,6 +2,7 @@
 
 import ast
 import json
+import re
 import urllib
 
 from wandb_gql import gql
@@ -32,9 +33,11 @@ class Reports(SizedPaginator["BetaReport"]):
                             user {
                                 username
                                 photoUrl
+                                email
                             }
                             spec
                             updatedAt
+                            createdAt
                         }
                         cursor
                     }
@@ -60,7 +63,7 @@ class Reports(SizedPaginator["BetaReport"]):
         super().__init__(client, variables, per_page)
 
     @property
-    def length(self):
+    def _length(self):
         # TODO: Add the count the backend
         if self.last_response:
             return len(self.objects)
@@ -111,11 +114,15 @@ class BetaReport(Attrs):
     WARNING: this API will likely change in a future release
 
     Attributes:
+        id (string): unique identifier of the report
         name (string): report name
-        description (string): report description;
-        user (User): the user that created the report
-        spec (dict): the spec off the report;
+        display_name (string): display name of the report
+        description (string): report description
+        user (User): the user that created the report (contains username and email)
+        spec (dict): the spec of the report
+        url (string): the url of the report
         updated_at (string): timestamp of last update
+        created_at (string): timestamp when the report was created
     """
 
     def __init__(self, client, attrs, entity=None, project=None):
@@ -124,7 +131,16 @@ class BetaReport(Attrs):
         self.entity = entity
         self.query_generator = public.QueryGenerator()
         super().__init__(dict(attrs))
-        self._attrs["spec"] = json.loads(self._attrs["spec"])
+
+        if "spec" in self._attrs:
+            if isinstance(self._attrs["spec"], str):
+                self._attrs["spec"] = json.loads(self._attrs["spec"])
+        else:
+            self._attrs["spec"] = {}
+
+    @property
+    def spec(self):
+        return self._attrs["spec"]
 
     @property
     def sections(self):
@@ -153,12 +169,44 @@ class BetaReport(Attrs):
             per_page=per_page,
         )
 
+    @property
+    def id(self):
+        return self._attrs.get("id")
+
+    @property
+    def name(self):
+        return self._attrs.get("name")
+
+    @property
+    def display_name(self):
+        return self._attrs.get("displayName")
+
+    @property
+    def description(self):
+        return self._attrs.get("description")
+
+    @property
+    def user(self):
+        return self._attrs.get("user")
+
     @property
     def updated_at(self):
-        return self._attrs["updatedAt"]
+        return self._attrs.get("updatedAt")
+
+    @property
+    def created_at(self):
+        return self._attrs.get("createdAt")
 
     @property
     def url(self):
+        if (
+            not self.client
+            or not self.entity
+            or not self.project
+            or not self.display_name
+            or not self.id
+        ):
+            return None
         return self.client.app_url + "/".join(
             [
                 self.entity,
@@ -166,7 +214,12 @@ class BetaReport(Attrs):
                 "reports",
                 "--".join(
                     [
-                        urllib.parse.quote(self.display_name.replace(" ", "-")),
+                        # made this more closely match the url creation in the frontend (https://github.com/wandb/core/blob/76943979c8e967f7a62dae8bef0a001a2672584c/frontends/app/src/util/report/urls.ts#L19)
+                        urllib.parse.quote(
+                            re.sub(
+                                r"-+", "-", re.sub(r"\W", "-", self.display_name)
+                            ).strip("-")
+                        ),
                         self.id.replace("=", ""),
                     ]
                 ),
@@ -175,7 +228,10 @@ class BetaReport(Attrs):
 
     def to_html(self, height=1024, hidden=False):
         """Generate HTML containing an iframe displaying this report."""
-        url = self.url + "?jupyter=true"
+        url = self.url
+        if url is None:
+            return "<div>Report URL not available</div>"
+        url = url + "?jupyter=true"
         style = f"border:none;width:100%;height:{height}px;"
         prefix = ""
         if hidden:

wandb/apis/public/runs.py

@@ -111,7 +111,7 @@ class Runs(SizedPaginator["Run"]):
                     runs(filters: $filters, after: $cursor, first: $perPage, order: $order) {{
                         edges {{
                             node {{
-                                {"" if _server_provides_internal_id_for_project(client) else "internalId"}
+                                {"projectId" if _server_provides_internal_id_for_project(client) else ""}
                                 ...RunFragment
                             }}
                             cursor
@@ -143,11 +143,10 @@ class Runs(SizedPaginator["Run"]):
         super().__init__(client, variables, per_page)
 
     @property
-    def length(self):
-        if self.last_response:
-            return self.last_response["project"]["runCount"]
-        else:
-            return None
+    def _length(self):
+        if not self.last_response:
+            self._load_page()
+        return self.last_response["project"]["runCount"]
 
     @property
     def more(self):
@@ -454,25 +453,19 @@ class Run(Attrs):
         )
 
     def load(self, force=False):
-        query = gql(
-            """
-        query Run($project: String!, $entity: String!, $name: String!) {{
-            project(name: $project, entityName: $entity) {{
-                run(name: $name) {{
-                    {}
-                    ...RunFragment
+        if force or not self._attrs:
+            query = gql(f"""#graphql
+            query Run($project: String!, $entity: String!, $name: String!) {{
+                project(name: $project, entityName: $entity) {{
+                    run(name: $name) {{
+                        {"projectId" if _server_provides_internal_id_for_project(self.client) else ""}
+                        ...RunFragment
+                    }}
                 }}
             }}
-        }}
-        {}
-        """.format(
-                "projectId"
-                if _server_provides_internal_id_for_project(self.client)
-                else "",
-                RUN_FRAGMENT,
-            )
-        )
-        if force or not self._attrs:
+            {RUN_FRAGMENT}
+            """)
+
             response = self._exec(query)
             if (
                 response is None

wandb/automations/__init__.py

@@ -45,21 +45,21 @@ else:
 
 __all__ = [
     # Scopes
-    "ScopeType",
-    "ArtifactCollectionScope",
-    "ProjectScope",
+    "ScopeType",  # doc:exclude
+    "ArtifactCollectionScope",  # doc:exclude
+    "ProjectScope",  # doc:exclude
     # Events
-    "EventType",
+    "EventType",  # doc:exclude
     "OnAddArtifactAlias",
     "OnCreateArtifact",
     "OnLinkArtifact",
     "OnRunMetric",
-    "ArtifactEvent",
-    "RunEvent",
+    "ArtifactEvent",  # doc:exclude
+    "RunEvent",  # doc:exclude
     "MetricThresholdFilter",
     "MetricChangeFilter",
     # Actions
-    "ActionType",
+    "ActionType",  # doc:exclude
     "SendNotification",
     "SendWebhook",
     "DoNothing",
@@ -67,7 +67,7 @@ __all__ = [
     "Automation",
     "NewAutomation",
     # Integrations
-    "Integration",
-    "SlackIntegration",
-    "WebhookIntegration",
+    "Integration",  # doc:exclude
+    "SlackIntegration",  # doc:exclude
+    "WebhookIntegration",  # doc:exclude
 ]

wandb/automations/_filters/run_metrics.py

@@ -1,5 +1,3 @@
-# ruff: noqa: UP007
-
 from __future__ import annotations
 
 from abc import ABC, abstractmethod

wandb/automations/_utils.py

@@ -1,5 +1,3 @@
-# ruff: noqa: UP007  # Avoid using `X | Y` for union fields, as this can cause issues with pydantic < 2.6
-
 from __future__ import annotations
 
 from typing import Any, Collection, Final, Optional, Protocol, TypedDict

wandb/automations/actions.py

@@ -1,7 +1,5 @@
 """Actions that are triggered by W&B Automations."""
 
-# ruff: noqa: UP007  # Avoid using `X | Y` for union fields, as this can cause issues with pydantic < 2.6
-
 from __future__ import annotations
 
 from typing import Any, Literal, Optional, Union

wandb/automations/automations.py

@@ -1,5 +1,3 @@
-# ruff: noqa: UP007  # Avoid using `X | Y` for union fields, as this can cause issues with pydantic < 2.6
-
 from __future__ import annotations
 
 from datetime import datetime