wandb 0.19.9__py3-none-win_amd64.whl → 0.19.10__py3-none-win_amd64.whl

wandb/apis/public/automations.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from itertools import chain
+from typing import TYPE_CHECKING, Any, Iterable, Mapping
+
+from pydantic import ValidationError
+from typing_extensions import override
+from wandb_graphql.language.ast import Document
+
+from wandb.apis.paginator import Paginator, _Client
+
+if TYPE_CHECKING:
+    from wandb.automations import Automation
+    from wandb.automations._generated import ProjectConnectionFields
+
+
+class Automations(Paginator["Automation"]):
+    last_response: ProjectConnectionFields | None
+    _query: Document
+
+    def __init__(
+        self,
+        client: _Client,
+        variables: Mapping[str, Any],
+        per_page: int = 50,
+        _query: Document | None = None,
+    ):
+        super().__init__(client, variables, per_page=per_page)
+        if _query is None:
+            raise RuntimeError(f"Query required for {type(self).__qualname__}")
+        self._query = _query
+
+    @property
+    def more(self) -> bool:
+        """Whether there are more items to fetch."""
+        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."""
+        if self.last_response is None:
+            return None
+        return self.last_response.page_info.end_cursor
+
+    @override
+    def _update_response(self) -> None:
+        """Fetch the raw response data for the current page."""
+        from wandb.automations._generated import ProjectConnectionFields
+
+        data: dict[str, Any] = self.client.execute(
+            self._query, variable_values=self.variables
+        )
+        try:
+            page_data = data["searchScope"]["projects"]
+            self.last_response = ProjectConnectionFields.model_validate(page_data)
+        except (LookupError, AttributeError, ValidationError) as e:
+            raise ValueError("Unexpected response data") from e
+
+    def convert_objects(self) -> Iterable[Automation]:
+        """Parse the page data into a list of objects."""
+        from wandb.automations import Automation
+
+        page = self.last_response
+        return [
+            Automation.model_validate_json(obj.model_dump_json())
+            for obj in chain.from_iterable(edge.node.triggers for edge in page.edges)
+        ]

wandb/apis/public/integrations.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Iterable
+
+from pydantic import ValidationError
+from typing_extensions import override
+from wandb_gql import gql
+from wandb_graphql.language.ast import Document
+
+from wandb.apis.paginator import Paginator
+
+if TYPE_CHECKING:
+    from wandb.apis.paginator import _Client
+    from wandb.automations import Integration, SlackIntegration, WebhookIntegration
+    from wandb.automations._generated import (
+        GenericWebhookIntegrationConnectionFields,
+        IntegrationConnectionFields,
+        SlackIntegrationConnectionFields,
+    )
+
+
+class Integrations(Paginator["Integration"]):
+    last_response: IntegrationConnectionFields | None
+    _query: Document
+
+    def __init__(self, client: _Client, variables: dict[str, Any], per_page: int = 50):
+        from wandb.automations._generated import INTEGRATIONS_BY_ENTITY_GQL
+
+        super().__init__(client, variables, per_page=per_page)
+        # All integrations for entity
+        self._query = gql(INTEGRATIONS_BY_ENTITY_GQL)
+
+    @property
+    def more(self) -> bool:
+        """Whether there are more Integrations to fetch."""
+        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."""
+        if self.last_response is None:
+            return None
+        return self.last_response.page_info.end_cursor
+
+    @override
+    def _update_response(self) -> None:
+        """Fetch and parse the response data for the current page."""
+        from wandb.automations._generated import IntegrationConnectionFields
+
+        data: dict[str, Any] = self.client.execute(
+            self._query, variable_values=self.variables
+        )
+        try:
+            page_data = data["entity"]["integrations"]
+            self.last_response = IntegrationConnectionFields.model_validate(page_data)
+        except (LookupError, AttributeError, ValidationError) as e:
+            raise ValueError("Unexpected response data") from e
+
+    def convert_objects(self) -> Iterable[Integration]:
+        """Parse the page data into a list of Integrations."""
+        from wandb.automations.integrations import _IntegrationEdge
+
+        page = self.last_response
+        return [_IntegrationEdge.model_validate(edge).node for edge in page.edges]
+
+
+class WebhookIntegrations(Paginator["WebhookIntegration"]):
+    last_response: GenericWebhookIntegrationConnectionFields | None
+    _query: Document
+
+    def __init__(self, client: _Client, variables: dict[str, Any], per_page: int = 50):
+        from wandb.automations._generated import (
+            GENERIC_WEBHOOK_INTEGRATIONS_BY_ENTITY_GQL,
+        )
+
+        super().__init__(client, variables, per_page=per_page)
+        # Webhook integrations for entity
+        self._query = gql(GENERIC_WEBHOOK_INTEGRATIONS_BY_ENTITY_GQL)
+
+    @property
+    def more(self) -> bool:
+        """Whether there are more Integrations to fetch."""
+        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."""
+        if self.last_response is None:
+            return None
+        return self.last_response.page_info.end_cursor
+
+    @override
+    def _update_response(self) -> None:
+        """Fetch and parse the response data for the current page."""
+        from wandb.automations._generated import (
+            GenericWebhookIntegrationConnectionFields,
+        )
+
+        data: dict[str, Any] = self.client.execute(
+            self._query, variable_values=self.variables
+        )
+        try:
+            page_data = data["entity"]["integrations"]
+            self.last_response = (
+                GenericWebhookIntegrationConnectionFields.model_validate(page_data)
+            )
+        except (LookupError, AttributeError, ValidationError) as e:
+            raise ValueError("Unexpected response data") from e
+
+    def convert_objects(self) -> Iterable[WebhookIntegration]:
+        """Parse the page data into a list of Integrations."""
+        from wandb.automations import WebhookIntegration
+
+        page = self.last_response
+        return [WebhookIntegration.model_validate(edge.node) for edge in page.edges]
+
+
+class SlackIntegrations(Paginator["SlackIntegration"]):
+    last_response: SlackIntegrationConnectionFields | None
+    _query: Document
+
+    def __init__(self, client: _Client, variables: dict[str, Any], per_page: int = 50):
+        from wandb.automations._generated import SLACK_INTEGRATIONS_BY_ENTITY_GQL
+
+        super().__init__(client, variables, per_page=per_page)
+        # Slack integrations for entity
+        self._query = gql(SLACK_INTEGRATIONS_BY_ENTITY_GQL)
+
+    @property
+    def more(self) -> bool:
+        """Whether there are more Integrations to fetch."""
+        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."""
+        if self.last_response is None:
+            return None
+        return self.last_response.page_info.end_cursor
+
+    @override
+    def _update_response(self) -> None:
+        """Fetch and parse the response data for the current page."""
+        from wandb.automations._generated import SlackIntegrationConnectionFields
+
+        data: dict[str, Any] = self.client.execute(
+            self._query, variable_values=self.variables
+        )
+        try:
+            page_data = data["entity"]["integrations"]
+            self.last_response = SlackIntegrationConnectionFields.model_validate(
+                page_data
+            )
+        except (LookupError, AttributeError, ValidationError) as e:
+            raise ValueError("Unexpected response data") from e
+
+    def convert_objects(self) -> list[SlackIntegration]:
+        """Parse the page data into a list of Integrations."""
+        from wandb.automations import SlackIntegration
+
+        page = self.last_response
+        return [SlackIntegration.model_validate(edge.node) for edge in page.edges]

