wandb 0.21.2__py3-none-macosx_12_0_x86_64.whl

wandb/apis/public/users.py

@@ -0,0 +1,177 @@
+"""W&B Public API for managing users and API keys.
+
+This module provides classes for managing W&B users and their API keys.
+
+Note:
+    This module is part of the W&B Public API and provides methods to manage
+    users and their authentication. Some operations require admin privileges.
+"""
+
+import requests
+from wandb_gql import gql
+
+import wandb
+from wandb.apis.attrs import Attrs
+
+
+class User(Attrs):
+    """A class representing a W&B user with authentication and management capabilities.
+
+    This class provides methods to manage W&B users, including creating users,
+    managing API keys, and accessing team memberships. It inherits from Attrs
+    to handle user attributes.
+
+    Args:
+        client: (`wandb.apis.internal.Api`) The client instance to use
+        attrs: (dict) The user attributes
+
+    Note:
+        Some operations require admin privileges
+    """
+
+    CREATE_USER_MUTATION = gql(
+        """
+    mutation CreateUserFromAdmin($email: String!, $admin: Boolean) {
+        createUser(input: {email: $email, admin: $admin}) {
+            user {
+                id
+                name
+                username
+                email
+                admin
+            }
+        }
+    }
+        """
+    )
+
+    DELETE_API_KEY_MUTATION = gql(
+        """
+    mutation DeleteApiKey($id: String!) {
+        deleteApiKey(input: {id: $id}) {
+            success
+        }
+    }
+        """
+    )
+    GENERATE_API_KEY_MUTATION = gql(
+        """
+    mutation GenerateApiKey($description: String) {
+        generateApiKey(input: {description: $description}) {
+            apiKey {
+                id
+                name
+            }
+        }
+    }
+        """
+    )
+
+    def __init__(self, client, attrs):
+        super().__init__(attrs)
+        self._client = client
+        self._user_api = None
+
+    @property
+    def user_api(self):
+        """An instance of the api using credentials from the user."""
+        if self._user_api is None and len(self.api_keys) > 0:
+            self._user_api = wandb.Api(api_key=self.api_keys[0])
+        return self._user_api
+
+    @classmethod
+    def create(cls, api, email, admin=False):
+        """Create a new user.
+
+        Args:
+            api (`Api`): The api instance to use
+            email (str): The name of the team
+            admin (bool): Whether this user should be a global instance admin
+
+        Returns:
+            A `User` object
+        """
+        res = api.client.execute(
+            cls.CREATE_USER_MUTATION,
+            {"email": email, "admin": admin},
+        )
+        return User(api.client, res["createUser"]["user"])
+
+    @property
+    def api_keys(self):
+        """List of API key names associated with the user.
+
+        Returns:
+            list[str]: Names of API keys associated with the user. Empty list if user
+                has no API keys or if API key data hasn't been loaded.
+        """
+        if self._attrs.get("apiKeys") is None:
+            return []
+        return [k["node"]["name"] for k in self._attrs["apiKeys"]["edges"]]
+
+    @property
+    def teams(self):
+        """List of team names that the user is a member of.
+
+        Returns:
+            list (list): Names of teams the user belongs to. Empty list if user has no
+                team memberships or if teams data hasn't been loaded.
+        """
+        if self._attrs.get("teams") is None:
+            return []
+        return [k["node"]["name"] for k in self._attrs["teams"]["edges"]]
+
+    def delete_api_key(self, api_key):
+        """Delete a user's api key.
+
+        Args:
+            api_key (str): The name of the API key to delete. This should be
+                one of the names returned by the `api_keys` property.
+
+        Returns:
+            Boolean indicating success
+
+        Raises:
+            ValueError if the api_key couldn't be found
+        """
+        idx = self.api_keys.index(api_key)
+        try:
+            self._client.execute(
+                self.DELETE_API_KEY_MUTATION,
+                {"id": self._attrs["apiKeys"]["edges"][idx]["node"]["id"]},
+            )
+        except requests.exceptions.HTTPError:
+            return False
+        return True
+
+    def generate_api_key(self, description=None):
+        """Generate a new api key.
+
+        Args:
+            description (str, optional): A description for the new API key. This can be
+                used to identify the purpose of the API key.
+
+        Returns:
+            The new api key, or None on failure
+        """
+        try:
+            # We must make this call using credentials from the original user
+            key = self.user_api.client.execute(
+                self.GENERATE_API_KEY_MUTATION, {"description": description}
+            )["generateApiKey"]["apiKey"]
+            self._attrs["apiKeys"]["edges"].append({"node": key})
+            return key["name"]
+        except (requests.exceptions.HTTPError, AttributeError):
+            return None
+
+    def __repr__(self):
+        if "email" in self._attrs:
+            return f"<User {self._attrs['email']}>"
+        elif "username" in self._attrs:
+            return f"<User {self._attrs['username']}>"
+        elif "id" in self._attrs:
+            return f"<User {self._attrs['id']}>"
+        elif "name" in self._attrs:
+            return f"<User {self._attrs['name']!r}>"
+        else:
+            return "<User ???>"

