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

wandb/apis/public/reports.py

@@ -1,7 +1,12 @@
-"""Public API: reports."""
+"""W&B Public API for Report objects.
+
+This module provides classes for interacting with W&B reports and
+managing report-related data.
+"""
 
 import ast
 import json
+import re
 import urllib
 
 from wandb_gql import gql
@@ -14,7 +19,17 @@ from wandb.sdk.lib import ipython
 
 
 class Reports(SizedPaginator["BetaReport"]):
-    """Reports is an iterable collection of `BetaReport` objects."""
+    """Reports is a lazy iterator of `BetaReport` objects.
+
+    Args:
+        client (`wandb.apis.internal.Api`): The API client instance to use.
+        project (`wandb.sdk.internal.Project`): The project to fetch reports from.
+        name (str, optional): The name of the report to filter by. If `None`,
+            fetches all reports.
+        entity (str, optional): The entity name for the project. Defaults to
+            the project entity.
+        per_page (int): Number of reports to fetch per page (default is 50).
+    """
 
     QUERY = gql(
         """
@@ -32,9 +47,11 @@ class Reports(SizedPaginator["BetaReport"]):
                             user {
                                 username
                                 photoUrl
+                                email
                             }
                             spec
                             updatedAt
+                            createdAt
                         }
                         cursor
                     }
@@ -60,7 +77,11 @@ class Reports(SizedPaginator["BetaReport"]):
         super().__init__(client, variables, per_page)
 
     @property
-    def length(self):
+    def _length(self):
+        """The number of reports in the project.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         # TODO: Add the count the backend
         if self.last_response:
             return len(self.objects)
@@ -68,25 +89,37 @@ class Reports(SizedPaginator["BetaReport"]):
             return None
 
     @property
-    def more(self):
+    def more(self) -> bool:
+        """Returns whether there are more files to fetch.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if self.last_response:
-            return self.last_response["project"]["allViews"]["pageInfo"]["hasNextPage"]
+            return bool(
+                self.last_response["project"]["allViews"]["pageInfo"]["hasNextPage"]
+            )
         else:
             return True
 
     @property
     def cursor(self):
+        """Returns the cursor position for pagination of file results.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if self.last_response:
             return self.last_response["project"]["allViews"]["edges"][-1]["cursor"]
         else:
             return None
 
     def update_variables(self):
+        """Updates the GraphQL query variables for pagination."""
         self.variables.update(
             {"reportCursor": self.cursor, "reportLimit": self.per_page}
         )
 
     def convert_objects(self):
+        """Converts GraphQL edges to File objects."""
         if self.last_response["project"] is None:
             raise ValueError(
                 f"Project {self.variables['project']} does not exist under entity {self.variables['entity']}"
@@ -106,16 +139,20 @@ class Reports(SizedPaginator["BetaReport"]):
 
 
 class BetaReport(Attrs):
-    """BetaReport is a class associated with reports created in wandb.
+    """BetaReport is a class associated with reports created in W&B.
 
     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,13 +161,24 @@ 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):
+        """Get the panel sections (groups) from the report."""
         return self.spec["panelGroups"]
 
     def runs(self, section, per_page=50, only_selected=True):
+        """Get runs associated with a section of the report."""
         run_set_idx = section.get("openRunSet", 0)
         run_set = section["runSets"][run_set_idx]
         order = self.query_generator.key_to_server_path(run_set["sort"]["key"])
@@ -153,12 +201,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 +246,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 +260,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:
@@ -188,6 +276,11 @@ class BetaReport(Attrs):
 
 
 class PythonMongoishQueryGenerator:
+    """Converts Python-style query expressions to MongoDB-style queries for W&B reports.
+
+    <!-- lazydoc-ignore-class: internal -->
+    """
+
     SPACER = "----------"
     DECIMAL_SPACER = ";;;"
     FRONTEND_NAME_MAPPING = {
@@ -298,6 +391,10 @@ class PythonMongoishQueryGenerator:
         return field_name.replace(self.SPACER, ".")  # Allow dotted fields
 
     def python_to_mongo(self, filterstr):
+        """Convert Python expresion to MongoDB filter.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         try:
             tree = ast.parse(self._convert(filterstr), mode="eval")
         except SyntaxError as e:
@@ -316,6 +413,10 @@ class PythonMongoishQueryGenerator:
         return {"$or": [{op: values}]}
 
     def front_to_back(self, name):
+        """Convert frontend metric names to backend field names.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         name, *rest = name.split(".")
         rest = "." + ".".join(rest) if rest else ""
 
@@ -329,6 +430,10 @@ class PythonMongoishQueryGenerator:
             return f"summary_metrics.{name}{rest}"
 
     def back_to_front(self, name):
+        """Convert backend field names to frontend metric names.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if name in self.FRONTEND_NAME_MAPPING_REVERSED:
             return self.FRONTEND_NAME_MAPPING_REVERSED[name]
         elif name in self.FRONTEND_NAME_MAPPING:
@@ -345,6 +450,10 @@ class PythonMongoishQueryGenerator:
 
     # These are only used for ParallelCoordinatesPlot because it has weird backend names...
     def pc_front_to_back(self, name):
+        """Convert ParallelCoordinatesPlot to backend field names.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         name, *rest = name.split(".")
         rest = "." + ".".join(rest) if rest else ""
         if name is None:
@@ -361,6 +470,10 @@ class PythonMongoishQueryGenerator:
             return f"summary:{name}{rest}"
 
     def pc_back_to_front(self, name):
+        """Convert backend backend field names to ParallelCoordinatesPlot names.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if name is None:
             return None
         elif "summary:" in name:
@@ -380,6 +493,11 @@ class PythonMongoishQueryGenerator:
 
 
 class PanelMetricsHelper:
+    """Converts Python-style query expressions to MongoDB-style queries for W&B reports.
+
+    <!-- lazydoc-ignore-class: internal -->
+    """
+
     FRONTEND_NAME_MAPPING = {
         "Step": "_step",
         "Relative Time (Wall)": "_absolute_runtime",
@@ -392,17 +510,29 @@ class PanelMetricsHelper:
     RUN_MAPPING_REVERSED = {v: k for k, v in RUN_MAPPING.items()}
 
     def front_to_back(self, name):
+        """Convert frontend metric names to backend field names.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if name in self.FRONTEND_NAME_MAPPING:
             return self.FRONTEND_NAME_MAPPING[name]
         return name
 
     def back_to_front(self, name):
+        """Convert backend field names to frontend metric names.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if name in self.FRONTEND_NAME_MAPPING_REVERSED:
             return self.FRONTEND_NAME_MAPPING_REVERSED[name]
         return name
 
     # ScatterPlot and ParallelCoords have weird conventions
     def special_front_to_back(self, name):
+        """Convert frontend metric names to backend field names.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if name is None:
             return name
 
@@ -429,6 +559,10 @@ class PanelMetricsHelper:
         return "summary:" + name
 
     def special_back_to_front(self, name):
+        """Convert backend field names to frontend metric names.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if name is not None:
             kind, rest = name.split(":", 1)