wandb 0.21.2__py3-none-macosx_12_0_x86_64.whl

wandb/__main__.py

@@ -0,0 +1,3 @@
+from wandb.cli import cli
+
+cli.cli(prog_name="python -m wandb")

wandb/_iterutils.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Iterable, TypeVar, Union, overload
+
+if TYPE_CHECKING:
+    T = TypeVar("T")
+    ClassInfo = Union[type[T], tuple[type[T], ...]]
+
+
+@overload
+def always_list(obj: Iterable[T], base_type: ClassInfo = ...) -> list[T]: ...
+@overload
+def always_list(obj: T, base_type: ClassInfo = ...) -> list[T]: ...
+def always_list(obj: Any, base_type: Any = (str, bytes)) -> list[T]:
+    """Return a guaranteed list of objects from a single instance OR iterable of such objects.
+
+    By default, assume the returned list should have string-like elements (i.e. `str`/`bytes`).
+
+    Adapted from `more_itertools.always_iterable`, but simplified for internal use.  See:
+    https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.always_iterable
+    """
+    return [obj] if isinstance(obj, base_type) else list(obj)
+
+
+def one(
+    iterable: Iterable[T],
+    too_short: type[Exception] | Exception | None = None,
+    too_long: type[Exception] | Exception | None = None,
+) -> T:
+    """Return the only item in the iterable.
+
+    Note:
+        This is intended **only** as an internal helper/convenience function,
+        and its implementation is directly adapted from `more_itertools.one`.
+        Users needing similar functionality are strongly encouraged to use
+        that library instead:
+        https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.one
+
+    Args:
+        iterable: The iterable to get the only item from.
+        too_short: Custom exception to raise if the iterable has no items.
+        too_long: Custom exception to raise if the iterable has multiple items.
+
+    Raises:
+        ValueError or `too_short`: If the iterable has no items.
+        ValueError or `too_long`: If the iterable has multiple items.
+    """
+    # For a general iterable, avoid inadvertently iterating through all values,
+    # which may be costly or impossible (e.g. if infinite).  Only check that:
+
+    # ... the first item exists
+    it = iter(iterable)
+    try:
+        obj = next(it)
+    except StopIteration:
+        raise (too_short or ValueError("Expected 1 item in iterable, got 0")) from None
+
+    # ...the second item doesn't
+    try:
+        _ = next(it)
+    except StopIteration:
+        return obj
+    raise (
+        too_long or ValueError("Expected 1 item in iterable, got multiple")
+    ) from None

wandb/_pydantic/__init__.py

@@ -0,0 +1,30 @@
+"""Internal utilities for working with pydantic."""
+
+from .base import (
+    CompatBaseModel,
+    GQLBase,
+    GQLId,
+    SerializedToJson,
+    Typename,
+    ensure_json,
+)
+from .utils import IS_PYDANTIC_V2, from_json, gql_typename, pydantic_isinstance, to_json
+from .v1_compat import AliasChoices, computed_field, field_validator, model_validator
+
+__all__ = [
+    "IS_PYDANTIC_V2",
+    "CompatBaseModel",
+    "GQLBase",
+    "Typename",
+    "GQLId",
+    "SerializedToJson",
+    "AliasChoices",
+    "computed_field",
+    "field_validator",
+    "model_validator",
+    "pydantic_isinstance",
+    "to_json",
+    "from_json",
+    "ensure_json",
+    "gql_typename",
+]

wandb/_pydantic/base.py