wandb/apis/public/projects.py

@@ -1,5 +1,8 @@
 """Public API: projects."""
 
+from contextlib import suppress
+
+from requests import HTTPError
 from wandb_gql import gql
 
 from wandb.apis import public
@@ -153,3 +156,29 @@ class Project(Attrs):
             )
             for e in ret["project"]["sweeps"]["edges"]
         ]
+
+    _PROJECT_ID = gql(
+        """
+        query ProjectID($projectName: String!, $entityName: String!) {
+            project(name: $projectName, entityName: $entityName) {
+                id
+            }
+        }
+        """
+    )
+
+    @property
+    def id(self) -> str:
+        # This is a workaround to ensure that the project ID can be retrieved
+        # on demand, as it generally is not set or fetched on instantiation.
+        # This is necessary if using this project as the scope of a new Automation.
+        with suppress(LookupError):
+            return self._attrs["id"]
+
+        variable_values = {"projectName": self.name, "entityName": self.entity}
+        try:
+            data = self.client.execute(self._PROJECT_ID, variable_values)
+            self._attrs["id"] = data["project"]["id"]
+            return self._attrs["id"]
+        except (HTTPError, LookupError, TypeError) as e:
+            raise ValueError(f"Unable to fetch project ID: {variable_values!r}") from e

