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

wandb/apis/public/sweeps.py

@@ -1,4 +1,31 @@
-"""Public API: sweeps."""
+"""W&B Public API for Sweeps.
+
+This module provides classes for interacting with W&B hyperparameter
+optimization sweeps.
+
+Example:
+```python
+from wandb.apis.public import Api
+
+# Get a specific sweep
+sweep = Api().sweep("entity/project/sweep_id")
+
+# Access sweep properties
+print(f"Sweep: {sweep.name}")
+print(f"State: {sweep.state}")
+print(f"Best Loss: {sweep.best_loss}")
+
+# Get best performing run
+best_run = sweep.best_run()
+print(f"Best Run: {best_run.name}")
+print(f"Metrics: {best_run.summary}")
+```
+
+Note:
+    This module is part of the W&B Public API and provides read-only access
+    to sweep data. For creating and controlling sweeps, use the wandb.sweep()
+    and wandb.agent() functions from the main wandb package.
+"""
 
 import urllib
 from typing import Optional
@@ -9,6 +36,8 @@ import wandb
 from wandb import util
 from wandb.apis import public
 from wandb.apis.attrs import Attrs
+from wandb.apis.paginator import SizedPaginator
+from wandb.apis.public.api import RetryingClient
 from wandb.sdk.lib import ipython
 
 SWEEP_FRAGMENT = """fragment SweepFragment on Sweep {
@@ -27,23 +56,154 @@ SWEEP_FRAGMENT = """fragment SweepFragment on Sweep {
 """
 
 
-class Sweep(Attrs):
-    """A set of runs associated with a sweep.
+class Sweeps(SizedPaginator["Sweep"]):
+    """A lazy iterator over a collection of `Sweep` objects.
 
     Examples:
-        Instantiate with:
-        ```
-        api = wandb.Api()
-        sweep = api.sweep(path / to / sweep)
-        ```
+    ```python
+    from wandb.apis.public import Api
+
+    sweeps = Api().project(name="project_name", entity="entity").sweeps()
+
+    # Iterate over sweeps and print details
+    for sweep in sweeps:
+        print(f"Sweep name: {sweep.name}")
+        print(f"Sweep ID: {sweep.id}")
+        print(f"Sweep URL: {sweep.url}")
+        print("----------")
+    ```
+    """
+
+    QUERY = gql(
+        f"""#graphql
+        query GetSweeps($project: String!, $entity: String!, $cursor: String, $perPage: Int = 50) {{
+            project(name: $project, entityName: $entity) {{
+                totalSweeps
+                sweeps(after: $cursor, first: $perPage) {{
+                    edges {{
+                        node {{
+                            ...SweepFragment
+                        }}
+                        cursor
+                    }}
+                    pageInfo {{
+                        endCursor
+                        hasNextPage
+                    }}
+                }}
+            }}
+        }}
+        {SWEEP_FRAGMENT}
+        """
+    )
+
+    def __init__(
+        self,
+        client: RetryingClient,
+        entity: str,
+        project: str,
+        per_page: int = 50,
+    ) -> "Sweeps":
+        """An iterable collection of `Sweep` objects.
+
+        Args:
+            client: The API client used to query W&B.
+            entity: The entity which owns the sweeps.
+            project: The project which contains the sweeps.
+            per_page: The number of sweeps to fetch per request to the API.
+        """
+        self.client = client
+        self.entity = entity
+        self.project = project
+        variables = {
+            "project": self.project,
+            "entity": self.entity,
+        }
+        super().__init__(client, variables, per_page)
+
+    @property
+    def _length(self):
+        """The total number of sweeps in the project.
+
+        <!-- lazydoc-ignore: internal -->
+        """
+        if not self.last_response:
+            self._load_page()
+
+        return (
+            self.last_response["project"]["totalSweeps"]
+            if self.last_response["project"]["totalSweeps"] is not None
+            else 0
+        )
+
+    @property
+    def more(self):
+        """Returns whether there are more sweeps to fetch.
+
+        <!-- lazydoc-ignore: internal -->
+        """
+        if self.last_response:
+            return bool(
+                self.last_response["project"]["sweeps"]["pageInfo"]["hasNextPage"]
+            )
+        else:
+            return True
+
+    @property
+    def cursor(self):
+        """Returns the cursor for the next page of sweeps.
+
+        <!-- lazydoc-ignore: internal -->
+        """
+        if self.last_response:
+            return self.last_response["project"]["sweeps"]["pageInfo"]["endCursor"]
+        else:
+            return None
+
+    def update_variables(self):
+        """Updates the variables for the next page of sweeps.
+
+        <!-- lazydoc-ignore: internal -->
+        """
+        self.variables.update({"perPage": self.per_page, "cursor": self.cursor})
+
+    def convert_objects(self):
+        """Converts the last GraphQL response into a list of `Sweep` objects.
+
+        <!-- lazydoc-ignore: internal -->
+        """
+        if self.last_response is None or self.last_response.get("project") is None:
+            raise ValueError("Could not find project {}".format(self.project))
+
+        if self.last_response["project"]["totalSweeps"] < 1:
+            return []
+
+        return [
+            # match format of existing public sweep apis
+            public.Sweep(
+                self.client,
+                self.entity,
+                self.project,
+                e["node"]["name"],
+            )
+            for e in self.last_response["project"]["sweeps"]["edges"]
+        ]
+
+    def __repr__(self):
+        return f"<Sweeps {self.entity}/{self.project}>"
+
+
+class Sweep(Attrs):
+    """The set of runs associated with the sweep.
 
     Attributes:
-        runs: (`Runs`) list of runs
-        id: (str) sweep id
-        project: (str) name of project
-        config: (str) dictionary of sweep configuration
-        state: (str) the state of the sweep
-        expected_run_count: (int) number of expected runs for the sweep
+        runs (Runs): List of runs
+        id (str): Sweep ID
+        project (str): The name of the project the sweep belongs to
+        config (dict): Dictionary containing the sweep configuration
+        state (str): The state of the sweep. Can be "Finished", "Failed",
+            "Crashed", or "Running".
+        expected_run_count (int): The number of expected runs for the sweep
     """
 
     QUERY = gql(
@@ -53,6 +213,7 @@ class Sweep(Attrs):
             sweep(sweepName: $name) {
                 id
                 name
+                displayName
                 state
                 runCountExpected
                 bestLoss
@@ -92,18 +253,25 @@ class Sweep(Attrs):
 
     @property
     def entity(self):
+        """The entity associated with the sweep."""
         return self._entity
 
     @property
     def username(self):
+        """Deprecated. Use `Sweep.entity` instead."""
         wandb.termwarn("Sweep.username is deprecated. please use Sweep.entity instead.")
         return self._entity
 
     @property
     def config(self):
+        """The sweep configuration used for the sweep."""
         return util.load_yaml(self._attrs["config"])
 
     def load(self, force: bool = False):
+        """Fetch and update sweep data logged to the run from GraphQL database.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if force or not self._attrs:
             sweep = self.get(self.client, self.entity, self.project, self.id)
             if sweep is None:
@@ -115,6 +283,7 @@ class Sweep(Attrs):
 
     @property
     def order(self):
+        """Return the order key for the sweep."""
         if self._attrs.get("config") and self.config.get("metric"):
             sort_order = self.config["metric"].get("goal", "minimize")
             prefix = "+" if sort_order == "minimize" else "-"
@@ -154,6 +323,9 @@ class Sweep(Attrs):
 
     @property
     def path(self):
+        """Returns the path of the project.
+
+        The path is a list containing the entity, project name, and sweep ID."""
         return [
             urllib.parse.quote_plus(str(self.entity)),
             urllib.parse.quote_plus(str(self.project)),
@@ -162,26 +334,54 @@ class Sweep(Attrs):
 
     @property
     def url(self):
+        """The URL of the sweep.
+
+        The sweep URL is generated from the entity, project, the term
+        "sweeps", and the sweep ID.run_id. For
+        SaaS users, it takes the form
+        of `https://wandb.ai/entity/project/sweeps/sweeps_ID`.
+        """
         path = self.path
         path.insert(2, "sweeps")
         return self.client.app_url + "/".join(path)
 
     @property
     def name(self):
-        return self.config.get("name") or self.id
+        """The name of the sweep.
+
+        Returns the first name that exists in the following priority order:
+
+        1. User-edited display name
+        2. Name configured at creation time
+        3. Sweep ID
+        """
+        return self._attrs.get("displayName") or self.config.get("name") or self.id
 
     @classmethod
     def get(
         cls,
-        client,
-        entity=None,
-        project=None,
-        sid=None,
-        order=None,
-        query=None,
+        client: "RetryingClient",
+        entity: Optional[str] = None,
+        project: Optional[str] = None,
+        sid: Optional[str] = None,
+        order: Optional[str] = None,
+        query: Optional[str] = None,
         **kwargs,
     ):
-        """Execute a query against the cloud backend."""
+        """Execute a query against the cloud backend.
+
+        Args:
+            client: The client to use to execute the query.
+            entity: The entity (username or team) that owns the project.
+            project: The name of the project to fetch sweep from.
+            sid: The sweep ID to query.
+            order: The order in which the sweep's runs are returned.
+            query: The query to use to execute the query.
+            **kwargs: Additional keyword arguments to pass to the query.
+        """
+        if not order:
+            order = "+created_at"
+
         if query is None:
             query = cls.QUERY
 

wandb/apis/public/teams.py

@@ -1,4 +1,12 @@
-"""Public API: teams."""
+"""W&B Public API for managing teams and team members.
+
+This module provides classes for managing W&B teams and their members.
+
+Note:
+    This module is part of the W&B Public API and provides methods to manage
+    teams and their members. Team management operations require appropriate
+    permissions.
+"""
 
 import requests
 from wandb_gql import gql
@@ -7,6 +15,14 @@ from wandb.apis.attrs import Attrs
 
 
 class Member(Attrs):
+    """A member of a team.
+
+    Args:
+        client (`wandb.apis.internal.Api`): The client instance to use
+        team (str): The name of the team this member belongs to
+        attrs (dict): The member attributes
+    """
+
     DELETE_MEMBER_MUTATION = gql(
         """
     mutation DeleteInvite($id: String, $entityName: String) {
@@ -40,6 +56,21 @@ class Member(Attrs):
 
 
 class Team(Attrs):
+    """A class that represents a W&B team.
+
+    This class provides methods to manage W&B teams, including creating teams,
+    inviting members, and managing service accounts. It inherits from Attrs
+    to handle team attributes.
+
+    Args:
+        client (`wandb.apis.public.Api`): The api instance to use
+        name (str): The name of the team
+        attrs (dict): Optional dictionary of team attributes
+
+    Note:
+        Team management requires appropriate permissions.
+    """
+
     CREATE_TEAM_MUTATION = gql(
         """
     mutation CreateTeam($teamName: String!, $teamAdminUserName: String) {
@@ -148,11 +179,13 @@ class Team(Attrs):
         """Invite a user to a team.
 
         Args:
-            username_or_email: (str) The username or email address of the user you want to invite
-            admin: (bool) Whether to make this user a team admin, defaults to False
+            username_or_email: (str) The username or email address of the user
+                you want to invite.
+            admin: (bool) Whether to make this user a team admin.
+                Defaults to `False`.
 
         Returns:
-            True on success, False if user was already invited or didn't exist
+            `True` on success, `False` if user was already invited or didn't exist.
         """
         variables = {"entityName": self.name, "admin": admin}
         if "@" in username_or_email:
@@ -185,6 +218,10 @@ class Team(Attrs):
             return None
 
     def load(self, force=False):
+        """Return members that belong to a team.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if force or not self._attrs:
             response = self._client.execute(self.TEAM_QUERY, {"name": self.name})
             self._attrs = response["entity"]

wandb/apis/public/users.py

@@ -1,4 +1,11 @@
-"""Public API: users."""
+"""W&B Public API for managing users and API keys.
+
+This module provides classes for managing W&B users and their API keys.
+
+Note:
+    This module is part of the W&B Public API and provides methods to manage
+    users and their authentication. Some operations require admin privileges.
+"""
 
 import requests
 from wandb_gql import gql
@@ -8,6 +15,20 @@ from wandb.apis.attrs import Attrs
 
 
 class User(Attrs):
+    """A class representing a W&B user with authentication and management capabilities.
+
+    This class provides methods to manage W&B users, including creating users,
+    managing API keys, and accessing team memberships. It inherits from Attrs
+    to handle user attributes.
+
+    Args:
+        client: (`wandb.apis.internal.Api`) The client instance to use
+        attrs: (dict) The user attributes
+
+    Note:
+        Some operations require admin privileges
+    """
+
     CREATE_USER_MUTATION = gql(
         """
     mutation CreateUserFromAdmin($email: String!, $admin: Boolean) {
@@ -63,9 +84,9 @@ class User(Attrs):
         """Create a new user.
 
         Args:
-            api: (`Api`) The api instance to use
-            email: (str) The name of the team
-            admin: (bool) Whether this user should be a global instance admin
+            api (`Api`): The api instance to use
+            email (str): The name of the team
+            admin (bool): Whether this user should be a global instance admin
 
         Returns:
             A `User` object
@@ -78,12 +99,24 @@ class User(Attrs):
 
     @property
     def api_keys(self):
+        """List of API key names associated with the user.
+
+        Returns:
+            list[str]: Names of API keys associated with the user. Empty list if user
+                has no API keys or if API key data hasn't been loaded.
+        """
         if self._attrs.get("apiKeys") is None:
             return []
         return [k["node"]["name"] for k in self._attrs["apiKeys"]["edges"]]
 
     @property
     def teams(self):
+        """List of team names that the user is a member of.
+
+        Returns:
+            list (list): Names of teams the user belongs to. Empty list if user has no
+                team memberships or if teams data hasn't been loaded.
+        """
         if self._attrs.get("teams") is None:
             return []
         return [k["node"]["name"] for k in self._attrs["teams"]["edges"]]
@@ -91,6 +124,10 @@ class User(Attrs):
     def delete_api_key(self, api_key):
         """Delete a user's api key.
 
+        Args:
+            api_key (str): The name of the API key to delete. This should be
+                one of the names returned by the `api_keys` property.
+
         Returns:
             Boolean indicating success
 
@@ -110,6 +147,10 @@ class User(Attrs):
     def generate_api_key(self, description=None):
         """Generate a new api key.
 
+        Args:
+            description (str, optional): A description for the new API key. This can be
+                used to identify the purpose of the API key.
+
         Returns:
             The new api key, or None on failure
         """

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

wandb/automations/events.py

@@ -1,7 +1,5 @@
 """Events that trigger 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 TYPE_CHECKING, Any, Literal, Optional, Union