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

wandb/apis/public/api.py

@@ -51,6 +51,7 @@ from wandb.apis.public.utils import (
 )
 from wandb.proto.wandb_deprecated import Deprecated
 from wandb.proto.wandb_internal_pb2 import ServerFeature
+from wandb.sdk import wandb_login
 from wandb.sdk.artifacts._validators import is_artifact_registry_project
 from wandb.sdk.internal.internal_api import Api as InternalApi
 from wandb.sdk.internal.thread_local_settings import _thread_local_api_settings
@@ -75,6 +76,11 @@ logger = logging.getLogger(__name__)
 
 
 class RetryingClient:
+    """A GraphQL client that retries requests on failure.
+
+    <!-- lazydoc-ignore-class: internal -->
+    """
+
     INFO_QUERY = gql(
         """
         query ServerInfo{
@@ -135,16 +141,14 @@ class RetryingClient:
 
 
 class Api:
-    """Used for querying the wandb server.
+    """Used for querying the W&B server.
 
     Examples:
-        Most common way to initialize
-        >>> wandb.Api()
+    ```python
+    import wandb
 
-    Args:
-        overrides: (dict) You can set `base_url` if you are using a wandb server
-            other than https://api.wandb.ai.
-            You can also set defaults for `entity`, `project`, and `run`.
+    wandb.Api()
+    ```
     """
 
     _HTTP_TIMEOUT = env.get_http_timeout(19)
@@ -275,6 +279,17 @@ class Api:
         timeout: Optional[int] = None,
         api_key: Optional[str] = None,
     ) -> None:
+        """Initialize the API.
+
+        Args:
+            overrides: You can set `base_url` if you are
+                using a W&B server other than `https://api.wandb.ai`. You can also
+                set defaults for `entity`, `project`, and `run`.
+            timeout: HTTP timeout in seconds for API requests. If not
+                specified, the default timeout will be used.
+            api_key: API key to use for authentication. If not provided,
+                the API key from the current environment or configuration will be used.
+        """
         self.settings = InternalApi().settings()
 
         _overrides = overrides or {}
@@ -289,8 +304,18 @@ class Api:
             self.settings["entity"] = _overrides["username"]
 
         self._api_key = api_key
-        if self.api_key is None and _thread_local_api_settings.cookies is None:
-            wandb.login(host=_overrides.get("base_url"))
+        if _thread_local_api_settings.cookies is None:
+            wandb_login._login(
+                host=self.settings["base_url"],
+                key=self.api_key,
+                verify=True,
+                _silent=(
+                    self.settings.get("silent", False)
+                    or self.settings.get("quiet", False)
+                ),
+                update_api_key=False,
+                _disable_warning=True,
+            )
 
         self._viewer = None
         self._projects = {}
@@ -323,13 +348,32 @@ class Api:
             )
         )
         self._client = RetryingClient(self._base_client)
+        self._sentry = wandb.analytics.sentry.Sentry()
+        self._configure_sentry()
+
+    def _configure_sentry(self) -> None:
+        try:
+            viewer = self.viewer
+        except (ValueError, requests.RequestException):
+            # we need the viewer to configure the entity, and user email
+            return
+
+        email = viewer.email if viewer else None
+        entity = self.default_entity
+
+        self._sentry.configure_scope(
+            tags={
+                "entity": entity,
+                "email": email,
+            },
+        )
 
     def create_project(self, name: str, entity: str) -> None:
         """Create a new project.
 
         Args:
-            name: (str) The name of the new project.
-            entity: (str) The entity of the new project.
+            name: The name of the new project.
+            entity: The entity of the new project.
         """
         self.client.execute(self.CREATE_PROJECT, {"entityName": entity, "name": name})
 
@@ -343,10 +387,12 @@ class Api:
         """Create a new run.
 
         Args:
-            run_id: (str, optional) The ID to assign to the run, if given.  The run ID is automatically generated by
-                default, so in general, you do not need to specify this and should only do so at your own risk.
-            project: (str, optional) If given, the project of the new run.
-            entity: (str, optional) If given, the entity of the new run.
+            run_id: The ID to assign to the run. If not specified, W&B
+                creates a random ID.
+            project: The project where to log the run to. If no project is specified,
+                log the run to a project called "Uncategorized".
+            entity: The entity that owns the project. If no entity is
+                specified, log the run to the default entity.
 
         Returns:
             The newly created `Run`.
@@ -364,33 +410,28 @@ class Api:
         config: Optional[dict] = None,
         template_variables: Optional[dict] = None,
     ) -> "public.RunQueue":
-        """Create a new run queue (launch).
+        """Create a new run queue in W&B Launch.
 
         Args:
-            name: (str) Name of the queue to create
-            type: (str) Type of resource to be used for the queue. One of "local-container", "local-process", "kubernetes", "sagemaker", or "gcp-vertex".
-            entity: (str) Optional name of the entity to create the queue. If None, will use the configured or default entity.
-            prioritization_mode: (str) Optional version of prioritization to use. Either "V0" or None
-            config: (dict) Optional default resource configuration to be used for the queue. Use handlebars (eg. `{{var}}`) to specify template variables.
-            template_variables: (dict) A dictionary of template variable schemas to be used with the config. Expected format of:
-                `{
-                    "var-name": {
-                        "schema": {
-                            "type": ("string", "number", or "integer"),
-                            "default": (optional value),
-                            "minimum": (optional minimum),
-                            "maximum": (optional maximum),
-                            "enum": [..."(options)"]
-                        }
-                    }
-                }`
+            name: Name of the queue to create
+            type: Type of resource to be used for the queue. One of
+                "local-container", "local-process", "kubernetes","sagemaker",
+                or "gcp-vertex".
+            entity: Name of the entity to create the queue. If `None`, use
+                the configured or default entity.
+            prioritization_mode: Version of prioritization to use.
+                Either "V0" or `None`.
+            config: Default resource configuration to be used for the queue.
+                Use handlebars (eg. `{{var}}`) to specify template variables.
+            template_variables: A dictionary of template variable schemas to
+                use with the config.
 
         Returns:
-            The newly created `RunQueue`
+            The newly created `RunQueue`.
 
         Raises:
-            ValueError if any of the parameters are invalid
-            wandb.Error on wandb API errors
+            `ValueError` if any of the parameters are invalid
+            `wandb.Error` on wandb API errors
         """
         # TODO(np): Need to check server capabilities for this feature
         # 0. assert params are valid/normalized
