dyff-schema 0.25.1__tar.gz → 0.26.1__tar.gz

{dyff_schema-0.25.1/dyff_schema.egg-info → dyff_schema-0.26.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: dyff-schema
-Version: 0.25.1
+Version: 0.26.1
 Summary: Data models for the Dyff AI auditing platform.
 Author-email: Digital Safety Research Institute <contact@dsri.org>
 License: Apache-2.0

{dyff_schema-0.25.1 → dyff_schema-0.26.1}/dyff/schema/v0/r1/base.py

@@ -561,6 +561,25 @@ def list_(
         return pydantic.conlist(item_type, min_items=list_size, max_items=list_size)
 
 
+class Null:
+    """Use this type in a Union to make Pydantic generate a JSON Schema that accepts
+    'null' for the field value."""
+
+    @classmethod
+    def __get_validators__(cls):  # -> Generator[Callable, None, None]:
+        yield cls.validate
+
+    @classmethod
+    def validate(cls, value: Any, field: pydantic.fields.ModelField) -> None:
+        if value is not None:
+            raise ValueError()
+        return None
+
+    @classmethod
+    def __modify_schema__(cls, field_schema: dict[str, Any]) -> None:
+        field_schema["type"] = "null"
+
+
 # mypy gets confused because 'dict' is the name of a method in DyffBaseModel
 _ModelAsDict = dict[str, Any]
 
@@ -649,6 +668,7 @@ __all__ = [
     "Int16",
     "Int32",
     "Int64",
+    "Null",
     "UInt8",
     "UInt16",
     "UInt32",

{dyff_schema-0.25.1 → dyff_schema-0.26.1}/dyff/schema/v0/r1/commands.py

@@ -7,19 +7,23 @@ These are used internally by the platform and users typically won't encounter th
 
 from __future__ import annotations
 
-from typing import Any, Literal, Union
+from typing import Any, Literal, Optional, Union
 
 import pydantic
 
-from .base import DyffSchemaBaseModel
+from .base import DyffSchemaBaseModel, Null
 from .platform import (
-    Documented,
     DyffEntityType,
     EntityKindLiteral,
+    FamilyMember,
     FamilyMembers,
-    Labeled,
+    LabelKeyType,
+    LabelValueType,
     SchemaVersion,
     Status,
+    TagNameType,
+    summary_maxlen,
+    title_maxlen,
 )
 
 # ----------------------------------------------------------------------------
@@ -47,14 +51,13 @@ class FamilyIdentifier(EntityIdentifier):
     kind: Literal["Family"] = "Family"
 
 
-class Command(SchemaVersion):
+class Command(SchemaVersion, DyffSchemaBaseModel):
     """Base class for Command messages.
 
     Commands define the API of the "command model" in our CQRS architecture.
     """
 
     command: Literal[
-        "AppendRevisionToHistory",
         "CreateEntity",
         "EditEntityDocumentation",
         "EditEntityLabels",
@@ -91,9 +94,53 @@ class CreateEntity(Command):
 # ----------------------------------------------------------------------------
 
 
-class EditEntityDocumentationData(Documented, EntityIdentifier):
+class EditEntityDocumentationPatch(DyffSchemaBaseModel):
+    """Same properties as DocumentationBase, but assigning None to a field is
+    interpreted as a command to delete that field.
+
+    Fields that are assigned explicitly remain unchanged.
+    """
+
+    title: Optional[Union[pydantic.constr(max_length=title_maxlen()), Null]] = (  # type: ignore
+        pydantic.Field(
+            default=None,
+            description='A short plain string suitable as a title or "headline".'
+            " Providing an explicit None value deletes the current value.",
+        )
+    )
+
+    summary: Optional[Union[pydantic.constr(max_length=summary_maxlen()), Null]] = (  # type: ignore
+        pydantic.Field(
+            default=None,
+            description="A brief summary, suitable for display in"
+            " small UI elements. Providing an explicit None value deletes the"
+            " current value.",
+        )
+    )
+
+    fullPage: Optional[Union[str, Null]] = pydantic.Field(
+        default=None,
+        description="Long-form documentation. Interpreted as"
+        " Markdown. There are no length constraints, but be reasonable."
+        " Providing an explicit None value deletes the current value.",
+    )
+
+
+class EditEntityDocumentationAttributes(DyffSchemaBaseModel):
+    """Attributes for the EditEntityDocumentation command."""
+
+    documentation: EditEntityDocumentationPatch = pydantic.Field(
+        description="Edits to make to the documentation."
+    )
+
+
+class EditEntityDocumentationData(EntityIdentifier):
     """Payload data for the EditEntityDocumentation command."""
 
+    attributes: EditEntityDocumentationAttributes = pydantic.Field(
+        description="The command attributes"
+    )
+
 
 class EditEntityDocumentation(Command):
     """Edit the documentation associated with an entity.
@@ -110,9 +157,24 @@ class EditEntityDocumentation(Command):
 # ----------------------------------------------------------------------------
 
 
-class EditEntityLabelsData(Labeled, EntityIdentifier):
+class EditEntityLabelsAttributes(DyffSchemaBaseModel):
+    """Attributes for the EditEntityLabels command."""
+
+    labels: dict[LabelKeyType, Optional[Union[LabelValueType, Null]]] = pydantic.Field(
+        default_factory=dict,
+        description="A set of key-value labels for the resource."
+        " Existing label keys that are not provided in the edit remain unchanged."
+        " Providing an explicit None value deletes the corresponding key.",
+    )
+
+
+class EditEntityLabelsData(EntityIdentifier):
     """Payload data for the EditEntityLabels command."""
 
+    attributes: EditEntityLabelsAttributes = pydantic.Field(
+        description="The command attributes"
+    )
+
 
 class EditEntityLabels(Command):
     """Edit the labels associated with an entity.
@@ -129,9 +191,21 @@ class EditEntityLabels(Command):
 # ----------------------------------------------------------------------------
 
 
+class EditFamilyMembersAttributes(DyffSchemaBaseModel):
+    """Attributes for the EditFamilyMembers command."""
+
+    members: dict[TagNameType, Optional[Union[FamilyMember, Null]]] = pydantic.Field(
+        description="Mapping of names to IDs of member resources.",
+    )
+
+
 class EditFamilyMembersData(FamilyMembers, FamilyIdentifier):
     """Payload data for the EditFamilyMembers command."""
 
+    attributes: EditFamilyMembersAttributes = pydantic.Field(
+        description="The command attributes"
+    )
+
 
 class EditFamilyMembers(Command):
     """Edit the labels associated with an entity.
@@ -159,9 +233,25 @@ class ForgetEntity(Command):
 # ----------------------------------------------------------------------------
 
 
-class UpdateEntityStatusData(Status, EntityIdentifier):
+class UpdateEntityStatusAttributes(DyffSchemaBaseModel):
+    """Attributes for the UpdateEntityStatus command."""
+
+    status: str = pydantic.Field(
+        description=Status.__fields__["status"].field_info.description
+    )
+
+    reason: Optional[Union[str, Null]] = pydantic.Field(
+        description=Status.__fields__["reason"].field_info.description
+    )
+
+
+class UpdateEntityStatusData(EntityIdentifier):
     """Payload data for the UpdateEntityStatus command."""
 
+    attributes: UpdateEntityStatusAttributes = pydantic.Field(
+        description="The command attributes"
+    )
+
 
 class UpdateEntityStatus(Command):
     """Update the status fields of an entity."""
@@ -189,14 +279,19 @@ __all__ = [
     "CreateEntity",
     "DyffCommandType",
     "EditEntityDocumentation",
+    "EditEntityDocumentationAttributes",
     "EditEntityDocumentationData",
+    "EditEntityDocumentationPatch",
     "EditEntityLabels",
+    "EditEntityLabelsAttributes",
     "EditEntityLabelsData",
     "EditFamilyMembers",
+    "EditFamilyMembersAttributes",
     "EditFamilyMembersData",
     "EntityIdentifier",
     "FamilyIdentifier",
     "ForgetEntity",
     "UpdateEntityStatus",
+    "UpdateEntityStatusAttributes",
     "UpdateEntityStatusData",
 ]

{dyff_schema-0.25.1 → dyff_schema-0.26.1}/dyff/schema/v0/r1/platform.py

@@ -291,21 +291,29 @@ class DyffModelWithID(DyffSchemaBaseModel):
     account: str = pydantic.Field(description="Account that owns the entity")
 
 
-LabelKey: TypeAlias = pydantic.constr(  # type: ignore
-    regex=_k8s_label_key_regex(), max_length=_k8s_label_key_maxlen()
-)
+def LabelKey() -> type[str]:
+    return pydantic.constr(
+        regex=_k8s_label_key_regex(), max_length=_k8s_label_key_maxlen()
+    )
 
 
-LabelValue: TypeAlias = Optional[  # type: ignore
-    pydantic.constr(  # type: ignore
+def LabelValue() -> type[str]:
+    return pydantic.constr(  # type: ignore
         regex=_k8s_label_value_regex(), max_length=_k8s_label_value_maxlen()
     )
-]
 
 
-TagName: TypeAlias = pydantic.constr(  # type: ignore
-    regex=_oci_image_tag_regex(), max_length=_k8s_label_key_maxlen()
-)
+def TagName() -> type[str]:
+    return pydantic.constr(  # type: ignore
+        regex=_oci_image_tag_regex(), max_length=_k8s_label_key_maxlen()
+    )
+
+
+LabelKeyType: TypeAlias = LabelKey()  # type: ignore
+
+LabelValueType: TypeAlias = LabelValue()  # type: ignore
+
+TagNameType: TypeAlias = TagName()  # type: ignore
 
 
 class Label(DyffSchemaBaseModel):
@@ -317,20 +325,20 @@ class Label(DyffSchemaBaseModel):
     https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
     """
 
-    key: LabelKey = pydantic.Field(
+    key: LabelKeyType = pydantic.Field(  # type: ignore
         description="The label key is a DNS label with an optional DNS domain"
         " prefix. For example: 'my-key', 'your.com/key_0'. Keys prefixed with"
         " 'dyff.io/', 'subdomain.dyff.io/', etc. are reserved.",
     )
 
-    value: LabelValue = pydantic.Field(
+    value: LabelValueType = pydantic.Field(  # type: ignore
         description="The label value consists of alphanumeric characters"
         " separated by '.', '-', or '_'.",
     )
 
 
 class Labeled(DyffSchemaBaseModel):
-    labels: dict[LabelKey, LabelValue] = pydantic.Field(
+    labels: dict[LabelKeyType, LabelValueType] = pydantic.Field(  # type: ignore
         default_factory=dict,
         description="A set of key-value labels for the resource. Used to"
         " specify identifying attributes of resources that are meaningful to"
@@ -372,7 +380,7 @@ class ServiceClass(str, enum.Enum):
 
 
 class ResourceAllocation(DyffSchemaBaseModel):
-    quantities: dict[LabelKey, Quantity] = pydantic.Field(
+    quantities: dict[LabelKeyType, Quantity] = pydantic.Field(  # type: ignore
         default_factory=dict,
         description="Mapping of resource keys to quantities to be allocated.",
     )
@@ -382,7 +390,7 @@ class ResourceAllocation(DyffSchemaBaseModel):
 
 class Status(DyffSchemaBaseModel):
     status: str = pydantic.Field(
-        default=None, description="Top-level resource status (assigned by system)"
+        description="Top-level resource status (assigned by system)"
     )
 
     reason: Optional[str] = pydantic.Field(
@@ -441,6 +449,12 @@ class DyffEntityMetadata(DyffSchemaBaseModel):
         description="Unique identifier of the current revision of the entity.",
     )
 
+    documentation: Optional[DocumentationBase] = pydantic.Field(
+        default_factory=DocumentationBase,
+        description="Documentation of the resource. The content is used to"
+        " populate various views in the web UI.",
+    )
+
 
 class DyffEntity(Status, Labeled, SchemaVersion, DyffModelWithID):
     kind: Literal[
@@ -668,7 +682,7 @@ class FamilyMemberKind(str, enum.Enum):
 
 
 class FamilyMemberBase(DyffSchemaBaseModel):
-    name: TagName = pydantic.Field(
+    name: TagNameType = pydantic.Field(
         description="An interpretable identifier for the member that is unique"
         " in the context of the corresponding Family.",
     )
@@ -696,7 +710,7 @@ class FamilyMember(FamilyMemberBase):
 
 
 class FamilyMembers(DyffSchemaBaseModel):
-    members: dict[TagName, FamilyMember] = pydantic.Field(
+    members: dict[TagNameType, FamilyMember] = pydantic.Field(
         default_factory=dict,
         description="Mapping of names to IDs of member resources.",
     )
@@ -711,12 +725,6 @@ class FamilyBase(DyffSchemaBaseModel):
 class Family(DyffEntity, FamilyBase, FamilyMembers):
     kind: Literal["Family"] = "Family"
 
-    documentation: DocumentationBase = pydantic.Field(
-        default_factory=DocumentationBase,
-        description="Documentation of the resource family. The content is used"
-        " to populate various views in the web UI.",
-    )
-
 
 class RevisionMetadata(DyffSchemaBaseModel):
     previousRevision: Optional[str] = pydantic.Field(
@@ -1207,7 +1215,7 @@ class ContainerImageSource(DyffSchemaBaseModel):
         " digest, even if 'tag' is specified.",
         regex=r"^sha256:[0-9a-f]{64}$",
     )
-    tag: Optional[TagName] = pydantic.Field(
+    tag: Optional[TagNameType] = pydantic.Field(
         default=None,
         description="The tag of the image. Although the image is always pulled"
         " by digest, including the tag is strongly recommended as it is often"
@@ -2479,7 +2487,9 @@ __all__ = [
     "InferenceSessionSpec",
     "Label",
     "LabelKey",
+    "LabelKeyType",
     "LabelValue",
+    "LabelValueType",
     "Labeled",
     "Measurement",
     "MeasurementLevel",
@@ -2532,6 +2542,7 @@ __all__ = [
     "Status",
     "StorageSignedURL",
     "TagName",
+    "TagNameType",
     "TaskSchema",
     "UseCase",
     "entity_class",

{dyff_schema-0.25.1 → dyff_schema-0.26.1}/dyff/schema/v0/r1/requests.py

@@ -16,11 +16,12 @@ from __future__ import annotations
 
 import re
 from datetime import datetime
-from typing import Literal, Optional, Union
+from typing import Any, Literal, Optional, Union
 
 import pydantic
 
-from .base import DyffBaseModel, DyffSchemaBaseModel
+from . import commands
+from .base import DyffBaseModel
 from .platform import (
     AnalysisBase,
     AnalysisScope,
@@ -30,10 +31,8 @@ from .platform import (
     DocumentationBase,
     EvaluationBase,
     FamilyBase,
-    FamilyMembers,
     InferenceServiceBase,
     InferenceSessionBase,
-    Labeled,
     MethodBase,
     ModelSpec,
     ModuleBase,
@@ -43,6 +42,9 @@ from .platform import (
 )
 from .version import SchemaVersion
 
+# mypy gets confused because 'dict' is the name of a method in DyffBaseModel
+_ModelAsDict = dict[str, Any]
+
 
 class DyffRequestDefaultValidators(DyffBaseModel):
     """This must be the base class for *all* request models in the Dyff schema.
@@ -62,7 +64,19 @@ class DyffRequestDefaultValidators(DyffBaseModel):
 
 
 class DyffRequestBase(SchemaVersion, DyffRequestDefaultValidators):
-    pass
+    # TODO: (DYFF-223) I think that exclude_unset=True should be the default
+    # for all schema objects, but I'm unsure of the consequences of making
+    # this change and we'll defer it until v1.
+    def dict(
+        self, *, by_alias: bool = True, exclude_unset=True, **kwargs
+    ) -> _ModelAsDict:
+        return super().dict(by_alias=by_alias, exclude_unset=exclude_unset, **kwargs)
+
+    def json(self, *, by_alias: bool = True, exclude_unset=True, **kwargs) -> str:
+        return super().json(by_alias=by_alias, exclude_unset=exclude_unset, **kwargs)
+
+
+# ----------------------------------------------------------------------------
 
 
 class DyffEntityCreateRequest(DyffRequestBase):
@@ -124,26 +138,6 @@ class DatasetCreateRequest(DyffEntityCreateRequest, DatasetBase):
     pass
 
 
-class DocumentationEditRequest(DyffRequestBase, DocumentationBase):
-    @pydantic.validator("title", check_fields=False)
-    def _validate_title(cls, title: Optional[str]) -> Optional[str]:
-        # TODO: This has to be a validator function because we can't apply the
-        # contraint to DocumentationBase, since there are already entities
-        # that violate the constraints in the data store. Fix in Schema v1.
-        if title is not None and len(title) > title_maxlen():
-            raise ValueError(f".title must have length < {title_maxlen()}")
-        return title
-
-    @pydantic.validator("summary", check_fields=False)
-    def _validate_summary(cls, summary: Optional[str]) -> Optional[str]:
-        # TODO: This has to be a validator function because we can't apply the
-        # contraint to DocumentationBase, since there are already entities
-        # that violate the constraints in the data store. Fix in Schema v1.
-        if summary is not None and len(summary) > summary_maxlen():
-            raise ValueError(f".summary must have length < {summary_maxlen()}")
-        return summary
-
-
 class InferenceServiceCreateRequest(DyffEntityCreateRequest, InferenceServiceBase):
     model: Optional[str] = pydantic.Field(
         default=None, description="ID of Model backing the service, if applicable"
@@ -239,14 +233,35 @@ class ReportCreateRequest(DyffEntityCreateRequest, ReportBase):
     )
 
 
-class FamilyMembersEditRequest(DyffRequestBase, FamilyMembers):
+# ----------------------------------------------------------------------------
+
+
+class DocumentationEditRequest(
+    DyffRequestBase, commands.EditEntityDocumentationAttributes
+):
     pass
 
 
-class LabelUpdateRequest(DyffRequestBase, Labeled):
+class FamilyMembersEditRequest(DyffRequestBase, commands.EditFamilyMembersAttributes):
     pass
 
 
+class LabelsEditRequest(DyffRequestBase, commands.EditEntityLabelsAttributes):
+    pass
+
+
+class LabelUpdateRequest(LabelsEditRequest):
+    """Deprecated alias for LabelsEditRequest.
+
+    .. deprecated:: 0.26.0
+
+        Use LabelsEditRequest
+    """
+
+
+# ----------------------------------------------------------------------------
+
+
 # Note: Query requests, as they currently exist, don't work with Versioned
 # because fastapi will assign None to every field that the client doesn't
 # specify. I think it's not that important, because all of the query parameters
@@ -418,6 +433,7 @@ __all__ = [
     "InferenceSessionQueryRequest",
     "InferenceSessionTokenCreateRequest",
     "LabelUpdateRequest",
+    "LabelsEditRequest",
     "MeasurementQueryRequest",
     "MethodCreateRequest",
     "MethodQueryRequest",

{dyff_schema-0.25.1 → dyff_schema-0.26.1/dyff_schema.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: dyff-schema
-Version: 0.25.1
+Version: 0.26.1
 Summary: Data models for the Dyff AI auditing platform.
 Author-email: Digital Safety Research Institute <contact@dsri.org>
 License: Apache-2.0