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

wandb/apis/public/files.py

@@ -1,8 +1,41 @@
-"""Public API: files."""
+"""W&B Public API for File objects.
+
+This module provides classes for interacting with files stored in W&B.
+
+Example:
+```python
+from wandb.apis.public import Api
+
+# Get files from a specific run
+run = Api().run("entity/project/run_id")
+files = run.files()
+
+# Work with files
+for file in files:
+    print(f"File: {file.name}")
+    print(f"Size: {file.size} bytes")
+    print(f"Type: {file.mimetype}")
+
+    # Download file
+    if file.size < 1000000:  # Less than 1MB
+        file.download(root="./downloads")
+
+    # Get S3 URI for large files
+    if file.size >= 1000000:
+        print(f"S3 URI: {file.path_uri}")
+```
+
+Note:
+    This module is part of the W&B Public API and provides methods to access,
+    download, and manage files stored in W&B. Files are typically associated
+    with specific runs and can include model weights, datasets, visualizations,
+    and other artifacts.
+"""
+
+from __future__ import annotations
 
 import io
 import os
-from typing import Optional
 
 import requests
 from wandb_gql import gql
@@ -14,12 +47,13 @@ from wandb.apis.attrs import Attrs
 from wandb.apis.normalize import normalize_exceptions
 from wandb.apis.paginator import SizedPaginator
 from wandb.apis.public import utils
-from wandb.apis.public.api import Api
+from wandb.apis.public.api import Api, RetryingClient
 from wandb.apis.public.const import RETRY_TIMEDELTA
