wandb 0.21.2__py3-none-macosx_12_0_arm64.whl

wandb/apis/public/projects.py

@@ -0,0 +1,276 @@
+"""W&B Public API for Project objects.
+
+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
+
+from wandb.apis import public
+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 {
+    id
+    name
+    entityName
+    createdAt
+    isBenchmark
+}"""
+
+
+class Projects(Paginator["Project"]):
+    """An lazy iterator of `Project` objects.
+
+    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 {{
+                    node {{
+                        ...ProjectFragment
+                    }}
+                    cursor
+                }}
+                pageInfo {{
+                    endCursor
+                    hasNextPage
+                }}
+            }}
+        }}
+        {PROJECT_FRAGMENT}
+    """)
+
+    def __init__(
+        self,
+        client: RetryingClient,
+        entity: str,
+        per_page: int = 50,
+    ) -> "Projects":
+        """An iterable collection of `Project` objects.
+
+        Args:
+            client: The API client used to query W&B.
+            entity: The entity which owns the projects.
+            per_page: The number of projects to fetch per request to the API.
+        """
+        self.client = client
+        self.entity = entity
+        variables = {
+            "entity": self.entity,
+        }
+        super().__init__(client, variables, per_page)
+
+    @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:
+            return True
+
+    @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"]
+        ]
+
+    def __repr__(self):
+        return f"<Projects {self.entity}>"
+
+
+class Project(Attrs):
+    """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,
+        client: RetryingClient,
+        entity: str,
+        project: str,
+        attrs: dict,
+    ) -> "Project":
+        """A single project associated with an entity.
+
+        Args:
+            client: The API client used to query W&B.
+            entity: The entity which owns the project.
+            project: The name of the project to query.
+            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.
+
+        <!-- lazydoc-ignore: internal -->
+        """
+        url = self.url + "?jupyter=true"
+        style = f"border:none;width:100%;height:{height}px;"
+        prefix = ""
+        if hidden:
+            style += "display:none;"
+            prefix = ipython.toggle_button("project")
+        return prefix + f"<iframe src={url!r} style={style!r}></iframe>"
+
+    def _repr_html_(self) -> str:
+        return self.to_html()
+
+    def __repr__(self):
+        return "<Project {}>".format("/".join(self.path))
+
+    @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, per_page=50):
+        """Return a paginated collection of sweeps in this project.
+
+        Args:
+            per_page: The number of sweeps to fetch per request to the API.
+
+        Returns:
+            A `Sweeps` object, which is an iterable collection of `Sweep` objects.
+        """
+        return Sweeps(self.client, self.entity, self.name, per_page=per_page)
+
+    @property
+    def id(self) -> str:
+        if not self._is_loaded:
+            self._load()
+
+        if "id" not in self._attrs:
+            raise ValueError(f"Project {self.name} not found")
+
+        return self._attrs["id"]
+
+    def __getattr__(self, name: str):
+        if not self._is_loaded:
+            self._load()
+
+        return super().__getattr__(name)

wandb/apis/public/query_generator.py

@@ -0,0 +1,176 @@
+class QueryGenerator:
+    """QueryGenerator is a helper object to write filters for runs.
+
+    <!-- lazydoc-ignore-class: internal -->
+    """
+
+    INDIVIDUAL_OP_TO_MONGO = {
+        "!=": "$ne",
+        ">": "$gt",
+        ">=": "$gte",
+        "<": "$lt",
+        "<=": "$lte",
+        "IN": "$in",
+        "NIN": "$nin",
+        "REGEX": "$regex",
+    }
+    MONGO_TO_INDIVIDUAL_OP = {v: k for k, v in INDIVIDUAL_OP_TO_MONGO.items()}
+
+    GROUP_OP_TO_MONGO = {"AND": "$and", "OR": "$or"}
+    MONGO_TO_GROUP_OP = {v: k for k, v in GROUP_OP_TO_MONGO.items()}
+
+    def __init__(self):
+        pass
+
+    @classmethod
+    def format_order_key(cls, key: str):
+        """Format a key for sorting."""
+        if key.startswith(("+", "-")):
+            direction = key[0]
+            key = key[1:]
+        else:
+            direction = "-"
+        parts = key.split(".")
+        if len(parts) == 1:
+            # Assume the user meant summary_metrics if not a run column
+            if parts[0] not in ["createdAt", "updatedAt", "name", "sweep"]:
+                return direction + "summary_metrics." + parts[0]
+        # Assume summary metrics if prefix isn't known
+        elif parts[0] not in ["config", "summary_metrics", "tags"]:
+            return direction + ".".join(["summary_metrics"] + parts)
+        else:
+            return direction + ".".join(parts)
+
+    def _is_group(self, op):
+        return op.get("filters") is not None
+
+    def _is_individual(self, op):
+        return op.get("key") is not None
+
+    def _to_mongo_op_value(self, op, value):
+        if op == "=":
+            return value
+        else:
+            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":
+            return "summary_metrics." + key["name"]
+        elif key["section"] == "keys_info":
+            return "keys_info.keys." + key["name"]
+        elif key["section"] == "run":
+            return key["name"]
+        elif key["section"] == "tags":
+            return "tags." + key["name"]
+        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."):
+            return {"section": "summary", "name": path.split("summary_metrics.", 1)[1]}
+        elif path.startswith("keys_info.keys."):
+            return {"section": "keys_info", "name": path.split("keys_info.keys.", 1)[1]}
+        elif path.startswith("tags."):
+            return {"section": "tags", "name": path.split("tags.", 1)[1]}
+        else:
+            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"])
+            if key.get("ascending"):
+                order = "+" + order
+            else:
+                order = "-" + order
+            orders.append(order)
+        # return ",".join(orders)
+        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:]
+            if k[0] == "+":
+                ascending = True
+            elif k[0] == "-":
+                ascending = False
+            else:
+                raise Exception("you must sort by ascending(+) or descending(-)")
+
+            key = {"key": {"section": "run", "name": name}, "ascending": ascending}
+            keys.append(key)
+
+        return {"keys": keys}
+
+    def _to_mongo_individual(self, filter):
+        if filter["key"]["name"] == "":
+            return None
+
+        if filter.get("value") is None and filter["op"] != "=" and filter["op"] != "!=":
+            return None
+
+        if filter.get("disabled") is not None and filter["disabled"]:
+            return None
+
+        if filter["key"]["section"] == "tags":
+            if filter["op"] == "IN":
+                return {"tags": {"$in": filter["value"]}}
+            if filter["value"] is False:
+                return {
+                    "$or": [{"tags": None}, {"tags": {"$ne": filter["key"]["name"]}}]
+                }
+            else:
+                return {"tags": filter["key"]["name"]}
+        path = self.key_to_server_path(filter["key"])
+        if path is None:
+            return path
+        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):
+            return {
+                self.GROUP_OP_TO_MONGO[filter["op"]]: [
+                    self.filter_to_mongo(f) for f in filter["filters"]
+                ]
+            }
+
+    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.
+
+        group_op = None
+        for key in filter.keys():
+            # if self.MONGO_TO_GROUP_OP[key]:
+            if key in self.MONGO_TO_GROUP_OP:
+                group_op = key
+                break
+        if group_op is not None:
+            return {
+                "op": self.MONGO_TO_GROUP_OP[group_op],
+                "filters": [self.mongo_to_filter(f) for f in filter[group_op]],
+            }
+        else:
+            for k, v in filter.items():
+                if isinstance(v, dict):
+                    # TODO: do we always have one key in this case?
+                    op = next(iter(v.keys()))
+                    return {
+                        "key": self.server_path_to_key(k),
+                        "op": self.MONGO_TO_INDIVIDUAL_OP[op],
+                        "value": v[op],
+                    }
+                else:
+                    return {"key": self.server_path_to_key(k), "op": "=", "value": v}

wandb/apis/public/registries/_freezable_list.py

@@ -0,0 +1,179 @@
+from itertools import chain
+from typing import (
+    Any,
+    Iterable,
+    Iterator,
+    List,
+    MutableSequence,
+    Sequence,
+    Tuple,
+    TypeVar,
+    Union,
+    final,
+    overload,
+)
+
+T = TypeVar("T")
+
+
+@final
+class FreezableList(MutableSequence[T]):
+    """A list-like container type that only allows adding new items.
+
+    It tracks "saved" (immutable) and "draft" (mutable) items.
+    Items can be added, inserted, and removed while in draft state, but once frozen,
+    they become immutable. Unlike a set, duplicate items are allowed in the draft
+    state but duplicates already present in the saved state cannot be added.
+    Any initial items passed to the constructor are saved.
+    """
+
+    def __init__(self, iterable: Union[Iterable[T], None] = None, /) -> None:
+        self._frozen: Tuple[T, ...] = tuple(iterable or ())
+        self._draft: List[T] = []
+
+    def append(self, value: T) -> None:
+        """Append an item to the draft list. No duplicates are allowed."""
+        if (value in self._frozen) or (value in self._draft):
+            return
+        self._draft.append(value)
+
+    def remove(self, value: T) -> None:
+        """Remove the first occurrence of value from the draft list."""
+        if value in self._frozen:
+            raise ValueError(f"Cannot remove item from frozen list: {value!r}")
+        self._draft.remove(value)
+
+    def freeze(self) -> None:
+        """Freeze any draft items by adding them to the saved tuple."""
+        # Filter out duplicates already in saved before extending
+        new_items = tuple(item for item in self._draft if item not in self._frozen)
+        self._frozen = self._frozen + new_items
+        self._draft.clear()
+
+    def __eq__(self, value: object) -> bool:
+        if not isinstance(value, Sequence):
+            return NotImplemented
+        return list(self) == list(value)
+
+    def __contains__(self, value: Any) -> bool:
+        return value in self._frozen or value in self._draft
+
+    def __len__(self) -> int:
+        return len(self._frozen) + len(self._draft)
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(chain(self._frozen, self._draft))
+
+    @overload
+    def __getitem__(self, index: int) -> T: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> Sequence[T]: ...
+
+    def __getitem__(self, index: Union[int, slice]) -> Union[T, Sequence[T]]:
+        return [*self._frozen, *self._draft][index]
+
+    @overload
+    def __setitem__(self, index: int, value: T) -> None: ...
+
+    @overload
+    def __setitem__(self, index: slice, value: Iterable[T]) -> None: ...
+
+    def __setitem__(
+        self, index: Union[int, slice], value: Union[T, Iterable[T]]
+    ) -> None:
+        if isinstance(index, slice):
+            # Setting slices might affect saved items, disallow for simplicity
+            raise TypeError(
+                f"{type(self).__name__!r} does not support slice assignment"
+            )
+        else:
+            if value in self._frozen or value in self._draft:
+                return
+
+            # The frozen items are sequentially first and protected from changes
+            len_frozen = len(self._frozen)
+            size = len(self)
+
+            if (index >= size) or (index < -size):
+                raise IndexError("Index out of range")
+
+            draft_index = (index % size) - len_frozen
+            if draft_index < 0:
+                raise ValueError(f"Cannot assign to saved item at index {index!r}")
+            self._draft[draft_index] = value
+
+    @overload
+    def __delitem__(self, index: int) -> None: ...
+
+    @overload
+    def __delitem__(self, index: slice) -> None: ...
+
+    def __delitem__(self, index: Union[int, slice]) -> None:
+        if isinstance(index, slice):
+            raise TypeError(f"{type(self).__name__!r} does not support slice deletion")
+        else:
+            # The frozen items are sequentially first and protected from changes
+            len_frozen = len(self._frozen)
+            size = len(self)
+
+            if (index >= size) or (index < -size):
+                raise IndexError("Index out of range")
+
+            draft_index = (index % size) - len_frozen
+            if draft_index < 0:
+                raise ValueError(f"Cannot delete saved item at index {index!r}")
+            del self._draft[draft_index]
+
+    def insert(self, index: int, value: T) -> None:
+        """Insert item before index.
+
+        Insertion is only allowed at indices corresponding to the draft portion
+        of the list (i.e., index >= len(frozen_items)). Negative indices are
+        interpreted relative to the combined length of frozen and draft items.
+        """
+        if value in self._frozen or value in self._draft:
+            # Silently ignore duplicates, similar to append
+            return
+
+        # The frozen items are sequentially first and protected from changes
+        len_frozen = len(self._frozen)
+        size = len(self)
+
+        # Follow the behavior of `list.insert()` when the index is out of bounds.
+        # - negative out-of-bounds index: prepend.  Will only work if the frozen items are empty.
+        if index < -size and not self._frozen:
+            return self._draft.insert(0, value)
+
+        # - positive out-of-bounds index: append.
+        if index >= size:
+            return self._draft.append(value)
+
+        # - in-bounds index: insert only if into the draft portion.
+        draft_index = (index % size) - len_frozen
+        if draft_index < 0:
+            raise IndexError(
+                f"Cannot insert into the frozen list (index < {len_frozen})"
+            )
+        return self._draft.insert(draft_index, value)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(frozen={list(self._frozen)!r}, draft={list(self._draft)!r})"
+
+    @property
+    def draft(self) -> Tuple[T, ...]:
+        """A read-only, tuple copy of the current draft items."""
+        return tuple(self._draft)
+
+
+class AddOnlyArtifactTypesList(FreezableList[str]):
+    def remove(self, value: str) -> None:
+        try:
+            super().remove(value)
+        except ValueError:
+            raise ValueError(
+                f"Cannot remove artifact type: {value!r} that has been saved to the registry"
+            )
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(saved={list(self._frozen)!r}, draft={list(self._draft)!r})"