@@ -0,0 +1,128 @@
+"""Base classes and other customizations for generated pydantic types."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, Literal, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field, Json, StrictStr
+from typing_extensions import Annotated, TypedDict, Unpack, override
+
+from .utils import IS_PYDANTIC_V2, to_json
+from .v1_compat import PydanticCompatMixin
+
+if TYPE_CHECKING:
+    from pydantic.main import IncEx
+
+
+class ModelDumpKwargs(TypedDict, total=False):
+    """Shared keyword arguments for `BaseModel.model_{dump,dump_json}`."""
+
+    include: IncEx | None
+    exclude: IncEx | None
+    context: dict[str, Any] | None
+    by_alias: bool | None
+    exclude_unset: bool
+    exclude_defaults: bool
+    exclude_none: bool
+    round_trip: bool
+    warnings: bool | Literal["none", "warn", "error"]
+    fallback: Callable[[Any], Any] | None
+    serialize_as_any: bool
+
+
+#: Custom overrides of default kwargs for `BaseModel.model_{dump,dump_json}`.
+MODEL_DUMP_DEFAULTS = ModelDumpKwargs(
+    by_alias=True,  # Always serialize with aliases (e.g. camelCase names)
+    round_trip=True,  # Ensure serialized values remain valid inputs for deserialization
+)
+
+
+# v1-compatible base class for pydantic types.
+class CompatBaseModel(PydanticCompatMixin, BaseModel):
+    __doc__ = None  # Prevent subclasses from inheriting the BaseModel docstring
+
+
+# Base class for all GraphQL-generated types.
+# Omitted from docstring to avoid inclusion in generated docs.
+class GQLBase(CompatBaseModel):
+    model_config = ConfigDict(
+        populate_by_name=True,  # Discouraged in pydantic v2.11+, will be deprecated in v3
+        validate_by_name=True,  # Introduced in pydantic v2.11
+        validate_by_alias=True,  # Introduced in pydantic v2.11
+        serialize_by_alias=True,  # Introduced in pydantic v2.11
+        validate_assignment=True,
+        validate_default=True,
+        use_attribute_docstrings=True,
+        from_attributes=True,
+        revalidate_instances="always",
+        protected_namespaces=(),  # Some GraphQL fields may begin with "model_"
+    )
+
+    @override
+    def model_dump(
+        self,
+        *,
+        mode: Literal["json", "python"] | str = "json",  # NOTE: changed default
+        **kwargs: Unpack[ModelDumpKwargs],
+    ) -> dict[str, Any]:
+        kwargs = {**MODEL_DUMP_DEFAULTS, **kwargs}
+        return super().model_dump(mode=mode, **kwargs)
+
+    @override
+    def model_dump_json(
+        self,
+        *,
+        indent: int | None = None,
+        **kwargs: Unpack[ModelDumpKwargs],
+    ) -> str:
+        kwargs = {**MODEL_DUMP_DEFAULTS, **kwargs}
+        return super().model_dump_json(indent=indent, **kwargs)
+
+
+# ------------------------------------------------------------------------------
+# Reusable annotations for field types
+T = TypeVar("T")
+
+if IS_PYDANTIC_V2 or TYPE_CHECKING:
+    GQLId = Annotated[
+        StrictStr,
+        Field(repr=False, frozen=True),
+    ]
+else:
+    # FIXME: Find a way to fix this for pydantic v1, which doesn't like when
+    # `Field(...)` used in the field assignment AND `Annotated[...]`.
+    # This is a problem for codegen, which can currently outputs e.g.
+    #
+    #   class MyModel(GQLBase):
+    #       my_id: GQLId = Field(alias="myID")
+    #
+    GQLId = StrictStr  # type: ignore[misc]
+
+Typename = Annotated[
+    T,
+    Field(repr=False, frozen=True, alias="__typename"),
+]
+
+
+def ensure_json(v: Any) -> Any:
+    """In case the incoming value isn't serialized JSON, reserialize it.
+
+    This lets us use `Json[...]` fields with values that are already deserialized.
+    """
+    # NOTE: Assumes that the deserialized type is not itself a string.
+    # Revisit this if we need to support deserialized types that are str/bytes.
+    return v if isinstance(v, (str, bytes)) else to_json(v)
+
+
+if IS_PYDANTIC_V2 or TYPE_CHECKING:
+    from pydantic import BeforeValidator, PlainSerializer
+
+    SerializedToJson = Annotated[
+        Json[T],
+        # Allow lenient instantiation/validation: incoming data may already be deserialized.
+        BeforeValidator(ensure_json),
+        PlainSerializer(to_json),
+    ]
+else:
+    # FIXME: Restore, modify, or replace this later after ensuring pydantic v1 compatibility.
+    SerializedToJson = Json[T]  # type: ignore[misc]

wandb/_pydantic/utils.py

@@ -0,0 +1,80 @@
+"""Internal utilities for working with Pydantic types and data."""
+
+from __future__ import annotations
+
+import json
+import sys
+from contextlib import suppress
+from typing import Any, Type
+
+import pydantic
+from pydantic import BaseModel, ValidationError
+from typing_extensions import TypeAlias
+
+PYTHON_VERSION = sys.version_info
+
+pydantic_major, *_ = pydantic.VERSION.split(".")
+IS_PYDANTIC_V2: bool = int(pydantic_major) >= 2
+
+
+BaseModelType: TypeAlias = Type[BaseModel]
+
+
+def gql_typename(cls: type[BaseModel]) -> str:
+    """Get the GraphQL typename for a Pydantic model."""
+    if (field := cls.model_fields.get("typename__")) and (typename := field.default):
+        return typename
+    raise TypeError(f"Cannot extract GraphQL typename from: {cls.__qualname__!r}.")
+
+
+if IS_PYDANTIC_V2:
+    import pydantic_core  # pydantic_core is only installed by pydantic v2
+
+    def from_json(s: str) -> Any:
+        """Quickly deserialize a JSON string to a Python object."""
+        return pydantic_core.from_json(s)
+
+    def to_json(v: Any) -> str:
+        """Quickly serialize a (possibly Pydantic) object to a JSON string."""
+        return pydantic_core.to_json(v, by_alias=True, round_trip=True).decode("utf-8")
+
+    def pydantic_isinstance(
+        v: Any, classinfo: BaseModelType | tuple[BaseModelType, ...]
+    ) -> bool:
+        """Return True if the object could be parsed into the given Pydantic type.
+
+        This is like a more lenient version of `isinstance()` for use with Pydantic.
+        In Pydantic v2, should be fast since the underlying implementation is in Rust,
+        and it may be preferable over `try:...except ValidationError:...`.
+
+        See: https://docs.pydantic.dev/latest/api/pydantic_core/#pydantic_core.SchemaValidator.isinstance_python
+        """
+        if isinstance(classinfo, tuple):
+            return any(
+                cls.__pydantic_validator__.isinstance_python(v) for cls in classinfo
+            )
+        cls = classinfo
+        return cls.__pydantic_validator__.isinstance_python(v)
+
+else:
+    # Pydantic v1 fallback implementations.
+    # These may be noticeably slower, but their primary goal is to ensure
+    # compatibility with Pydantic v1 so long as we need to support it.
+
+    from pydantic.json import pydantic_encoder  # Only valid in pydantic v1
+
+    def from_json(s: str) -> Any:
+        return json.loads(s)
+
+    def to_json(v: Any) -> str:
+        return json.dumps(v, default=pydantic_encoder)
+
+    def pydantic_isinstance(
+        v: Any, classinfo: BaseModelType | tuple[BaseModelType, ...]
+    ) -> bool:
+        classes = classinfo if isinstance(classinfo, tuple) else (classinfo,)
+        for cls in classes:
+            with suppress(ValidationError):
+                cls.model_validate(v)
+                return True
+        return False

wandb/_pydantic/v1_compat.py

@@ -0,0 +1,284 @@
+"""Provides partial support for compatibility with Pydantic v1."""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from inspect import signature
+from operator import attrgetter
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, Literal, overload
+
+import pydantic
+
+from .utils import IS_PYDANTIC_V2, to_json
+
+if TYPE_CHECKING:
+    from typing import Protocol
+
+    class V1Model(Protocol):
+        # ------------------------------------------------------------------------------
+        # NOTE: These aren't part of the original v1 BaseModel spec, but were added as
+        # internal helpers and are (re-)declared here to satisfy mypy checks.
+        @classmethod
+        def _dump_json_vals(cls, values: dict, by_alias: bool) -> dict: ...
+
+        # ------------------------------------------------------------------------------
+        # These methods are part of the original v1 BaseModel spec.
+
+        __config__: ClassVar[type]
+        __fields__: ClassVar[dict[str, Any]]
+        __fields_set__: set[str]
+
+        @classmethod
+        def update_forward_refs(cls, *args: Any, **kwargs: Any) -> None: ...
+        @classmethod
+        def construct(cls, *args: Any, **kwargs: Any) -> V1Model: ...
+        @classmethod
+        def parse_obj(cls, *args: Any, **kwargs: Any) -> V1Model: ...
+        @classmethod
+        def parse_raw(cls, *args: Any, **kwargs: Any) -> V1Model: ...
+
+        def dict(self, **kwargs: Any) -> dict[str, Any]: ...
+        def json(self, **kwargs: Any) -> str: ...
+        def copy(self, **kwargs: Any) -> V1Model: ...
+
+
+# Maps {v2 -> v1} model config keys that were renamed in v2.
+# See: https://docs.pydantic.dev/latest/migration/#changes-to-config
+_V1_CONFIG_KEYS = {
+    "populate_by_name": "allow_population_by_field_name",
+    "str_to_lower": "anystr_lower",
+    "str_strip_whitespace": "anystr_strip_whitespace",
+    "str_to_upper": "anystr_upper",
+    "ignored_types": "keep_untouched",
+    "str_max_length": "max_anystr_length",
+    "str_min_length": "min_anystr_length",
+    "from_attributes": "orm_mode",
+    "json_schema_extra": "schema_extra",
+    "validate_default": "validate_all",
+}
+
+
+def convert_v2_config(v2_config: dict[str, Any]) -> dict[str, Any]:
+    """Internal helper: Return a copy of the v2 ConfigDict with renamed v1 keys."""
+    return {_V1_CONFIG_KEYS.get(k, k): v for k, v in v2_config.items()}
+
+
+@lru_cache(maxsize=None)  # Reduce repeat introspection via `signature()`
+def allowed_arg_names(func: Callable) -> set[str]:
+    """Internal helper: Return the names of args accepted by the given function."""
+    return set(signature(func).parameters)
+
+
+# Pydantic BaseModels are defined with a custom metaclass, but its namespace
+# has changed between pydantic versions.
+#
+# In v1, it can be imported as `from pydantic.main import ModelMetaclass`
+# In v2, it's defined in an internal module so we avoid directly importing it.
+PydanticModelMetaclass: type = type(pydantic.BaseModel)
+
+
+class V1MixinMetaclass(PydanticModelMetaclass):
+    def __new__(
+        cls,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        **kwargs: Any,
+    ):
+        # In the class definition, convert the model config, if any:
+        #     # BEFORE
+        #     class MyModel(BaseModel):  # v2 model with `ConfigDict`
+        #         model_config = ConfigDict(populate_by_name=True)
+        #
+        #     # AFTER
+        #     class MyModel(BaseModel):  # v1 model with inner `Config` class
+        #         class Config:
+        #             allow_population_by_field_name = True
+        if config_dict := namespace.pop("model_config", None):
+            namespace["Config"] = type("Config", (), convert_v2_config(config_dict))
+        return super().__new__(cls, name, bases, namespace, **kwargs)
+
+    @property
+    def model_fields(self) -> dict[str, Any]:
+        return self.__fields__  # type: ignore[deprecated]
+
+
+# Mixin to ensure compatibility of Pydantic models if Pydantic v1 is detected.
+# These are "best effort" implementations and cannot guarantee complete
+# compatibility in v1 environments.
+#
+# Whenever possible, users should strongly prefer upgrading to Pydantic v2 to
+# ensure full compatibility.
+class V1Mixin(metaclass=V1MixinMetaclass):
+    # Internal compat helpers
+    @classmethod
+    def _dump_json_vals(cls, values: dict[str, Any], by_alias: bool) -> dict[str, Any]:
+        """Reserialize values from `Json`-typed fields after dumping the model to dict."""
+        # Get the expected keys (after `.model_dump()`) for `Json`-typed fields.
+        # Note: In v1, `Json` fields have `ModelField.parse_json == True`
+        json_fields = (f for f in cls.__fields__.values() if f.parse_json)  # type: ignore[deprecated]
+        get_key = attrgetter("alias" if by_alias else "name")
+        json_field_keys = set(map(get_key, json_fields))
+
+        return {
+            # Only serialize `Json` fields with non-null values.
+            k: to_json(v) if ((v is not None) and (k in json_field_keys)) else v
+            for k, v in values.items()
+        }
+
+    # ------------------------------------------------------------------------------
+    @classmethod
+    def __try_update_forward_refs__(cls: type[V1Model], **localns: Any) -> None:
+        if hasattr(sup := super(), "__try_update_forward_refs__"):
+            sup.__try_update_forward_refs__(**localns)
+
+    @classmethod
+    def model_rebuild(cls, *args: Any, **kwargs: Any) -> None:
+        return cls.update_forward_refs(*args, **kwargs)
+
+    @classmethod
+    def model_construct(cls, *args: Any, **kwargs: Any) -> V1Model:
+        return cls.construct(*args, **kwargs)
+
+    @classmethod
+    def model_validate(cls, *args: Any, **kwargs: Any) -> V1Model:
+        return cls.parse_obj(*args, **kwargs)
+
+    @classmethod
+    def model_validate_json(cls, *args: Any, **kwargs: Any) -> V1Model:
+        return cls.parse_raw(*args, **kwargs)
+
+    def model_dump(self: V1Model, **kwargs: Any) -> dict[str, Any]:
+        # Pass only kwargs that are allowed in the V1 method.
+        allowed_keys = allowed_arg_names(self.dict) & kwargs.keys()
+        dict_ = self.dict(**{k: kwargs[k] for k in allowed_keys})
+
+        # Ugly hack: Try to serialize `Json` fields correctly when `round_trip=True` in pydantic v1
+        if kwargs.get("round_trip", False):
+            by_alias: bool = kwargs.get("by_alias", False)
+            return self._dump_json_vals(dict_, by_alias=by_alias)
+
+        return dict_
+
+    def model_dump_json(self: V1Model, **kwargs: Any) -> str:
+        # Pass only kwargs that are allowed in the V1 method.
+        allowed_keys = allowed_arg_names(self.json) & kwargs.keys()
+        json_ = self.json(**{k: kwargs[k] for k in allowed_keys})
+
+        # Ugly hack: Try to serialize `Json` fields correctly when `round_trip=True` in pydantic v1
+        if kwargs.get("round_trip", False):
+            by_alias: bool = kwargs.get("by_alias", False)
+            dict_ = json.loads(json_)
+            return json.dumps(self._dump_json_vals(dict_, by_alias=by_alias))
+
+        return json_
+
+    def model_copy(self: V1Model, **kwargs: Any) -> V1Model:
+        # Pass only kwargs that are allowed in the V1 method.
+        allowed_keys = allowed_arg_names(self.copy) & kwargs.keys()
+        return self.copy(**{k: kwargs[k] for k in allowed_keys})
+
+    @property
+    def model_fields_set(self: V1Model) -> set[str]:
+        return self.__fields_set__
+
+
+# Placeholder. Pydantic v2 is already compatible with itself, so no need for extra mixins.
+class V2Mixin:
+    pass
+
+
+# Pick the mixin type based on the detected Pydantic version.
+PydanticCompatMixin: type = V2Mixin if IS_PYDANTIC_V2 else V1Mixin
+
+
+# ----------------------------------------------------------------------------
+# Decorators and other pydantic helpers
+# ----------------------------------------------------------------------------
+if IS_PYDANTIC_V2:
+    field_validator = pydantic.field_validator
+    model_validator = pydantic.model_validator
+    AliasChoices = pydantic.AliasChoices
+    computed_field = pydantic.computed_field
+
+else:
+    # Redefines `@field_validator` with a v2-like signature
+    # to call `@validator` from v1 instead.
+    def field_validator(
+        field: str,
+        /,
+        *fields: str,
+        mode: Literal["before", "after", "wrap", "plain"] = "after",
+        check_fields: bool | None = None,
+        **_: Any,
+    ) -> Callable:
+        return pydantic.validator(  # type: ignore[deprecated]
+            field,
+            *fields,
+            pre=(mode == "before"),
+            always=True,
+            check_fields=bool(check_fields),
+            allow_reuse=True,
+        )
+
+    # Redefines `@model_validator` with a v2-like signature
+    # to call `@root_validator` from v1 instead.
+    def model_validator(
+        *,
+        mode: Literal["before", "after", "wrap", "plain"],
+        **_: Any,
+    ) -> Callable:
+        if mode == "after":
+            # Patch the behavior for `@model_validator(mode="after")` in v1.  This is
+            # necessarily complicated because:
+            # - `@model_validator(mode="after")` decorates an instance method in pydantic v2
+            # - `@root_validator(pre=False)` always decorates a classmethod in pydantic v1
+            def _decorator(v2_method: Callable) -> Any:
+                def v1_method(
+                    cls: type[V1Model], values: dict[str, Any]
+                ) -> dict[str, Any]:
+                    # Note: Since this is an "after" validator, the values should already be
+                    # validated, so `.construct()` in v1 (`.model_construct()` in v2)
+                    # should create a valid object to pass to the **original** decorated instance method.
+                    validated = v2_method(cls.construct(**values))
+
+                    # Pydantic v1 expects the validator to return a dict of {field_name -> value}
+                    return {
+                        name: getattr(validated, name) for name in validated.__fields__
+                    }
+
+                return pydantic.root_validator(pre=False, allow_reuse=True)(  # type: ignore[call-overload]
+                    classmethod(v1_method)
+                )
+
+            return _decorator
+        else:
+            return pydantic.root_validator(pre=(mode == "before"), allow_reuse=True)  # type: ignore[call-overload]
+
+    @overload  # type: ignore[no-redef]
+    def computed_field(func: Callable | property, /) -> property: ...
+    @overload
+    def computed_field(
+        func: None, /, **_: Any
+    ) -> Callable[[Callable | property], property]: ...
+
+    def computed_field(
+        func: Callable | property | None = None, /, **_: Any
+    ) -> property | Callable[[Callable | property], property]:
+        """Compatibility wrapper for Pydantic v2's `computed_field` in v1."""
+
+        def always_property(f: Callable | property) -> property:
+            # Convert the method to a property only if needed
+            return f if isinstance(f, property) else property(f)
+
+        # Handle both decorator styles
+        return always_property if (func is None) else always_property(func)
+
+    class AliasChoices:  # type: ignore [no-redef]
+        """Placeholder class for Pydantic v2's AliasChoices for partial v1 compatibility."""
+
+        aliases: list[str]
+
+        def __init__(self, *aliases: str):
+            self.aliases = list(aliases)