wandb/apis/public/utils.py

@@ -0,0 +1,210 @@
+import re
+from enum import Enum
+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
+
+
+def parse_s3_url_to_s3_uri(url) -> str:
+    """Convert an S3 HTTP(S) URL to an S3 URI.
+
+    Arguments:
+        url (str): The S3 URL to convert, in the format
+                   'http(s)://<bucket>.s3.<region>.amazonaws.com/<key>'.
+                   or 'http(s)://<bucket>.s3.amazonaws.com/<key>'
+
+    Returns:
+        str: The corresponding S3 URI in the format 's3://<bucket>/<key>'.
+
+    Raises:
+        ValueError: If the provided URL is not a valid S3 URL.
+    """
+    # Regular expression to match S3 URL pattern
+    s3_pattern = r"^https?://.*s3.*amazonaws\.com.*"
+    parsed_url = urlparse(url)
+
+    # Check if it's an S3 URL
+    match = re.match(s3_pattern, parsed_url.geturl())
+    if not match:
+        raise ValueError("Invalid S3 URL")
+
+    # Extract bucket name and key
+    bucket_name, *_ = parsed_url.netloc.split(".")
+    key = parsed_url.path.lstrip("/")
+
+    # Construct the S3 URI
+    s3_uri = f"s3://{bucket_name}/{key}"
+
+    return s3_uri
+
+
+class PathType(Enum):
+    """We have lots of different paths users pass in to fetch artifacts, projects, etc.
+
+    This enum is used for specifying what format the path is in given a string path.
+    """
+
+    PROJECT = "PROJECT"
+    ARTIFACT = "ARTIFACT"
+
+
+def parse_org_from_registry_path(path: str, path_type: PathType) -> str:
+    """Parse the org from a registry path.
+
+    Essentially fetching the "entity" from the path but for Registries the entity is actually the org.
+
+    Args:
+        path (str): The path to parse. Can be a project path <entity>/<project> or <project> or an
+        artifact path like <entity>/<project>/<artifact> or <project>/<artifact> or <artifact>
+        path_type (PathType): The type of path to parse.
+    """
+    parts = path.split("/")
+    expected_parts = 3 if path_type == PathType.ARTIFACT else 2
+
+    if len(parts) >= expected_parts:
+        org, project = parts[:2]
+        if is_artifact_registry_project(project):
+            return org
+    return ""
+
+
+def fetch_org_from_settings_or_entity(
+    settings: dict, default_entity: Optional[str] = None
+) -> str:
+    """Fetch the org from either the settings or deriving it from the entity.
+
+    Returns the org from the settings if available. If no org is passed in or set, the entity is used to fetch the org.
+
+    Args:
+        organization (str | None): The organization to fetch the org for.
+        settings (dict): The settings to fetch the org for.
+        default_entity (str | None): The default entity to fetch the org for.
+    """
+    if (organization := settings.get("organization")) is None:
+        # Fetch the org via the Entity. Won't work if default entity is a personal entity and belongs to multiple orgs
+        entity = settings.get("entity") or default_entity
+        if entity is None:
+            raise ValueError(
+                "No entity specified and can't fetch organization from the entity"
+            )
+        entity_orgs = InternalApi()._fetch_orgs_and_org_entities_from_entity(entity)
+        entity_org = one(
+            entity_orgs,
+            too_short=ValueError(
+                "No organizations found for entity. Please specify an organization in the settings."
+            ),
+            too_long=ValueError(
+                "Multiple organizations found for entity. Please specify an organization in the settings."
+            ),
+        )
+        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/apis/reports/__init__.py