wandb/apis/public/utils.py

@@ -1,8 +1,11 @@
 import re
 from enum import Enum
-from typing import Optional
+from typing import Any, Dict, Iterable, Mapping, Optional, Set
 from urllib.parse import urlparse
 
+from wandb_gql import gql
+from wandb_graphql.language import ast, visitor
+
 from wandb._iterutils import one
 from wandb.sdk.artifacts._validators import is_artifact_registry_project
 from wandb.sdk.internal.internal_api import Api as InternalApi
@@ -102,3 +105,106 @@ def fetch_org_from_settings_or_entity(
         )
         organization = entity_org.display_name
     return organization
+
+
+class _GQLCompatRewriter(visitor.Visitor):
+    """GraphQL AST visitor to rewrite queries/mutations to be compatible with older server versions."""
+
+    omit_variables: Set[str]
+    omit_fragments: Set[str]
+    omit_fields: Set[str]
+    rename_fields: Dict[str, str]
+
+    def __init__(
+        self,
+        omit_variables: Optional[Iterable[str]] = None,
+        omit_fragments: Optional[Iterable[str]] = None,
+        omit_fields: Optional[Iterable[str]] = None,
+        rename_fields: Optional[Mapping[str, str]] = None,
+    ):
+        self.omit_variables = set(omit_variables or ())
+        self.omit_fragments = set(omit_fragments or ())
+        self.omit_fields = set(omit_fields or ())
+        self.rename_fields = dict(rename_fields or {})
+
+    def enter_VariableDefinition(self, node: ast.VariableDefinition, *_, **__) -> Any:  # noqa: N802
+        if node.variable.name.value in self.omit_variables:
+            return visitor.REMOVE
+        # return node
+
+    def enter_ObjectField(self, node: ast.ObjectField, *_, **__) -> Any:  # noqa: N802
+        # For context, note that e.g.:
+        #
+        #   {description: $description
+        #   ...}
+        #
+        # Is parsed as:
+        #
+        #   ObjectValue(fields=[
+        #     ObjectField(name=Name(value='description'), value=Variable(name=Name(value='description'))),
+        #   ...])
+        if (
+            isinstance(var := node.value, ast.Variable)
+            and var.name.value in self.omit_variables
+        ):
+            return visitor.REMOVE
+
+    def enter_Argument(self, node: ast.Argument, *_, **__) -> Any:  # noqa: N802
+        if node.name.value in self.omit_variables:
+            return visitor.REMOVE
+
+    def enter_FragmentDefinition(self, node: ast.FragmentDefinition, *_, **__) -> Any:  # noqa: N802
+        if node.name.value in self.omit_fragments:
+            return visitor.REMOVE
+
+    def enter_FragmentSpread(self, node: ast.FragmentSpread, *_, **__) -> Any:  # noqa: N802
+        if node.name.value in self.omit_fragments:
+            return visitor.REMOVE
+
+    def enter_Field(self, node: ast.Field, *_, **__) -> Any:  # noqa: N802
+        if node.name.value in self.omit_fields:
+            return visitor.REMOVE
+        if new_name := self.rename_fields.get(node.name.value):
+            node.name.value = new_name
+            return node
+
+    def leave_Field(self, node: ast.Field, *_, **__) -> Any:  # noqa: N802
+        # If the field had a selection set, but now it's empty, remove the field entirely
+        if (node.selection_set is not None) and (not node.selection_set.selections):
+            return visitor.REMOVE
+
+
+def gql_compat(
+    request_string: str,
+    omit_variables: Optional[Iterable[str]] = None,
+    omit_fragments: Optional[Iterable[str]] = None,
+    omit_fields: Optional[Iterable[str]] = None,
+    rename_fields: Optional[Mapping[str, str]] = None,
+) -> ast.Document:
+    """Rewrite a GraphQL request string to ensure compatibility with older server versions.
+
+    Args:
+        request_string (str): The GraphQL request string to rewrite.
+        omit_variables (Iterable[str] | None): Names of variables to remove from the request string.
+        omit_fragments (Iterable[str] | None): Names of fragments to remove from the request string.
+        omit_fields (Iterable[str] | None): Names of fields to remove from the request string.
+        rename_fields (Mapping[str, str] | None):
+            A mapping of fields to rename in the request string, given as `{old_name -> new_name}`.
+
+    Returns:
+        str: Modified GraphQL request string with fragments on omitted types removed.
+    """
+    # Parse the request into a GraphQL AST
+    doc = gql(request_string)
+
+    if not (omit_variables or omit_fragments or omit_fields or rename_fields):
+        return doc
+
+    # Visit the AST with our visitor to filter out unwanted fragments
+    rewriter = _GQLCompatRewriter(
+        omit_variables=omit_variables,
+        omit_fragments=omit_fragments,
+        omit_fields=omit_fields,
+        rename_fields=rename_fields,
+    )
+    return visitor.visit(doc, rewriter)