+from wandb.apis.public.runs import Run
 from wandb.sdk.lib import retry
 
 FILE_FRAGMENT = """fragment RunFilesFragment on Run {
-    files(names: $fileNames, after: $fileCursor, first: $fileLimit) {
+    files(names: $fileNames, after: $fileCursor, first: $fileLimit, pattern: $pattern) {
         edges {
             node {
                 id
@@ -42,12 +76,37 @@ FILE_FRAGMENT = """fragment RunFilesFragment on Run {
 
 
 class Files(SizedPaginator["File"]):
-    """An iterable collection of `File` objects."""
+    """A lazy iterator over a collection of `File` objects.
+
+    Access and manage files uploaded to W&B during a run. Handles pagination
+    automatically when iterating through large collections of files.
+
+    Example:
+    ```python
+    from wandb.apis.public.files import Files
+    from wandb.apis.public.api import Api
+
+    # Example run object
+    run = Api().run("entity/project/run-id")
+
+    # Create a Files object to iterate over files in the run
+    files = Files(api.client, run)
+
+    # Iterate over files
+    for file in files:
+        print(file.name)
+        print(file.url)
+        print(file.size)
+
+        # Download the file
+        file.download(root="download_directory", replace=True)
+    ```
+    """
 
     QUERY = gql(
         """
         query RunFiles($project: String!, $entity: String!, $name: String!, $fileCursor: String,
-            $fileLimit: Int = 50, $fileNames: [String] = [], $upload: Boolean = false) {{
+            $fileLimit: Int = 50, $fileNames: [String] = [], $upload: Boolean = false, $pattern: String) {{
             project(name: $project, entityName: $entity) {{
                 internalId
                 run(name: $name) {{
@@ -60,7 +119,36 @@ class Files(SizedPaginator["File"]):
         """.format(FILE_FRAGMENT)
     )
 
-    def __init__(self, client, run, names=None, per_page=50, upload=False):
+    def __init__(
+        self,
+        client: RetryingClient,
+        run: Run,
+        names: list[str] | None = None,
+        per_page: int = 50,
+        upload: bool = False,
+        pattern: str | None = None,
+    ):
+        """Initialize a lazy iterator over a collection of `File` objects.
+
+        Files are retrieved in pages from the W&B server as needed.
+
+        Args:
+        client: The run object that contains the files
+        run: The run object that contains the files
+        names (list, optional): A list of file names to filter the files
+        per_page (int, optional): The number of files to fetch per page
+        upload (bool, optional): If `True`, fetch the upload URL for each file
+        pattern (str, optional): Pattern to match when returning files from W&B
+            This pattern uses mySQL's LIKE syntax,
+            so matching all files that end with .json would be "%.json".
+            If both names and pattern are provided, a ValueError will be raised.
+        """
+        if names and pattern:
+            raise ValueError(
+                "Querying for files by both names and pattern is not supported."
+                " Please provide either a list of names or a pattern to match.",
+            )
+
         self.run = run
         variables = {
             "project": run.project,
@@ -68,11 +156,17 @@ class Files(SizedPaginator["File"]):
             "name": run.id,
             "fileNames": names or [],
             "upload": upload,
+            "pattern": pattern,
         }
         super().__init__(client, variables, per_page)
 
     @property
     def _length(self):
+        """
+        Returns total number of files.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if not self.last_response:
             self._load_page()
 
@@ -80,6 +174,10 @@ class Files(SizedPaginator["File"]):
 
     @property
     def more(self):
+        """Returns whether there are more files to fetch.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if self.last_response:
             return self.last_response["project"]["run"]["files"]["pageInfo"][
                 "hasNextPage"
@@ -89,15 +187,27 @@ class Files(SizedPaginator["File"]):
 
     @property
     def cursor(self):
+        """Returns the cursor position for pagination of file results.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if self.last_response:
             return self.last_response["project"]["run"]["files"]["edges"][-1]["cursor"]
         else:
             return None
 
     def update_variables(self):
+        """Updates the GraphQL query variables for pagination.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         self.variables.update({"fileLimit": self.per_page, "fileCursor": self.cursor})
 
     def convert_objects(self):
+        """Converts GraphQL edges to File objects.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         return [
             File(self.client, r["node"], self.run)
             for r in self.last_response["project"]["run"]["files"]["edges"]
@@ -108,28 +218,45 @@ class Files(SizedPaginator["File"]):
 
 
 class File(Attrs):
-    """File is a class associated with a file saved by wandb.
-
-    Attributes:
-        name (string): filename
-        url (string): path to file
-        direct_url (string): path to file in the bucket
-        md5 (string): md5 of file
-        mimetype (string): mimetype of file
-        updated_at (string): timestamp of last update
-        size (int): size of file in bytes
-        path_uri (str): path to file in the bucket, currently only available for files stored in S3
+    """File saved to W&B.
+
+    Represents a single file stored in W&B. Includes access to file metadata.
+    Files are associated with a specific run and
+    can include text files, model weights, datasets, visualizations, and other
+    artifacts. You can download the file, delete the file, and access file
+    properties.
+
+    Specify one or more attributes in a dictionary to fine a specific
+    file logged to a specific run. You can search using the following keys:
+
+    - id (str): The ID of the run that contains the file
+    - name (str): Name of the file
+    - url (str): path to file
+    - direct_url (str): path to file in the bucket
+    - sizeBytes (int): size of file in bytes
+    - md5 (str): md5 of file
+    - mimetype (str): mimetype of file
+    - updated_at (str): timestamp of last update
+    - path_uri (str): path to file in the bucket, currently only available for S3 objects and reference files
+
+    Args:
+        client: The run object that contains the file
+        attrs (dict): A dictionary of attributes that define the file
+        run: The run object that contains the file
+
+    <!-- lazydoc-ignore-class: internal -->
     """
 
     def __init__(self, client, attrs, run=None):
         self.client = client
         self._attrs = attrs
         self.run = run
-        self.server_supports_delete_file_with_project_id: Optional[bool] = None
+        self.server_supports_delete_file_with_project_id: bool | None = None
         super().__init__(dict(attrs))
 
     @property
     def size(self):
+        """Returns the size of the file in bytes."""
         size_bytes = self._attrs["sizeBytes"]
         if size_bytes is not None:
             return int(size_bytes)
@@ -137,17 +264,25 @@ class File(Attrs):
 
     @property
     def path_uri(self) -> str:
+        """Returns the URI path to the file in the storage bucket.
+
+        Returns:
+            str: The S3 URI (e.g., 's3://bucket/path/to/file') if the file is stored in S3,
+                 the direct URL if it's a reference file, or an empty string if unavailable.
         """
-        Returns the uri path to the file in the storage bucket.
-        """
-        path_uri = ""
+        if not (direct_url := self._attrs.get("directUrl")):
+            wandb.termwarn("Unable to find direct_url of file")
+            return ""
+
+        # For reference files, both the directUrl and the url are just the path to the file in the bucket
+        if direct_url == self._attrs.get("url"):
+            return direct_url
+
         try:
-            path_uri = utils.parse_s3_url_to_s3_uri(self._attrs["directUrl"])
+            return utils.parse_s3_url_to_s3_uri(direct_url)
         except ValueError:
             wandb.termwarn("path_uri is only available for files stored in S3")
-        except LookupError:
-            wandb.termwarn("Unable to find direct_url of file")
-        return path_uri
+            return ""
 
     @normalize_exceptions
     @retry.retriable(
@@ -160,20 +295,23 @@ class File(Attrs):
         root: str = ".",
         replace: bool = False,
         exist_ok: bool = False,
-        api: Optional[Api] = None,
+        api: Api | None = None,
     ) -> io.TextIOWrapper:
         """Downloads a file previously saved by a run from the wandb server.
 
         Args:
-            replace (boolean): If `True`, download will overwrite a local file
+            root: Local directory to save the file. Defaults to the
+                current working directory (".").
+            replace: If `True`, download will overwrite a local file
                 if it exists. Defaults to `False`.
-            root (str): Local directory to save the file.  Defaults to ".".
-            exist_ok (boolean): If `True`, will not raise ValueError if file already
-                exists and will not re-download unless replace=True. Defaults to `False`.
-            api (Api, optional): If given, the `Api` instance used to download the file.
+            exist_ok: If `True`, will not raise ValueError if file already
+                exists and will not re-download unless replace=True.
+                Defaults to `False`.
+            api: If specified, the `Api` instance used to download the file.
 
         Raises:
-            `ValueError` if file already exists, replace=False and exist_ok=False.
+            `ValueError` if file already exists, `replace=False` and
+            `exist_ok=False`.
         """
         if api is None:
             api = wandb.Api()
@@ -192,6 +330,7 @@ class File(Attrs):
 
     @normalize_exceptions
     def delete(self):
+        """Delete the file from the W&B server."""
         project_id_mutation_fragment = ""
         project_id_variable_fragment = ""
         variable_values = {

wandb/apis/public/history.py

@@ -1,17 +1,28 @@
-"""Public API: history."""
+"""W&B Public API for Run History.
+
+This module provides classes for efficiently scanning and sampling run
+history data.
+
+Note:
+    This module is part of the W&B Public API and provides methods
+    to access run history data. It handles pagination automatically and offers
+    both complete and sampled access to metrics logged during training runs.
+"""
 
 import json
 
-import requests
 from wandb_gql import gql
-from wandb_gql.client import RetryError
 
-from wandb import util
 from wandb.apis.normalize import normalize_exceptions
-from wandb.sdk.lib import retry
+from wandb.apis.public import api, runs
 
 
 class HistoryScan:
+    """Iterator for scanning complete run history.
+
+    <!-- lazydoc-ignore-class: internal -->
+    """
+
     QUERY = gql(
         """
         query HistoryPage($entity: String!, $project: String!, $run: String!, $minStep: Int64!, $maxStep: Int64!, $pageSize: Int!) {
@@ -24,7 +35,24 @@ class HistoryScan:
         """
     )
 
-    def __init__(self, client, run, min_step, max_step, page_size=1000):
+    def __init__(
+        self,
+        client: api.RetryingClient,
+        run: api.public.runs.Run,
+        min_step: int,
+        max_step: int,
+        page_size: int = 1000,
+    ):
+        """Initialize a HistoryScan instance.
+
+        Args:
+            client: The client instance to use for making API calls to the W&B backend.
+            run: The run object whose history is to be scanned.
+            min_step: The minimum step to start scanning from.
+            max_step: The maximum step to scan up to.
+            page_size: Number of history rows to fetch per page.
+                Default page_size is 1000.
+        """
         self.client = client
         self.run = run
         self.page_size = page_size
@@ -41,6 +69,10 @@ class HistoryScan:
         return self
 
     def __next__(self):
+        """Return the next row of history data with automatic pagination.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         while True:
             if self.scan_offset < len(self.rows):
                 row = self.rows[self.scan_offset]
@@ -53,10 +85,6 @@ class HistoryScan:
     next = __next__
 
     @normalize_exceptions
-    @retry.retriable(
-        check_retry_fn=util.no_retry_auth,
-        retryable_exceptions=(RetryError, requests.RequestException),
-    )
     def _load_next(self):
         max_step = self.page_offset + self.page_size
         if max_step > self.max_step:
@@ -78,6 +106,11 @@ class HistoryScan:
 
 
 class SampledHistoryScan:
+    """Iterator for sampling run history data.
+
+    <!-- lazydoc-ignore-class: internal -->
+    """
+
     QUERY = gql(
         """
         query SampledHistoryPage($entity: String!, $project: String!, $run: String!, $spec: JSONString!) {
@@ -90,7 +123,26 @@ class SampledHistoryScan:
         """
     )
 
-    def __init__(self, client, run, keys, min_step, max_step, page_size=1000):
+    def __init__(
+        self,
+        client: api.RetryingClient,
+        run: runs.Run,
+        keys: list,
+        min_step: int,
+        max_step: int,
+        page_size: int = 1000,
+    ):
+        """Initialize a SampledHistoryScan instance.
+
+        Args:
+            client: The client instance to use for making API calls to the W&B backend.
+            run: The run object whose history is to be sampled.
+            keys: List of keys to sample from the history.
+            min_step: The minimum step to start sampling from.
+            max_step: The maximum step to sample up to.
+            page_size: Number of sampled history rows to fetch per page.
+                Default page_size is 1000.
+        """
         self.client = client
         self.run = run
         self.keys = keys
@@ -108,6 +160,10 @@ class SampledHistoryScan:
         return self
 
     def __next__(self):
+        """Return the next row of sampled history data with automatic pagination.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         while True:
             if self.scan_offset < len(self.rows):
                 row = self.rows[self.scan_offset]
@@ -120,10 +176,6 @@ class SampledHistoryScan:
     next = __next__
 
     @normalize_exceptions
-    @retry.retriable(
-        check_retry_fn=util.no_retry_auth,
-        retryable_exceptions=(RetryError, requests.RequestException),
-    )
     def _load_next(self):
         max_step = self.page_offset + self.page_size
         if max_step > self.max_step:

wandb/apis/public/integrations.py

@@ -1,3 +1,8 @@
+"""W&B Public API for integrations.
+
+This module provides classes for interacting with W&B integrations.
+"""
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any, Iterable
@@ -20,6 +25,8 @@ if TYPE_CHECKING:
 
 
 class Integrations(Paginator["Integration"]):
+    """An lazy iterator of `Integration` objects."""
+
     last_response: IntegrationConnectionFields | None
     _query: Document
 
@@ -32,14 +39,20 @@ class Integrations(Paginator["Integration"]):
 
     @property
     def more(self) -> bool:
-        """Whether there are more Integrations to fetch."""
+        """Whether there are more Integrations to fetch.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if self.last_response is None:
             return True
         return self.last_response.page_info.has_next_page
 
     @property
     def cursor(self) -> str | None:
-        """The start cursor to use for the next page."""
+        """The start cursor to use for the next page.
+
+        <!-- lazydoc-ignore: internal -->
+        """
         if self.last_response is None:
             return None
         return self.last_response.page_info.end_cursor
@@ -67,6 +80,11 @@ class Integrations(Paginator["Integration"]):
 
 
 class WebhookIntegrations(Paginator["WebhookIntegration"]):
+    """An lazy iterator of `WebhookIntegration` objects.
+
+    <!-- lazydoc-ignore-class: internal -->
+    """
+
     last_response: GenericWebhookIntegrationConnectionFields | None
     _query: Document
 
@@ -126,6 +144,11 @@ class WebhookIntegrations(Paginator["WebhookIntegration"]):
 
 
 class SlackIntegrations(Paginator["SlackIntegration"]):
+    """An lazy iterator of `SlackIntegration` objects.
+
+    <!-- lazydoc-ignore-class: internal -->
+    """
+
     last_response: SlackIntegrationConnectionFields | None
     _query: Document