@@ -467,6 +508,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,
@@ -477,30 +597,24 @@ class Api:
         external_links: Optional[dict] = None,
         prioritization_mode: Optional["public.RunQueuePrioritizationMode"] = None,
     ):
-        """Upsert a run queue (launch).
+        """Upsert a run queue in W&B Launch.
 
         Args:
-            name: (str) Name of the queue to create
-            entity: (str) Optional name of the entity to create the queue. If None, will use the configured or default entity.
-            resource_config: (dict) Optional default resource configuration to be used for the queue. Use handlebars (eg. `{{var}}`) to specify template variables.
-            resource_type: (str) Type of resource to be used for the queue. One of "local-container", "local-process", "kubernetes", "sagemaker", or "gcp-vertex".
-            template_variables: (dict) A dictionary of template variable schemas to be used with the config. Expected format of:
-                `{
-                    "var-name": {
-                        "schema": {
-                            "type": ("string", "number", or "integer"),
-                            "default": (optional value),
-                            "minimum": (optional minimum),
-                            "maximum": (optional maximum),
-                            "enum": [..."(options)"]
-                        }
-                    }
-                }`
-            external_links: (dict) Optional dictionary of external links to be used with the queue. Expected format of:
-                `{
-                    "name": "url"
-                }`
-            prioritization_mode: (str) Optional version of prioritization to use. Either "V0" or None
+            name: Name of the queue to create
+            entity: Optional name of the entity to create the queue. If `None`,
+                use the configured or default entity.
+            resource_config: Optional default resource configuration to be used
+                for the queue. Use handlebars (eg. `{{var}}`) to specify
+                template variables.
+            resource_type: Type of resource to be used for the queue. One of
+                "local-container", "local-process", "kubernetes", "sagemaker",
+                or "gcp-vertex".
+            template_variables: A dictionary of template variable schemas to
+                be used with the config.
+            external_links: Optional dictionary of external links to be used
+                with the queue.
+            prioritization_mode: Optional version of prioritization to use.
+                Either "V0" or None
 
         Returns:
             The upserted `RunQueue`.
@@ -582,15 +696,15 @@ class Api:
             entity=entity,
         )
 
-    def create_user(self, email, admin=False):
+    def create_user(self, email: str, admin: Optional[bool] = False):
         """Create a new user.
 
         Args:
-            email: (str) The email address of the user
-            admin: (bool) Whether this user should be a global instance admin
+            email: The email address of the user.
+            admin: Set user as a global instance administrator.
 
         Returns:
-            A `User` object
+            A `User` object.
         """
         return public.User.create(self, email, admin)
 
@@ -620,14 +734,17 @@ class Api:
 
     @property
     def client(self) -> RetryingClient:
+        """Returns the client object."""
         return self._client
 
     @property
     def user_agent(self) -> str:
+        """Returns W&B public user agent."""
         return "W&B Public Client {}".format(wandb.__version__)
 
     @property
     def api_key(self) -> Optional[str]:
+        """Returns W&B API key."""
         # just use thread local api key if it's set
         if _thread_local_api_settings.api_key:
             return _thread_local_api_settings.api_key
@@ -645,6 +762,7 @@ class Api:
 
     @property
     def default_entity(self) -> Optional[str]:
+        """Returns the default W&B entity."""
         if self._default_entity is None:
             res = self._client.execute(self.DEFAULT_ENTITY_QUERY)
             self._default_entity = (res.get("viewer") or {}).get("entity")
@@ -652,42 +770,62 @@ class Api:
 
     @property
     def viewer(self) -> "public.User":
+        """Returns the viewer object.
+
+        Raises:
+            ValueError: If viewer data is not able to be fetched from W&B.
+            requests.RequestException: If an error occurs while making the graphql request.
+        """
         if self._viewer is None:
-            self._viewer = public.User(
-                self._client, self._client.execute(self.VIEWER_QUERY).get("viewer")
-            )
+            viewer = self._client.execute(self.VIEWER_QUERY).get("viewer")
+
+            if viewer is None:
+                raise ValueError(
+                    "Unable to fetch user data from W&B,"
+                    " please verify your API key is valid."
+                )
+
+            self._viewer = public.User(self._client, viewer)
             self._default_entity = self._viewer.entity
         return self._viewer
 
     def flush(self):
         """Flush the local cache.
 
-        The api object keeps a local cache of runs, so if the state of the run may
-        change while executing your script you must clear the local cache with
-        `api.flush()` to get the latest values associated with the run.
+        The api object keeps a local cache of runs, so if the state of the run
+        may change while executing your script you must clear the local cache
+        with `api.flush()` to get the latest values associated with the run.
         """
         self._runs = {}
 