wandb/automations/__init__.py

@@ -0,0 +1,81 @@
+from wandb._pydantic import IS_PYDANTIC_V2
+
+from . import _filters as filters
+from . import actions, automations, events, scopes
+from .actions import ActionType, DoNothing, DoNotification, DoWebhook
+from .automations import Automation, NewAutomation, PreparedAutomation
+from .events import (
+    ArtifactEvent,
+    EventType,
+    OnAddArtifactAlias,
+    OnCreateArtifact,
+    OnLinkArtifact,
+    OnRunMetric,
+    RunEvent,
+)
+from .integrations import Integration, SlackIntegration, WebhookIntegration
+from .scopes import ArtifactCollectionScope, ProjectScope, ScopeType
+
+# ----------------------------------------------------------------------------
+# WARNINGS on import
+if not IS_PYDANTIC_V2:
+    # Raises an error in Pydantic v1 environments, where the Automations API
+    # has not been tested and is unlikely to work as expected.
+    #
+    # Remove this when we either:
+    # - Drop support for Pydantic v1
+    # - Are able to implement (limited) Pydantic v1 support
+    raise ImportError(
+        "The W&B Automations API is not supported in Pydantic v1 at this time. "
+        "If at all possible, we currently recommend upgrading to Pydantic v2 to use this feature.",
+    )
+
+else:
+    # If Pydantic v2 is available, we can use the full Automations API
+    # but communicate to users that the API is still experimental and
+    # may change rapidly.
+    import warnings
+
+    warnings.warn(
+        "The W&B Automations API is currently experimental. Although we'll communicate "
+        "breaking changes in release notes and attempt to minimize them in general, "
+        "please know that such changes may occur between release versions without notice. "
+        "We strongly recommend pinning your `wandb` version when using the Automations API "
+        "to avoid unexpected breakages.",
+        FutureWarning,
+        stacklevel=1,
+    )
+# ----------------------------------------------------------------------------
+
+__all__ = [
+    "filters",
+    "scopes",
+    "events",
+    "actions",
+    "automations",
+    # Scopes
+    "ScopeType",
+    "ArtifactCollectionScope",
+    "ProjectScope",
+    # Events
+    "EventType",
+    "OnAddArtifactAlias",
+    "OnCreateArtifact",
+    "OnLinkArtifact",
+    "OnRunMetric",
+    "ArtifactEvent",
+    "RunEvent",
+    # Actions
+    "ActionType",
+    "DoNotification",
+    "DoWebhook",
+    "DoNothing",
+    # Automations
+    "Automation",
+    "NewAutomation",
+    "PreparedAutomation",
+    # Integrations
+    "Integration",
+    "SlackIntegration",
+    "WebhookIntegration",
+]