@@ -0,0 +1 @@
+from .v2 import *  # noqa: F403

wandb/apis/reports/v1/__init__.py

@@ -0,0 +1,8 @@
+import wandb
+
+try:
+    from wandb_workspaces.reports.v1 import *  # noqa: F403
+except ImportError:
+    wandb.termerror(
+        "Failed to import wandb_workspaces.  To edit reports programmatically, please install it using `pip install wandb[workspaces]`."
+    )

wandb/apis/reports/v2/__init__.py

@@ -0,0 +1,8 @@
+import wandb
+
+try:
+    from wandb_workspaces.reports.v2 import *  # noqa: F403
+except ImportError:
+    wandb.termerror(
+        "Failed to import wandb_workspaces.  To edit reports programmatically, please install it using `pip install wandb[workspaces]`."
+    )

wandb/apis/workspaces/__init__.py

@@ -0,0 +1,8 @@
+import wandb
+
+try:
+    from wandb_workspaces.workspaces import *  # noqa: F403
+except ImportError:
+    wandb.termerror(
+        "Failed to import wandb_workspaces. To edit workspaces programmatically, please install it using `pip install wandb[workspaces]`."
+    )

wandb/automations/__init__.py

@@ -0,0 +1,73 @@
+import wandb
+from wandb._pydantic import IS_PYDANTIC_V2
+
+from .actions import ActionType, DoNothing, SendNotification, SendWebhook
+from .automations import Automation, NewAutomation
+from .events import (
+    ArtifactEvent,
+    EventType,
+    MetricChangeFilter,
+    MetricThresholdFilter,
+    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 requires Pydantic v2. "
+        "We recommend upgrading `pydantic` 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.
+    wandb.termwarn(
+        "The W&B Automations API is experimental and the implementation is subject to change."
+        "Review the release notes before upgrading. We recommend pinning your "
+        f"package version to `{wandb.__package__}=={wandb.__version__}` to reduce the risk of disruption.",
+        repeat=False,
+    )
+# ----------------------------------------------------------------------------
+
+__all__ = [
+    # Scopes
+    "ScopeType",  # doc:exclude
+    "ArtifactCollectionScope",  # doc:exclude
+    "ProjectScope",  # doc:exclude
+    # Events
+    "EventType",  # doc:exclude
+    "OnAddArtifactAlias",
+    "OnCreateArtifact",
+    "OnLinkArtifact",
+    "OnRunMetric",
+    "ArtifactEvent",  # doc:exclude
+    "RunEvent",  # doc:exclude
+    "MetricThresholdFilter",
+    "MetricChangeFilter",
+    # Actions
+    "ActionType",  # doc:exclude
+    "SendNotification",
+    "SendWebhook",
+    "DoNothing",
+    # Automations
+    "Automation",
+    "NewAutomation",
+    # Integrations
+    "Integration",  # doc:exclude
+    "SlackIntegration",  # doc:exclude
+    "WebhookIntegration",  # doc:exclude
+]

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",
+]