-    def from_path(self, path):
+    def from_path(self, path: str):
         """Return a run, sweep, project or report from a path.
 
-        Examples:
-            ```
-            project = api.from_path("my_project")
-            team_project = api.from_path("my_team/my_project")
-            run = api.from_path("my_team/my_project/runs/id")
-            sweep = api.from_path("my_team/my_project/sweeps/id")
-            report = api.from_path("my_team/my_project/reports/My-Report-Vm11dsdf")
-            ```
-
         Args:
-            path: (str) The path to the project, run, sweep or report
+            path: The path to the project, run, sweep or report
 
         Returns:
             A `Project`, `Run`, `Sweep`, or `BetaReport` instance.
 
         Raises:
-            wandb.Error if path is invalid or the object doesn't exist
+            `wandb.Error` if path is invalid or the object doesn't exist.
+
+        Examples:
+        In the proceeding code snippets "project", "team", "run_id", "sweep_id",
+        and "report_name" are placeholders for the project, team, run ID,
+        sweep ID, and the name of a specific report, respectively.
+
+        ```python
+        import wandb
+
+        api = wandb.Api()
+
+        project = api.from_path("project")
+        team_project = api.from_path("team/project")
+        run = api.from_path("team/project/runs/run_id")
+        sweep = api.from_path("team/project/sweeps/sweep_id")
+        report = api.from_path("team/project/reports/report_name")
+        ```
         """
         parts = path.strip("/ ").split("/")
         if len(parts) == 1:
@@ -713,7 +851,7 @@ class Api:
                 return public.BetaReport(
                     self.client,
                     {
-                        "display_name": urllib.parse.unquote(name.replace("-", " ")),
+                        "displayName": urllib.parse.unquote(name.replace("-", " ")),
                         "id": id,
                         "spec": "{}",
                     },
@@ -795,12 +933,14 @@ class Api:
         """Get projects for a given entity.
 
         Args:
-            entity: (str) Name of the entity requested.  If None, will fall back to the
-                default entity passed to `Api`.  If no default entity, will raise a `ValueError`.
-            per_page: (int) Sets the page size for query pagination.  Usually there is no reason to change this.
+            entity: Name of the entity requested.  If None, will fall back to
+                the default entity passed to `Api`.  If no default entity,
+                will raise a `ValueError`.
+            per_page: Sets the page size for query pagination. If set to `None`,
+                use the default size. Usually there is no reason to change this.
 
         Returns:
-            A `Projects` object which is an iterable collection of `Project` objects.
+            A `Projects` object which is an iterable collection of `Project`objects.
         """
         if entity is None:
             entity = self.settings["entity"] or self.default_entity
@@ -818,9 +958,10 @@ class Api:
         """Return the `Project` with the given name (and entity, if given).
 
         Args:
-            name: (str) The project name.
-            entity: (str) Name of the entity requested.  If None, will fall back to the
-                default entity passed to `Api`.  If no default entity, will raise a `ValueError`.
+            name: The project name.
+            entity: Name of the entity requested.  If None, will fall back to the
+                default entity passed to `Api`.  If no default entity, will
+                raise a `ValueError`.
 
         Returns:
             A `Project` object.
@@ -844,15 +985,29 @@ class Api:
     ) -> "public.Reports":
         """Get reports for a given project path.
 
-        WARNING: This api is in beta and will likely change in a future release
+        Note: `wandb.Api.reports()` API is in beta and will likely change in
+        future releases.
 
         Args:
-            path: (str) path to project the report resides in, should be in the form: "entity/project"
-            name: (str, optional) optional name of the report requested.
-            per_page: (int) Sets the page size for query pagination.  Usually there is no reason to change this.
+            path: The path to project the report resides in. Specify the
+                entity that created the project as a prefix followed by a
+                forward slash.
+            name: Name of the report requested.
+            per_page: Sets the page size for query pagination. If set to
+                `None`, use the default size. Usually there is no reason to
+                change this.
 
         Returns:
-            A `Reports` object which is an iterable collection of `BetaReport` objects.
+            A `Reports` object which is an iterable collection of
+                `BetaReport` objects.
+
+        Examples:
+        ```python
+        import wandb
+
+        wandb.Api.reports("entity/project")
+        ```
+
         """
         entity, project, _ = self._parse_path(path + "/fake_run")
 
@@ -871,15 +1026,18 @@ class Api:
             )
         return self._reports[key]
 
-    def create_team(self, team, admin_username=None):
+    def create_team(
+        self, team: str, admin_username: Optional[str] = None
+    ) -> "public.Team":
         """Create a new team.
 
         Args:
-            team: (str) The name of the team
-            admin_username: (str) optional username of the admin user of the team, defaults to the current user.
+            team: The name of the team
+            admin_username: Username of the admin user of the team.
+                Defaults to the current user.
 
         Returns:
-            A `Team` object
+            A `Team` object.
         """
         return public.Team.create(self, team, admin_username)
 
@@ -887,7 +1045,7 @@ class Api:
         """Return the matching `Team` with the given name.
 
         Args:
-            team: (str) The name of the team.
+            team: The name of the team.
 
         Returns:
             A `Team` object.
@@ -897,13 +1055,14 @@ class Api:
     def user(self, username_or_email: str) -> Optional["public.User"]:
         """Return a user from a username or email address.
 
-        Note: This function only works for Local Admins, if you are trying to get your own user object, please use `api.viewer`.
+        This function only works for local administrators. Use `api.viewer`
+            to get your own user object.
 
         Args:
-            username_or_email: (str) The username or email address of the user
+            username_or_email: The username or email address of the user.
 
         Returns:
-            A `User` object or None if a user couldn't be found
+            A `User` object or None if a user is not found.
         """
         res = self._client.execute(self.USERS_QUERY, {"query": username_or_email})
         if len(res["users"]["edges"]) == 0:
@@ -919,13 +1078,14 @@ class Api:
     def users(self, username_or_email: str) -> List["public.User"]:
         """Return all users from a partial username or email address query.
 
-        Note: This function only works for Local Admins, if you are trying to get your own user object, please use `api.viewer`.
+        This function only works for local administrators. Use `api.viewer`
+            to get your own user object.
 
         Args:
-            username_or_email: (str) The prefix or suffix of the user you want to find
+            username_or_email: The prefix or suffix of the user you want to find.
 
         Returns:
-            An array of `User` objects
+            An array of `User` objects.
         """
         res = self._client.execute(self.USERS_QUERY, {"query": username_or_email})
         return [
@@ -940,7 +1100,7 @@ class Api:
         per_page: int = 50,
         include_sweeps: bool = True,
     ):
-        """Return a set of runs from a project that match the filters provided.
+        """Returns a `Runs` object, which lazily iterates over `Run` objects.
 
         Fields you can filter by include:
         - `createdAt`: The timestamp when the run was created. (in ISO 8601 format, e.g. "2023-01-01T12:00:00Z")
@@ -975,64 +1135,6 @@ class Api:
         - `$regex`
 
 
-        Examples:
-            Find runs in my_project where config.experiment_name has been set to "foo"
-            ```
-            api.runs(
-                path="my_entity/my_project",
-                filters={"config.experiment_name": "foo"},
-            )
-            ```
-
-            Find runs in my_project where config.experiment_name has been set to "foo" or "bar"
-            ```
-            api.runs(
-                path="my_entity/my_project",
-                filters={
-                    "$or": [
-                        {"config.experiment_name": "foo"},
-                        {"config.experiment_name": "bar"},
-                    ]
-                },
-            )
-            ```
-
-            Find runs in my_project where config.experiment_name matches a regex (anchors are not supported)
-            ```
-            api.runs(
-                path="my_entity/my_project",
-                filters={"config.experiment_name": {"$regex": "b.*"}},
-            )
-            ```
-
-            Find runs in my_project where the run name matches a regex (anchors are not supported)
-            ```
-            api.runs(
-                path="my_entity/my_project",
-                filters={"display_name": {"$regex": "^foo.*"}},
-            )
-            ```
-
-            Find runs in my_project where config.experiment contains a nested field "category" with value "testing"
-            ```
-            api.runs(
-                path="my_entity/my_project",
-                filters={"config.experiment.category": "testing"},
-            )
-            ```
-
-            Find runs in my_project with a loss value of 0.5 nested in a dictionary under model1 in the summary metrics
-            ```
-            api.runs(
-                path="my_entity/my_project",
-                filters={"summary_metrics.model1.loss": 0.5},
-            )
-            ```
-
-            Find runs in my_project sorted by ascending loss
-            ```
-            api.runs(path="my_entity/my_project", order="+summary_metrics.loss")
-            ```
 
         Args:
             path: (str) path to project, should be in the form: "entity/project"
@@ -1041,14 +1143,55 @@ class Api:
                 For example: `{"config.experiment_name": "foo"}` would find runs with a config entry
                     of experiment name set to "foo"
             order: (str) Order can be `created_at`, `heartbeat_at`, `config.*.value`, or `summary_metrics.*`.
-                If you prepend order with a + order is ascending.
-                If you prepend order with a - order is descending (default).
+                If you prepend order with a + order is ascending (default).
+                If you prepend order with a - order is descending.
                 The default order is run.created_at from oldest to newest.
             per_page: (int) Sets the page size for query pagination.
             include_sweeps: (bool) Whether to include the sweep runs in the results.
 
         Returns:
             A `Runs` object, which is an iterable collection of `Run` objects.
+
+        Examples:
+        ```python
+        # Find runs in project where config.experiment_name has been set to "foo"
+        api.runs(path="my_entity/project", filters={"config.experiment_name": "foo"})
+        ```
+
+        ```python
+        # Find runs in project where config.experiment_name has been set to "foo" or "bar"
+        api.runs(
+            path="my_entity/project",
+            filters={
+                "$or": [
+                    {"config.experiment_name": "foo"},
+                    {"config.experiment_name": "bar"},
+                ]
+            },
+        )
+        ```
+
+        ```python
+        # Find runs in project where config.experiment_name matches a regex
+        # (anchors are not supported)
+        api.runs(
+            path="my_entity/project",
+            filters={"config.experiment_name": {"$regex": "b.*"}},
+        )
+        ```
+
+        ```python
+        # Find runs in project where the run name matches a regex
+        # (anchors are not supported)
+        api.runs(
+            path="my_entity/project", filters={"display_name": {"$regex": "^foo.*"}}
+        )
+        ```
+
+        ```python
+        # Find runs in project sorted by ascending loss
+        api.runs(path="my_entity/project", order="+summary_metrics.loss")
+        ```
         """
         entity, project = self._parse_project_path(path)
         filters = filters or {}
@@ -1067,10 +1210,10 @@ class Api:
 
     @normalize_exceptions
     def run(self, path=""):
-        """Return a single run by parsing path in the form entity/project/run_id.
+        """Return a single run by parsing path in the form `entity/project/run_id`.
 
         Args:
-            path: (str) path to run in the form `entity/project/run_id`.
+            path: Path to run in the form `entity/project/run_id`.
                 If `api.entity` is set, this can be in the form `project/run_id`
                 and if `api.project` is set this can just be the run_id.
 
@@ -1084,16 +1227,16 @@ class Api:
 
     def queued_run(
         self,
-        entity,
-        project,
-        queue_name,
-        run_queue_item_id,
+        entity: str,
+        project: str,
+        queue_name: str,
+        run_queue_item_id: str,
         project_queue=None,
         priority=None,
     ):
         """Return a single queued run based on the path.
 
-        Parses paths of the form entity/project/queue_id/run_queue_item_id.
+        Parses paths of the form `entity/project/queue_id/run_queue_item_id`.
         """
         return public.QueuedRun(
             self.client,
@@ -1107,12 +1250,12 @@ class Api:
 
     def run_queue(
         self,
-        entity,
-        name,
+        entity: str,
+        name: str,
     ):
         """Return the named `RunQueue` for entity.
 
-        To create a new `RunQueue`, use `wandb.Api().create_run_queue(...)`.
+        See `Api.create_run_queue` for more information on how to create a run queue.
         """
         return public.RunQueue(
             self.client,
@@ -1125,8 +1268,9 @@ class Api:
         """Return a sweep by parsing path in the form `entity/project/sweep_id`.
 
         Args:
-            path: (str, optional) path to sweep in the form entity/project/sweep_id.  If `api.entity`
-                is set, this can be in the form project/sweep_id and if `api.project` is set
+            path: Path to sweep in the form entity/project/sweep_id.
+                If `api.entity` is set, this can be in the form
+                project/sweep_id and if `api.project` is set
                 this can just be the sweep_id.
 
         Returns:
@@ -1139,10 +1283,10 @@ class Api:
 
     @normalize_exceptions
     def artifact_types(self, project: Optional[str] = None) -> "public.ArtifactTypes":
-        """Return a collection of matching artifact types.
+        """Returns a collection of matching artifact types.
 
         Args:
-            project: (str, optional) If given, a project name or path to filter on.
+            project: The project name or path to filter on.
 
         Returns:
             An iterable `ArtifactTypes` object.
@@ -1162,11 +1306,11 @@ class Api:
     def artifact_type(
         self, type_name: str, project: Optional[str] = None
     ) -> "public.ArtifactType":
-        """Return the matching `ArtifactType`.
+        """Returns the matching `ArtifactType`.
 
         Args:
-            type_name: (str) The name of the artifact type to retrieve.
-            project: (str, optional) If given, a project name or path to filter on.
+            type_name: The name of the artifact type to retrieve.
+            project: If given, a project name or path to filter on.
 
         Returns:
             An `ArtifactType` object.
@@ -1186,12 +1330,13 @@ class Api:
     def artifact_collections(
         self, project_name: str, type_name: str, per_page: int = 50
     ) -> "public.ArtifactCollections":
-        """Return a collection of matching artifact collections.
+        """Returns a collection of matching artifact collections.
 
         Args:
-            project_name: (str) The name of the project to filter on.
-            type_name: (str) The name of the artifact type to filter on.
-            per_page: (int) Sets the page size for query pagination.  Usually there is no reason to change this.
+            project_name: The name of the project to filter on.
+            type_name: The name of the artifact type to filter on.
+            per_page: Sets the page size for query pagination.  None will use the default size.
+                Usually there is no reason to change this.
 
         Returns:
             An iterable `ArtifactCollections` object.
@@ -1212,14 +1357,39 @@ class Api:
     def artifact_collection(
         self, type_name: str, name: str
     ) -> "public.ArtifactCollection":
-        """Return a single artifact collection by type and parsing path in the form `entity/project/name`.
+        """Returns a single artifact collection by type.
+
+        You can use the returned `ArtifactCollection` object to retrieve
+        information about specific artifacts in that collection, and more.
 
         Args:
-            type_name: (str) The type of artifact collection to fetch.
-            name: (str) An artifact collection name. May be prefixed with entity/project.
+            type_name: The type of artifact collection to fetch.
+            name: An artifact collection name. Optionally append the entity
+                that logged the artifact as a prefix followed by a forward
+                slash.
 
         Returns:
             An `ArtifactCollection` object.
+
+        Examples:
+        In the proceeding code snippet "type", "entity", "project", and
+        "artifact_name" are placeholders for the collection type, your W&B
+        entity, name of the project the artifact is in, and the name of
+        the artifact, respectively.
+
+        ```python
+        import wandb
+
+        collections = wandb.Api().artifact_collection(
+            type_name="type", name="entity/project/artifact_name"
+        )
+
+        # Get the first artifact in the collection
+        artifact_example = collections.artifacts()[0]
+
+        # Download the contents of the artifact to the specified root directory.
+        artifact_example.download()
+        ```
         """
         entity, project, collection_name = self._parse_artifact_path(name)
         # If its an Registry artifact, the entity is considered to be an org instead
@@ -1241,7 +1411,7 @@ class Api:
 
     @normalize_exceptions
     def artifact_versions(self, type_name, name, per_page=50):
-        """Deprecated, use `artifacts(type_name, name)` instead."""
+        """Deprecated. Use `Api.artifacts(type_name, name)` method instead."""
         deprecate(
             field_name=Deprecated.api__artifact_versions,
             warning_message=(
@@ -1259,16 +1429,32 @@ class Api:
         per_page: int = 50,
         tags: Optional[List[str]] = None,
     ) -> "public.Artifacts":
-        """Return an `Artifacts` collection from the given parameters.
+        """Return an `Artifacts` collection.
 
         Args:
-            type_name: (str) The type of artifacts to fetch.
-            name: (str) An artifact collection name. May be prefixed with entity/project.
-            per_page: (int) Sets the page size for query pagination.  Usually there is no reason to change this.
-            tags: (list[str], optional) Only return artifacts with all of these tags.
+        type_name: The type of artifacts to fetch.
+        name: The artifact's collection name. Optionally append the
+            entity that logged the artifact as a prefix followed by
+            a forward slash.
+        per_page: Sets the page size for query pagination. If set to
+            `None`, use the default size. Usually there is no reason
+            to change this.
+        tags: Only return artifacts with all of these tags.
 
         Returns:
             An iterable `Artifacts` object.
+
+        Examples:
+        In the proceeding code snippet, "type", "entity", "project", and
+        "artifact_name" are placeholders for the artifact type, W&B entity,
+        name of the project the artifact was logged to,
+        and the name of the artifact, respectively.
+
+        ```python
+        import wandb
+
+        wandb.Api().artifacts(type_name="type", name="entity/project/artifact_name")
+        ```
         """
         entity, project, collection_name = self._parse_artifact_path(name)
         # If its an Registry project, the entity is considered to be an org instead
@@ -1331,22 +1517,47 @@ class Api:
 
     @normalize_exceptions
     def artifact(self, name: str, type: Optional[str] = None):
-        """Return a single artifact by parsing path in the form `project/name` or `entity/project/name`.
+        """Returns a single artifact.
 
         Args:
-            name: (str) An artifact name. May be prefixed with project/ or entity/project/.
-                    If no entity is specified in the name, the Run or API setting's entity is used.
-                Valid names can be in the following forms:
-                    name:version
-                    name:alias
-            type: (str, optional) The type of artifact to fetch.
+            name: The artifact's name. The name of an artifact resembles a
+                filepath that consists, at a minimum, the name of the project
+                the artifact was logged to, the name of the artifact, and the
+                artifact's version or alias. Optionally append the entity that
+                logged the artifact as a prefix followed by a forward slash.
+                If no entity is specified in the name, the Run or API
+                setting's entity is used.
+            type: The type of artifact to fetch.
 
         Returns:
             An `Artifact` object.
 
         Raises:
             ValueError: If the artifact name is not specified.
-            ValueError: If the artifact type is specified but does not match the type of the fetched artifact.
+            ValueError: If the artifact type is specified but does not
+                match the type of the fetched artifact.
+
+        Examples:
+        In the proceeding code snippets "entity", "project", "artifact",
+        "version", and "alias" are placeholders for your W&B entity, name
+        of the project the artifact is in, the name of the artifact,
+        and artifact's version, respectively.
+
+        ```python
+        import wandb
+
+        # Specify the project, artifact's name, and the artifact's alias
+        wandb.Api().artifact(name="project/artifact:alias")
+
+        # Specify the project, artifact's name, and a specific artifact version
+        wandb.Api().artifact(name="project/artifact:version")
+
+        # Specify the entity, project, artifact's name, and the artifact's alias
+        wandb.Api().artifact(name="entity/project/artifact:alias")
+
+        # Specify the entity, project, artifact's name, and a specific artifact version
+        wandb.Api().artifact(name="entity/project/artifact:version")
+        ```
 
         Note:
         This method is intended for external use only. Do not call `api.artifact()` within the wandb repository code.
@@ -1355,11 +1566,11 @@ class Api:
 
     @normalize_exceptions
     def job(self, name: Optional[str], path: Optional[str] = None) -> "public.Job":
-        """Return a `Job` from the given parameters.
+        """Return a `Job` object.
 
         Args:
-            name: (str) The job name.
-            path: (str, optional) If given, the root path in which to download the job artifact.
+            name: The name of the job.
+            path: The root path to download the job artifact.
 
         Returns:
             A `Job` object.
@@ -1377,8 +1588,8 @@ class Api:
         """Return a list of jobs, if any, for the given entity and project.
 
         Args:
-            entity: (str) The entity for the listed job(s).
-            project: (str) The project for the listed job(s).
+            entity: The entity for the listed jobs.
+            project: The project for the listed jobs.
 
         Returns:
             A list of matching jobs.
@@ -1452,19 +1663,33 @@ class Api:
 
     @normalize_exceptions
     def artifact_exists(self, name: str, type: Optional[str] = None) -> bool:
-        """Return whether an artifact version exists within a specified project and entity.
+        """Whether an artifact version exists within the specified project and entity.
 
         Args:
-            name: (str) An artifact name. May be prefixed with entity/project.
-                If entity or project is not specified, it will be inferred from the override params if populated.
-                Otherwise, entity will be pulled from the user settings and project will default to "uncategorized".
-                Valid names can be in the following forms:
-                    name:version
-                    name:alias
-            type: (str, optional) The type of artifact
+            name: The name of artifact. Add the artifact's entity and project
+                as a prefix. Append the version or the alias of the artifact
+                with a colon. If the entity or project is not specified,
+                W&B uses override parameters if populated. Otherwise, the
+                entity is pulled from the user settings and the project is
+                set to "Uncategorized".
+            type: The type of artifact.
 
         Returns:
             True if the artifact version exists, False otherwise.
+
+        Examples:
+        In the proceeding code snippets "entity", "project", "artifact",
+        "version", and "alias" are placeholders for your W&B entity, name of
+        the project the artifact is in, the name of the artifact, and
+        artifact's version, respectively.
+
+        ```python
+        import wandb
+
+        wandb.Api().artifact_exists("entity/project/artifact:version")
+        wandb.Api().artifact_exists("entity/project/artifact:alias")
+        ```
+
         """
         try:
             self._artifact(name, type)
@@ -1475,16 +1700,29 @@ class Api:
 
     @normalize_exceptions
     def artifact_collection_exists(self, name: str, type: str) -> bool:
-        """Return whether an artifact collection exists within a specified project and entity.
+        """Whether an artifact collection exists within a specified project and entity.
 
         Args:
-            name: (str) An artifact collection name. May be prefixed with entity/project.
-                If entity or project is not specified, it will be inferred from the override params if populated.
-                Otherwise, entity will be pulled from the user settings and project will default to "uncategorized".
-            type: (str) The type of artifact collection
+            name: An artifact collection name. Optionally append the
+                entity that logged the artifact as a prefix followed by
+                a forward slash. If entity or project is not specified,
+                infer the collection from the override params if they exist.
+                Otherwise, entity is pulled from the user settings and project
+                will default to "uncategorized".
+            type: The type of artifact collection.
 
         Returns:
             True if the artifact collection exists, False otherwise.
+
+        Examples:
+        In the proceeding code snippet "type", and "collection_name" refer to the type
+        of the artifact collection and the name of the collection, respectively.
+
+        ```python
+        import wandb
+
+        wandb.Api.artifact_collection_exists(type="type", name="collection_name")
+        ```
         """
         try:
             self.artifact_collection(type, name)
@@ -1498,44 +1736,16 @@ class Api:
         organization: Optional[str] = None,
         filter: Optional[Dict[str, Any]] = None,
     ) -> Registries:
-        """Returns a Registry iterator.
+        """Returns a lazy iterator of `Registry` objects.
 
         Use the iterator to search and filter registries, collections,
         or artifact versions across your organization's registry.
 
-        Examples:
-            Find all registries with the names that contain "model"
-            ```python
-            import wandb
-
-            api = wandb.Api()  # specify an org if your entity belongs to multiple orgs
-            api.registries(filter={"name": {"$regex": "model"}})
-            ```
-
-            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"})
-            ```
-
-            Find all artifact versions in the registries with a collection name that contains "my_collection" and a version that has the alias "best"
-            ```python
-            api.registries().collections(
-                filter={"name": {"$regex": "my_collection"}}
-            ).versions(filter={"alias": "best"})
-            ```
-
-            Find all artifact versions in the registries that contain "model" and have the tag "prod" or alias "best"
-            ```python
-            api.registries(filter={"name": {"$regex": "model"}}).versions(
-                filter={"$or": [{"tag": "prod"}, {"alias": "best"}]}
-            )
-            ```
-
         Args:
             organization: (str, optional) The organization of the registry to fetch.
                 If not specified, use the organization specified in the user's settings.
-            filter: (dict, optional) MongoDB-style filter to apply to each object in the registry iterator.
-                Fields available to filter for collections are
+            filter: (dict, optional) MongoDB-style filter to apply to each object in the lazy registry iterator.
+                Fields available to filter for registries are
                     `name`, `description`, `created_at`, `updated_at`.
                 Fields available to filter for collections are
                     `name`, `tag`, `description`, `created_at`, `updated_at`
@@ -1543,7 +1753,39 @@ class Api:
                     `tag`, `alias`, `created_at`, `updated_at`, `metadata`
 
         Returns:
-            A registry iterator.
+            A lazy iterator of `Registry` objects.
+
+        Examples:
+        Find all registries with the names that contain "model"
+
+        ```python
+        import wandb
+
+        api = wandb.Api()  # specify an org if your entity belongs to multiple orgs
+        api.registries(filter={"name": {"$regex": "model"}})
+        ```
+
+        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"})
+        ```
+
+        Find all artifact versions in the registries with a collection name that contains "my_collection" and a version that has the alias "best"
+
+        ```python
+        api.registries().collections(
+            filter={"name": {"$regex": "my_collection"}}
+        ).versions(filter={"alias": "best"})
+        ```
+
+        Find all artifact versions in the registries that contain "model" and have the tag "prod" or alias "best"
+
+        ```python
+        api.registries(filter={"name": {"$regex": "model"}}).versions(
+            filter={"$or": [{"tag": "prod"}, {"alias": "best"}]}
+        )
+        ```
         """
         if not InternalApi()._server_supports(ServerFeature.ARTIFACT_REGISTRY_SEARCH):
             raise RuntimeError(
@@ -1571,15 +1813,16 @@ class Api:
             A registry object.
 
         Examples:
-            Fetch and update a registry
-            ```python
-            import wandb
+        Fetch and update a registry
 
-            api = wandb.Api()
-            registry = api.registry(name="my-registry", organization="my-org")
-            registry.description = "This is an updated description"
-            registry.save()
-            ```
+        ```python
+        import wandb
+
+        api = wandb.Api()
+        registry = api.registry(name="my-registry", organization="my-org")
+        registry.description = "This is an updated description"
+        registry.save()
+        ```
         """
         if not InternalApi()._server_supports(ServerFeature.ARTIFACT_REGISTRY_SEARCH):
             raise RuntimeError(
@@ -1624,18 +1867,18 @@ class Api:
             A registry object.
 
         Examples:
-            ```python
-            import wandb
-
-            api = wandb.Api()
-            registry = api.create_registry(
-                name="my-registry",
-                visibility="restricted",
-                organization="my-org",
-                description="This is a test registry",
-                artifact_types=["model"],
-            )
-            ```
+        ```python
+        import wandb
+
+        api = wandb.Api()
+        registry = api.create_registry(
+            name="my-registry",
+            visibility="restricted",
+            organization="my-org",
+            description="This is a test registry",
+            artifact_types=["model"],
+        )
+        ```
         """
         if not InternalApi()._server_supports(
             ServerFeature.INCLUDE_ARTIFACT_TYPES_IN_REGISTRY_CREATION
@@ -1707,23 +1950,25 @@ class Api:
             Iterator[WebhookIntegration]: An iterator of webhook integrations.
 
         Examples:
-            Get all registered webhook integrations for the team "my-team":
-            ```python
-            import wandb
+        Get all registered webhook integrations for the team "my-team":
 
-            api = wandb.Api()
-            webhook_integrations = api.webhook_integrations(entity="my-team")
-            ```
+        ```python
+        import wandb
 
-            Find only webhook integrations that post requests to "https://my-fake-url.com":
-            ```python
-            webhook_integrations = api.webhook_integrations(entity="my-team")
-            my_webhooks = [
-                ig
-                for ig in webhook_integrations
-                if ig.url_endpoint.startswith("https://my-fake-url.com")
-            ]
-            ```
+        api = wandb.Api()
+        webhook_integrations = api.webhook_integrations(entity="my-team")
+        ```
+
+        Find only webhook integrations that post requests to "https://my-fake-url.com":
+
+        ```python
+        webhook_integrations = api.webhook_integrations(entity="my-team")
+        my_webhooks = [
+            ig
+            for ig in webhook_integrations
+            if ig.url_endpoint.startswith("https://my-fake-url.com")
+        ]
+        ```
         """
         from wandb.apis.public.integrations import WebhookIntegrations
 
@@ -1748,23 +1993,25 @@ class Api:
             Iterator[SlackIntegration]: An iterator of Slack integrations.
 
         Examples:
-            Get all registered Slack integrations for the team "my-team":
-            ```python
-            import wandb
+        Get all registered Slack integrations for the team "my-team":
 
-            api = wandb.Api()
-            slack_integrations = api.slack_integrations(entity="my-team")
-            ```
+        ```python
+        import wandb
 
-            Find only Slack integrations that post to channel names starting with "team-alerts-":
-            ```python
-            slack_integrations = api.slack_integrations(entity="my-team")
-            team_alert_integrations = [
-                ig
-                for ig in slack_integrations
-                if ig.channel_name.startswith("team-alerts-")
-            ]
-            ```
+        api = wandb.Api()
+        slack_integrations = api.slack_integrations(entity="my-team")
+        ```
+
+        Find only Slack integrations that post to channel names starting with "team-alerts-":
+
+        ```python
+        slack_integrations = api.slack_integrations(entity="my-team")
+        team_alert_integrations = [
+            ig
+            for ig in slack_integrations
+            if ig.channel_name.startswith("team-alerts-")
+        ]
+        ```
         """
         from wandb.apis.public.integrations import SlackIntegrations
 
@@ -1862,20 +2109,20 @@ class Api:
             ValueError: If zero or multiple Automations match the search criteria.
 
         Examples:
-            Get an existing automation named "my-automation":
+        Get an existing automation named "my-automation":
 
-            ```python
-            import wandb
+        ```python
+        import wandb
 
-            api = wandb.Api()
-            automation = api.automation(name="my-automation")
-            ```
+        api = wandb.Api()
+        automation = api.automation(name="my-automation")
+        ```
 
-            Get an existing automation named "other-automation", from the entity "my-team":
+        Get an existing automation named "other-automation", from the entity "my-team":
 
-            ```python
-            automation = api.automation(name="other-automation", entity="my-team")
-            ```
+        ```python
+        automation = api.automation(name="other-automation", entity="my-team")
+        ```
         """
         return one(
             self.automations(entity=entity, name=name),
@@ -1905,14 +2152,14 @@ class Api:
             A list of automations.
 
         Examples:
-            Fetch all existing automations for the entity "my-team":
+        Fetch all existing automations for the entity "my-team":
 
-            ```python
-            import wandb
+        ```python
+        import wandb
 
-            api = wandb.Api()
-            automations = api.automations(entity="my-team")
-            ```
+        api = wandb.Api()
+        automations = api.automations(entity="my-team")
+        ```
         """
         from wandb.apis.public.automations import Automations
         from wandb.automations._generated import (
@@ -1970,32 +2217,32 @@ class Api:
             The saved Automation.
 
         Examples:
-            Create a new automation named "my-automation" that sends a Slack notification
-            when a run within a specific project logs a metric exceeding a custom threshold:
+        Create a new automation named "my-automation" that sends a Slack notification
+        when a run within a specific project logs a metric exceeding a custom threshold:
 
-            ```python
-            import wandb
-            from wandb.automations import OnRunMetric, RunEvent, SendNotification
+        ```python
+        import wandb
+        from wandb.automations import OnRunMetric, RunEvent, SendNotification
 
-            api = wandb.Api()
+        api = wandb.Api()
 
-            project = api.project("my-project", entity="my-team")
+        project = api.project("my-project", entity="my-team")
 
-            # Use the first Slack integration for the team
-            slack_hook = next(api.slack_integrations(entity="my-team"))
+        # Use the first Slack integration for the team
+        slack_hook = next(api.slack_integrations(entity="my-team"))
 
-            event = OnRunMetric(
-                scope=project,
-                filter=RunEvent.metric("custom-metric") > 10,
-            )
-            action = SendNotification.from_integration(slack_hook)
+        event = OnRunMetric(
+            scope=project,
+            filter=RunEvent.metric("custom-metric") > 10,
+        )
+        action = SendNotification.from_integration(slack_hook)
 
-            automation = api.create_automation(
-                event >> action,
-                name="my-automation",
-                description="Send a Slack message whenever 'custom-metric' exceeds 10.",
-            )
-            ```
+        automation = api.create_automation(
+            event >> action,
+            name="my-automation",
+            description="Send a Slack message whenever 'custom-metric' exceeds 10.",
+        )
+        ```
         """
         from wandb.automations import Automation
         from wandb.automations._generated import CREATE_AUTOMATION_GQL, CreateAutomation
@@ -2075,35 +2322,35 @@ class Api:
             The updated automation.
 
         Examples:
-            Disable and edit the description of an existing automation ("my-automation"):
+        Disable and edit the description of an existing automation ("my-automation"):
 
-            ```python
-            import wandb
+        ```python
+        import wandb
 
-            api = wandb.Api()
+        api = wandb.Api()
 
-            automation = api.automation(name="my-automation")
-            automation.enabled = False
-            automation.description = "Kept for reference, but no longer used."
+        automation = api.automation(name="my-automation")
+        automation.enabled = False
+        automation.description = "Kept for reference, but no longer used."
 
-            updated_automation = api.update_automation(automation)
-            ```
+        updated_automation = api.update_automation(automation)
+        ```
 
-            OR:
+        OR
 
-            ```python
-            import wandb
+        ```python
+        import wandb
 
-            api = wandb.Api()
+        api = wandb.Api()
 
-            automation = api.automation(name="my-automation")
+        automation = api.automation(name="my-automation")
 
-            updated_automation = api.update_automation(
-                automation,
-                enabled=False,
-                description="Kept for reference, but no longer used.",
-            )
-            ```
+        updated_automation = api.update_automation(
+            automation,
+            enabled=False,
+            description="Kept for reference, but no longer used.",
+        )
+        ```
         """
         from wandb.automations import ActionType, Automation
         from wandb.automations._generated import UPDATE_AUTOMATION_GQL, UpdateAutomation