wandb/automations/_filters/__init__.py

@@ -0,0 +1,40 @@
+from .expressions import FilterExpr, MongoLikeFilter
+from .operators import (
+    And,
+    Contains,
+    Eq,
+    Exists,
+    Gt,
+    Gte,
+    In,
+    Lt,
+    Lte,
+    Ne,
+    Nor,
+    Not,
+    NotIn,
+    Op,
+    Or,
+    Regex,
+)
+
+__all__ = [
+    "And",
+    "Or",
+    "Nor",
+    "Not",
+    "Op",
+    "Gt",
+    "Lt",
+    "Gte",
+    "Lte",
+    "Eq",
+    "Ne",
+    "In",
+    "NotIn",
+    "Contains",
+    "Exists",
+    "Regex",
+    "FilterExpr",
+    "MongoLikeFilter",
+]

wandb/automations/_filters/expressions.py

@@ -0,0 +1,179 @@
+"""Pydantic-compatible representations of MongoDB expressions."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, Union
+
+from pydantic import ConfigDict, model_serializer
+from typing_extensions import Self, TypeAlias
+
+from wandb._pydantic import CompatBaseModel, model_validator
+
+from .operators import (
+    Contains,
+    Eq,
+    Exists,
+    Gt,
+    Gte,
+    In,
+    Lt,
+    Lte,
+    Ne,
+    NotIn,
+    Op,
+    Regex,
+    RichReprResult,
+    Scalar,
+    ScalarTypes,
+    SupportsLogicalOpSyntax,
+)
+
+
+class FilterableField:
+    """A descriptor that can be used to define a "filterable" field on a class.
+
+    Internal helper to support syntactic sugar for defining event filters.
+    """
+
+    _python_name: str  #: The name of the field this descriptor was assigned to in the Python class.
+    _server_name: str | None  #: If set, the actual server-side field name to filter on.
+
+    def __init__(self, server_name: str | None = None):
+        self._server_name = server_name
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self._python_name = name
+
+    def __get__(self, obj: Any, objtype: type) -> Self:
+        # By default, if we didn't explicitly provide a backend name for
+        # filtering, assume the field has the same name in the backend as
+        # the python attribute.
+        return self
+
+    @property
+    def _name(self) -> str:
+        return self._server_name or self._python_name
+
+    def __str__(self) -> str:
+        return self._name
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self._name!r})"
+
+    # Methods to define filter expressions through chaining
+    def matches_regex(self, pattern: str) -> FilterExpr:
+        return FilterExpr(field=self._name, op=Regex(regex_=pattern))
+
+    def contains(self, text: str) -> FilterExpr:
+        return FilterExpr(field=self._name, op=Contains(contains_=text))
+
+    def exists(self, exists: bool = True) -> FilterExpr:
+        return FilterExpr(field=self._name, op=Exists(exists_=exists))
+
+    def lt(self, value: Scalar) -> FilterExpr:
+        return FilterExpr(field=self._name, op=Lt(lt_=value))
+
+    def gt(self, value: Scalar) -> FilterExpr:
+        return FilterExpr(field=self._name, op=Gt(gt_=value))
+
+    def lte(self, value: Scalar) -> FilterExpr:
+        return FilterExpr(field=self._name, op=Lte(lte_=value))
+
+    def gte(self, value: Scalar) -> FilterExpr:
+        return FilterExpr(field=self._name, op=Gte(gte_=value))
+
+    def ne(self, value: Scalar) -> FilterExpr:
+        return FilterExpr(field=self._name, op=Ne(ne_=value))
+
+    def eq(self, value: Scalar) -> FilterExpr:
+        return FilterExpr(field=self._name, op=Eq(eq_=value))
+
+    def in_(self, values: Iterable[Scalar]) -> FilterExpr:
+        return FilterExpr(field=self._name, op=In(in_=values))
+
+    def not_in(self, values: Iterable[Scalar]) -> FilterExpr:
+        return FilterExpr(field=self._name, op=NotIn(nin_=values))
+
+    # Override the default behavior of comparison operators: <, >=, ==, etc
+    def __lt__(self, other: Any) -> FilterExpr:
+        if isinstance(other, ScalarTypes):
+            return self.lt(other)
+        raise TypeError(f"Invalid operand type in filter expression: {type(other)!r}")
+
+    def __gt__(self, other: Any) -> FilterExpr:
+        if isinstance(other, ScalarTypes):
+            return self.gt(other)
+        raise TypeError(f"Invalid operand type in filter expression: {type(other)!r}")
+
+    def __le__(self, other: Any) -> FilterExpr:
+        if isinstance(other, ScalarTypes):
+            return self.lte(other)
+        raise TypeError(f"Invalid operand type in filter expression: {type(other)!r}")
+
+    def __ge__(self, other: Any) -> FilterExpr:
+        if isinstance(other, ScalarTypes):
+            return self.gte(other)
+        raise TypeError(f"Invalid operand type in filter expression: {type(other)!r}")
+
+    # Operator behavior is intentionally overridden to allow defining
+    # filter expressions like `field == "value"`.  See similar overrides
+    # of built-in dunder methods in sqlalchemy, polars, pandas, numpy, etc.
+    #
+    # sqlalchemy example for illustrative purposes:
+    # https://github.com/sqlalchemy/sqlalchemy/blob/f21ae633486380a26dc0b67b70ae1c0efc6b4dc4/lib/sqlalchemy/orm/descriptor_props.py#L808-L812
+    def __eq__(self, other: Any) -> FilterExpr:
+        if isinstance(other, ScalarTypes):
+            return self.eq(other)
+        raise TypeError(f"Invalid operand type in filter expression: {type(other)!r}")
+
+    def __ne__(self, other: Any) -> FilterExpr:
+        if isinstance(other, ScalarTypes):
+            return self.ne(other)
+        raise TypeError(f"Invalid operand type in filter expression: {type(other)!r}")
+
+
+# ------------------------------------------------------------------------------
+class FilterExpr(CompatBaseModel, SupportsLogicalOpSyntax):
+    """A MongoDB filter expression on a specific field."""
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+    )
+
+    field: str
+    op: Op
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.field!s}={self.op!r})"
+
+    def __rich_repr__(self) -> RichReprResult:  # type: ignore[override]
+        # https://rich.readthedocs.io/en/stable/pretty.html
+        yield self.field, self.op
+
+    @model_validator(mode="before")
+    @classmethod
+    def _validate(cls, data: Any) -> Any:
+        """Parse a MongoDB dict representation of the filter expression."""
+        if (
+            isinstance(data, dict)
+            and len(data) == 1
+            and not any(key.startswith("$") for key in data)
+        ):
+            # This looks like a MongoDB filter dict.  E.g.:
+            # - in:  `{"display_name": {"$contains": "my-run"}}`
+            # - out: `FilterExpr(field="display_name", op=Contains(contains_="my-run"))`
+            ((field, op),) = data.items()
+            return {"field": field, "op": op}
+        return data
+
+    @model_serializer(mode="plain")
+    def _serialize(self) -> dict[str, Any]:
+        """Return a MongoDB dict representation of the expression."""
+        from pydantic_core import to_jsonable_python  # Only valid in pydantic v2
+
+        op_dict = to_jsonable_python(self.op, by_alias=True, round_trip=True)
+        return {self.field: op_dict}
+
+
+MongoLikeFilter: TypeAlias = Union[Op, FilterExpr]