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

wandb/apis/public/jobs.py

@@ -1,4 +1,8 @@
-"""Public API: jobs."""
+"""W&B Public API for management Launch Jobs and Launch Queues.
+
+This module provides classes for managing W&B jobs, queued runs, and run
+queues.
+"""
 
 import json
 import os
@@ -78,6 +82,7 @@ class Job:
 
     @property
     def name(self):
+        """The name of the job."""
         return self._name
 
     def _set_configure_launch_project(self, func):
@@ -162,6 +167,7 @@ class Job:
             launch_project.set_job_entry_point(self._entrypoint)
 
     def set_entrypoint(self, entrypoint: List[str]):
+        """Set the entrypoint for the job."""
         self._entrypoint = entrypoint
 
     def call(
@@ -176,6 +182,29 @@ class Job:
         project_queue=None,
         priority=None,
     ):
+        """Call the job with the given configuration.
+
+        Args:
+            config (dict): The configuration to pass to the job.
+                This should be a dictionary containing key-value pairs that
+                match the input types defined in the job.
+            project (str, optional): The project to log the run to. Defaults
+                to the job's project.
+            entity (str, optional): The entity to log the run under. Defaults
+                to the job's entity.
+            queue (str, optional): The name of the queue to enqueue the job to.
+                Defaults to None.
+            resource (str, optional): The resource type to use for execution.
+                Defaults to "local-container".
+            resource_args (dict, optional): Additional arguments for the
+                resource type. Defaults to None.
+            template_variables (dict, optional): Template variables to use for
+                the job. Defaults to None.
+            project_queue (str, optional): The project that manages the queue.
+                Defaults to None.
+            priority (int, optional): The priority of the queued run.
+                Defaults to None.
+        """
         from wandb.sdk.launch import _launch_add
 
         run_config = {}
@@ -212,7 +241,19 @@ class Job:
 
 
 class QueuedRun:
-    """A single queued run associated with an entity and project. Call `run = queued_run.wait_until_running()` or `run = queued_run.wait_until_finished()` to access the run."""
+    """A single queued run associated with an entity and project.
+
+    Args:
+        entity: The entity associated with the queued run.
+        project (str): The project where runs executed by the queue are logged to.
+        queue_name (str): The name of the queue.
+        run_queue_item_id (int): The id of the run queue item.
+        project_queue (str): The project that manages the queue.
+        priority (str): The priority of the queued run.
+
+    Call `run = queued_run.wait_until_running()` or
+    `run = queued_run.wait_until_finished()` to access the run.
+    """
 
     def __init__(
         self,
@@ -236,22 +277,27 @@ class QueuedRun:
 
     @property
     def queue_name(self):
+        """The name of the queue."""
         return self._queue_name
 
     @property
     def id(self):
+        """The id of the queued run."""
         return self._run_queue_item_id
 
     @property
     def project(self):
+        """The project associated with the queued run."""
         return self._project
 
     @property
     def entity(self):
+        """The entity associated with the queued run."""
         return self._entity
 
     @property
     def state(self):
+        """The state of the queued run."""
         item = self._get_item()
         if item:
             return item["state"].lower()
@@ -327,6 +373,7 @@ class QueuedRun:
 
     @normalize_exceptions
     def wait_until_finished(self):
+        """Wait for the queued run to complete and return the finished run."""
         if not self._run:
             self.wait_until_running()
 
@@ -388,6 +435,7 @@ class QueuedRun:
 
     @normalize_exceptions
     def wait_until_running(self):
+        """Wait until the queued run is running and return the run."""
         if self._run is not None:
             return self._run
 
@@ -426,6 +474,20 @@ RunQueuePrioritizationMode = Literal["DISABLED", "V0"]
 
 
 class RunQueue:
+    """Class that represents a run queue in W&B.
+
+    Args:
+        client: W&B API client instance.
+        name: Name of the run queue
+        entity: The entity (user or team) that owns this queue
+        prioritization_mode: Queue priority mode
+            Can be "DISABLED" or "V0". Defaults to `None`.
+        _access: Access level for the queue
+            Can be "project" or "user". Defaults to `None`.
+        _default_resource_config_id: ID of default resource config
+        _default_resource_config: Default resource configuration
+    """
+
     def __init__(
         self,
         client: "RetryingClient",
@@ -450,32 +512,41 @@ class RunQueue:
 
     @property
     def name(self):
+        """The name of the queue."""
         return self._name
 
     @property
     def entity(self):
+        """The entity that owns the queue."""
         return self._entity
 
     @property
     def prioritization_mode(self) -> RunQueuePrioritizationMode:
+        """The prioritization mode of the queue.
+
+        Can be set to "DISABLED" or "V0".
+        """
         if self._prioritization_mode is None:
             self._get_metadata()
         return self._prioritization_mode
 
     @property
     def access(self) -> RunQueueAccessType:
+        """The access level of the queue."""
         if self._access is None:
             self._get_metadata()
         return self._access
 
     @property
     def external_links(self) -> Dict[str, str]:
+        """External resource links for the queue."""
         if self._external_links is None:
             self._get_metadata()
         return self._external_links
 
     @property
     def type(self) -> RunQueueResourceType:
+        """The resource type for execution."""
         if self._type is None:
             if self._default_resource_config_id is None:
                 self._get_metadata()
@@ -484,6 +555,7 @@ class RunQueue:
 
     @property
     def default_resource_config(self):
+        """The default configuration for resources."""
         if self._default_resource_config is None:
             if self._default_resource_config_id is None:
                 self._get_metadata()
@@ -492,6 +564,7 @@ class RunQueue:
 
     @property
     def template_variables(self):
+        """Variables for resource templates."""
         if self._template_variables is None:
             if self._default_resource_config_id is None:
                 self._get_metadata()
@@ -500,6 +573,7 @@ class RunQueue:
 
     @property
     def id(self) -> str:
+        """The id of the queue."""
         if self._id is None:
             self._get_metadata()
         return self._id
@@ -648,6 +722,20 @@ class RunQueue:
         config: Optional[dict] = None,
         template_variables: Optional[dict] = None,
     ) -> "RunQueue":
+        """Create a RunQueue.
+
+        Args:
+            name: The name of the run queue to create.
+            resource: The resource type for execution.
+            entity: The entity (user or team) that will own the queue.
+                Defaults to the default entity of the API client.
+            prioritization_mode: The prioritization mode for the queue.
+                Can be "DISABLED" or "V0". Defaults to None.
+            config: Optional dictionary for the default resource
+                configuration. Defaults to None.
+            template_variables: Optional dictionary for template variables
+                used in the resource configuration.
+        """
         public_api = Api()
         return public_api.create_run_queue(
             name, resource, entity, prioritization_mode, config, template_variables

wandb/apis/public/projects.py

@@ -1,6 +1,35 @@
-"""Public API: projects."""
+"""W&B Public API for Project objects.
 
-from contextlib import suppress
+This module provides classes for interacting with W&B projects and their
+associated data.
+
+Example:
+```python
+from wandb.apis.public import Api
+
+# Get all projects for an entity
+projects = Api().projects("entity")
+
+# Access project data
+for project in projects:
+    print(f"Project: {project.name}")
+    print(f"URL: {project.url}")
+
+    # Get artifact types
+    for artifact_type in project.artifacts_types():
+        print(f"Artifact Type: {artifact_type.name}")
+
+    # Get sweeps
+    for sweep in project.sweeps():
+        print(f"Sweep ID: {sweep.id}")
+        print(f"State: {sweep.state}")
+```
+
+Note:
+    This module is part of the W&B Public API and provides methods to access
+    and manage projects. For creating new projects, use wandb.init()
+    with a new project name.
+"""
 
 from requests import HTTPError
 from wandb_gql import gql
@@ -10,6 +39,7 @@ 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.apis.public.sweeps import Sweeps
 from wandb.sdk.lib import ipython
 
 PROJECT_FRAGMENT = """fragment ProjectFragment on Project {
@@ -22,10 +52,32 @@ PROJECT_FRAGMENT = """fragment ProjectFragment on Project {
 
 
 class Projects(Paginator["Project"]):
-    """An iterable collection of `Project` objects."""
+    """An lazy iterator of `Project` objects.
 
-    QUERY = gql(
-        """
+    An iterable interface to access projects created and saved by the entity.
+
+    Args:
+        client (`wandb.apis.internal.Api`): The API client instance to use.
+        entity (str): The entity name (username or team) to fetch projects for.
+        per_page (int): Number of projects to fetch per request (default is 50).
+
+    Example:
+    ```python
+    from wandb.apis.public.api import Api
+
+    # Find projects that belong to this entity
+    projects = Api().projects(entity="entity")
+
+    # Iterate over files
+    for project in projects:
+        print(f"Project: {project.name}")
+        print(f"- URL: {project.url}")
+        print(f"- Created at: {project.created_at}")
+        print(f"- Is benchmark: {project.is_benchmark}")
+    ```
+    """
+
+    QUERY = gql(f"""#graphql
         query Projects($entity: String, $cursor: String, $perPage: Int = 50) {{
             models(entityName: $entity, after: $cursor, first: $perPage) {{
                 edges {{
@@ -40,9 +92,8 @@ class Projects(Paginator["Project"]):
                 }}
             }}
         }}
-        {}
-        """.format(PROJECT_FRAGMENT)
-    )
+        {PROJECT_FRAGMENT}
+    """)
 
     def __init__(
         self,
@@ -66,11 +117,22 @@ class Projects(Paginator["Project"]):
 
     @property
     def length(self) -> None:
+        """Returns the total number of projects.
+
+        Note: This property is not available for projects.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         # For backwards compatibility, even though this isn't a SizedPaginator
         return None
 
     @property
     def more(self):
+        """Returns `True` if there are more projects to fetch. Returns
+        `False` if there are no more projects to fetch.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if self.last_response:
             return self.last_response["models"]["pageInfo"]["hasNextPage"]
         else:
@@ -78,12 +140,20 @@ class Projects(Paginator["Project"]):
 
     @property
     def cursor(self):
+        """Returns the cursor position for pagination of project results.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if self.last_response:
             return self.last_response["models"]["edges"][-1]["cursor"]
         else:
             return None
 
     def convert_objects(self):
+        """Converts GraphQL edges to File objects.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         return [
             Project(self.client, self.entity, p["node"]["name"], p["node"])
             for p in self.last_response["models"]["edges"]
@@ -94,17 +164,22 @@ class Projects(Paginator["Project"]):
 
 
 class Project(Attrs):
-    """A project is a namespace for runs."""
-
-    QUERY = gql(
-        """
-        query Project($project: String!, $entity: String!) {
-            project(name: $project, entityName: $entity) {
-                id
-            }
-        }
-        """
-    )
+    """A project is a namespace for runs.
+
+    Args:
+        client: W&B API client instance.
+        name (str): The name of the project.
+        entity (str): The entity name that owns the project.
+    """
+
+    QUERY = gql(f"""#graphql
+        query Project($project: String!, $entity: String!) {{
+            project(name: $project, entityName: $entity) {{
+                ...ProjectFragment
+            }}
+        }}
+        {PROJECT_FRAGMENT}
+    """)
 
     def __init__(
         self,
@@ -122,20 +197,37 @@ class Project(Attrs):
             attrs: The attributes of the project.
         """
         super().__init__(dict(attrs))
+        self._is_loaded = bool(attrs)
         self.client = client
         self.name = project
         self.entity = entity
 
+    def _load(self):
+        variable_values = {"project": self.name, "entity": self.entity}
+        try:
+            response = self.client.execute(self.QUERY, variable_values)
+        except HTTPError as e:
+            raise ValueError(f"Unable to fetch project ID: {variable_values!r}") from e
+
+        self._attrs = response["project"]
+        self._is_loaded = True
+
     @property
     def path(self):
+        """Returns the path of the project. The path is a list containing the
+        entity and project name."""
         return [self.entity, self.name]
 
     @property
     def url(self):
+        """Returns the URL of the project."""
         return self.client.app_url + "/".join(self.path + ["workspace"])
 
     def to_html(self, height=420, hidden=False):
-        """Generate HTML containing an iframe displaying this project."""
+        """Generate HTML containing an iframe displaying this project.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         url = self.url + "?jupyter=true"
         style = f"border:none;width:100%;height:{height}px;"
         prefix = ""
@@ -152,74 +244,33 @@ class Project(Attrs):
 
     @normalize_exceptions
     def artifacts_types(self, per_page=50):
+        """Returns all artifact types associated with this project."""
         return public.ArtifactTypes(self.client, self.entity, self.name)
 
     @normalize_exceptions
-    def sweeps(self):
-        query = gql(
-            """
-            query GetSweeps($project: String!, $entity: String!) {{
-                project(name: $project, entityName: $entity) {{
-                    totalSweeps
-                    sweeps {{
-                        edges {{
-                            node {{
-                                ...SweepFragment
-                            }}
-                            cursor
-                        }}
-                        pageInfo {{
-                            endCursor
-                            hasNextPage
-                        }}
-                    }}
-                }}
-            }}
-            {}
-            """.format(public.SWEEP_FRAGMENT)
-        )
-        variable_values = {"project": self.name, "entity": self.entity}
-        ret = self.client.execute(query, variable_values)
-        if not ret.get("project") or ret["project"]["totalSweeps"] < 1:
-            return []
+    def sweeps(self, per_page=50):
+        """Return a paginated collection of sweeps in this project.
 
-        return [
-            # match format of existing public sweep apis
-            public.Sweep(
-                self.client,
-                self.entity,
-                self.name,
-                e["node"]["name"],
-            )
-            for e in ret["project"]["sweeps"]["edges"]
-        ]
+        Args:
+            per_page: The number of sweeps to fetch per request to the API.
 
-    _PROJECT_ID = gql(
+        Returns:
+            A `Sweeps` object, which is an iterable collection of `Sweep` objects.
         """
-        query ProjectID($projectName: String!, $entityName: String!) {
-            project(name: $projectName, entityName: $entityName) {
-                id
-            }
-        }
-        """
-    )
+        return Sweeps(self.client, self.entity, self.name, per_page=per_page)
 
     @property
     def id(self) -> str:
-        # This is a workaround to ensure that the project ID can be retrieved
-        # on demand, as it generally is not set or fetched on instantiation.
-        # This is necessary if using this project as the scope of a new Automation.
-        with suppress(LookupError):
-            return self._attrs["id"]
+        if not self._is_loaded:
+            self._load()
 
-        variable_values = {"projectName": self.name, "entityName": self.entity}
-        try:
-            data = self.client.execute(self._PROJECT_ID, variable_values)
+        if "id" not in self._attrs:
+            raise ValueError(f"Project {self.name} not found")
 
-            if not data.get("project") or not data["project"].get("id"):
-                raise ValueError(f"Project {self.name} not found")
+        return self._attrs["id"]
 
-            self._attrs["id"] = data["project"]["id"]
-            return self._attrs["id"]
-        except (HTTPError, LookupError, TypeError) as e:
-            raise ValueError(f"Unable to fetch project ID: {variable_values!r}") from e
+    def __getattr__(self, name: str):
+        if not self._is_loaded:
+            self._load()
+
+        return super().__getattr__(name)

wandb/apis/public/query_generator.py

@@ -1,5 +1,8 @@
 class QueryGenerator:
-    """QueryGenerator is a helper object to write filters for runs."""
+    """QueryGenerator is a helper object to write filters for runs.
+
+    <!-- lazydoc-ignore-class: internal -->
+    """
 
     INDIVIDUAL_OP_TO_MONGO = {
         "!=": "$ne",
@@ -21,6 +24,7 @@ class QueryGenerator:
 
     @classmethod
     def format_order_key(cls, key: str):
+        """Format a key for sorting."""
         if key.startswith(("+", "-")):
             direction = key[0]
             key = key[1:]
@@ -50,6 +54,7 @@ class QueryGenerator:
             return {self.INDIVIDUAL_OP_TO_MONGO[op]: value}
 
     def key_to_server_path(self, key):
+        """Convert a key dictionary to the corresponding server path string."""
         if key["section"] == "config":
             return "config." + key["name"]
         elif key["section"] == "summary":
@@ -63,6 +68,7 @@ class QueryGenerator:
         raise ValueError("Invalid key: {}".format(key))
 
     def server_path_to_key(self, path):
+        """Convert a server path string to the corresponding key dictionary."""
         if path.startswith("config."):
             return {"section": "config", "name": path.split("config.", 1)[1]}
         elif path.startswith("summary_metrics."):
@@ -75,6 +81,7 @@ class QueryGenerator:
             return {"section": "run", "name": path}
 
     def keys_to_order(self, keys):
+        """Convert a list of key dictionaries to an order string."""
         orders = []
         for key in keys["keys"]:
             order = self.key_to_server_path(key["key"])
@@ -87,6 +94,7 @@ class QueryGenerator:
         return orders
 
     def order_to_keys(self, order):
+        """Convert an order string to a list of key dictionaries."""
         keys = []
         for k in order:  # orderstr.split(","):
             name = k[1:]
@@ -127,6 +135,7 @@ class QueryGenerator:
         return {path: self._to_mongo_op_value(filter["op"], filter["value"])}
 
     def filter_to_mongo(self, filter):
+        """Returns dictionary with filter format converted to MongoDB filter."""
         if self._is_individual(filter):
             return self._to_mongo_individual(filter)
         elif self._is_group(filter):
@@ -137,6 +146,7 @@ class QueryGenerator:
             }
 
     def mongo_to_filter(self, filter):
+        """Returns dictionary with MongoDB filter converted to filter format."""
         # Returns {"op": "OR", "filters": [{"op": "AND", "filters": []}]}
         if filter is None:
             return None  # this covers the case where self.filter_to_mongo returns None.

wandb/apis/public/registries/_utils.py

@@ -1,6 +1,8 @@
+from __future__ import annotations
+
 from enum import Enum
 from functools import lru_cache
-from typing import TYPE_CHECKING, Any, List, Literal, Mapping, Optional, Sequence
+from typing import TYPE_CHECKING, Any, Literal, Mapping, Sequence
 
 from wandb.sdk.artifacts._validators import (
     REGISTRY_PREFIX,
@@ -21,15 +23,12 @@ class Visibility(str, Enum):
 
     @classmethod
     def _missing_(cls, value: object) -> Any:
-        return next(
-            (e for e in cls if e.name == value),
-            None,
-        )
+        return next((e for e in cls if e.name == value), None)
 
 
 def format_gql_artifact_types_input(
-    artifact_types: Optional[List[str]] = None,
-):
+    artifact_types: list[str] | None,
+) -> list[dict[str, str]]:
     """Format the artifact types for the GQL input.
 
     Args:
@@ -40,8 +39,7 @@ def format_gql_artifact_types_input(
     """
     if artifact_types is None:
         return []
-    new_types = validate_artifact_types_list(artifact_types)
-    return [{"name": type} for type in new_types]
+    return [{"name": typ} for typ in validate_artifact_types_list(artifact_types)]
 
 
 def gql_to_registry_visibility(
@@ -67,14 +65,14 @@ def registry_visibility_to_gql(
     """Convert the registry visibility to the GQL visibility."""
     try:
         return Visibility[visibility].value
-    except KeyError:
+    except LookupError:
+        allowed_str = ", ".join(map(repr, (e.name for e in Visibility)))
         raise ValueError(
-            f"Invalid visibility: {visibility!r}. "
-            f"Must be one of: {', '.join(map(repr, (e.name for e in Visibility)))}"
+            f"Invalid visibility: {visibility!r}. Must be one of: {allowed_str}"
         )
 
 
-def ensure_registry_prefix_on_names(query, in_name=False):
+def ensure_registry_prefix_on_names(query: Any, in_name: bool = False) -> Any:
     """Traverse the filter to prepend the `name` key value with the registry prefix unless the value is a regex.
 
     - in_name: True if we are under a "name" key (or propagating from one).
@@ -105,7 +103,7 @@ def ensure_registry_prefix_on_names(query, in_name=False):
 
 
 @lru_cache(maxsize=10)
-def fetch_org_entity_from_organization(client: "Client", organization: str) -> str:
+def fetch_org_entity_from_organization(client: Client, organization: str) -> str:
     """Fetch the org entity from the organization.
 
     Args:
@@ -127,7 +125,7 @@ def fetch_org_entity_from_organization(client: "Client", organization: str) -> s
         response = client.execute(query, variable_values={"organization": organization})
     except Exception as e:
         raise ValueError(
-            f"Error fetching org entity for organization: {organization}"
+            f"Error fetching org entity for organization: {organization!r}"
         ) from e
 
     if (
@@ -135,6 +133,6 @@ def fetch_org_entity_from_organization(client: "Client", organization: str) -> s
         or not (org_entity := org["orgEntity"])
         or not (org_name := org_entity["name"])
     ):
-        raise ValueError(f"Organization entity for {organization} not found.")
+        raise ValueError(f"Organization entity for {organization!r} not found.")
 
     return org_name