♻️ add traits and docstrings

sync traits declared in #909

client/ayon_core/pipeline/traits/__init__.py

@@ -1,15 +1,26 @@
 """Trait classes for the pipeline."""
+from .color import ColorManaged
 from .content import (
     Bundle,
     Compressed,
     FileLocation,
+    Fragment,
+    LocatableContent,
     MimeType,
     RootlessLocation,
 )
+from .cryptography import DigitallySigned, GPGSigned
 from .lifecycle import Persistent, Transient
 from .meta import Tagged, TemplatePath
-from .three_dimensional import Spatial
-from .time import Clip, GapPolicy, Sequence, SMPTETimecode
+from .three_dimensional import Geometry, IESProfile, Lighting, Shader, Spatial
+from .time import (
+    FrameRanged,
+    GapPolicy,
+    Handles,
+    Sequence,
+    SMPTETimecode,
+    Static,
+)
 from .trait import Representation, TraitBase
 from .two_dimensional import (
     UDIM,
@@ -31,6 +42,15 @@
     "FileLocation",
     "MimeType",
     "RootlessLocation",
+    "Fragment",
+    "LocatableContent",
+
+    # color
+    "ColorManaged",
+
+    # cryptography
+    "DigitallySigned",
+    "GPGSigned",
 
     # life cycle
     "Persistent",
@@ -50,10 +70,16 @@
     "UDIM",
 
     # three-dimensional
+    "Geometry",
+    "IESProfile",
+    "Lighting",
+    "Shader",
     "Spatial",
 
     # time
-    "Clip",
+    "FrameRanged",
+    "Static",
+    "Handles",
     "GapPolicy",
     "Sequence",
     "SMPTETimecode",

client/ayon_core/pipeline/traits/color.py

@@ -0,0 +1,31 @@
+"""Color management related traits."""
+from __future__ import annotations
+
+from typing import ClassVar, Optional
+
+from pydantic import Field
+
+from .trait import TraitBase
+
+
+class ColorManaged(TraitBase):
+    """Color managed trait.
+
+    Holds color management information. Can be used with Image related
+    traits to define color space and config.
+
+    Sync with OpenAssetIO MediaCreation Traits.
+
+    Attributes:
+        color_space (str): An OCIO colorspace name available
+            in the "current" OCIO context.
+        config (str): An OCIO config name defining color space.
+    """
+    id: ClassVar[str] = "ayon.color.ColorManaged.v1"
+    name: ClassVar[str] = "ColorManaged"
+    description: ClassVar[str] = "Color Managed trait."
+    color_space: str = Field(
+        ...,
+        description="Color space."
+    )
+    config: Optional[str] = Field(None, description="Color config.")

client/ayon_core/pipeline/traits/content.py

@@ -13,13 +13,17 @@
 class MimeType(TraitBase):
     """MimeType trait model.
 
-    This model represents a mime type trait.
+    This model represents a mime type trait. For example, image/jpeg.
+    It is used to describe the type of content in a representation regardless
+    of the file extension.
+
+    For more information, see RFC 2046 and RFC 4288 (and related RFCs).
 
     Attributes:
         name (str): Trait name.
         description (str): Trait description.
         id (str): id should be namespaced trait name with version
-        mime_type (str): Mime type.
+        mime_type (str): Mime type like image/jpeg.
 
     """
 
@@ -28,10 +32,35 @@ class MimeType(TraitBase):
     id: ClassVar[str] = "ayon.content.MimeType.v1"
     mime_type: str = Field(..., title="Mime Type")
 
-class FileLocation(TraitBase):
+class LocatableContent(TraitBase):
+    """LocatableContent trait model.
+
+    This model represents a locatable content trait. Locatable content
+    is content that has a location. It doesn't have to be a file - it could
+    be a URL or some other location.
+
+    Sync with OpenAssetIO MediaCreation Traits.
+
+    Attributes:
+        name (str): Trait name.
+        description (str): Trait description.
+        id (str): id should be namespaced trait name with version
+        location (str): Location.
+
+    """
+
+    name: ClassVar[str] = "LocatableContent"
+    description: ClassVar[str] = "LocatableContent Trait Model"
+    id: ClassVar[str] = "ayon.content.LocatableContent.v1"
+    location: str = Field(..., title="Location")
+    is_templated: Optional[bool] = Field(None, title="Is Templated")
+
+class FileLocation(LocatableContent):
     """FileLocation trait model.
 
-    This model represents a file location trait.
+    This model represents a file path. It is a specialization of the
+    LocatableContent trait. It is adding optional file size and file hash
+    for easy access to file information.
 
     Attributes:
         name (str): Trait name.
@@ -46,14 +75,22 @@ class FileLocation(TraitBase):
     name: ClassVar[str] = "FileLocation"
     description: ClassVar[str] = "FileLocation Trait Model"
     id: ClassVar[str] = "ayon.content.FileLocation.v1"
-    file_path: Path = Field(..., title="File Path")
-    file_size: int = Field(..., title="File Size")
+    file_path: Path = Field(..., title="File Path", alias="location")
+    file_size: int = Field(None, title="File Size")
     file_hash: Optional[str] = Field(None, title="File Hash")
 
 class RootlessLocation(TraitBase):
     """RootlessLocation trait model.
 
-    This model represents a rootless location trait.
+    RootlessLocation trait is a trait that represents a file path that is
+    without specific root. To obtain absolute path, the root needs to be
+    resolved by AYON. Rootless path can be used on multiple platforms.
+
+    Example::
+
+        RootlessLocation(
+            rootless_path="{root[work]}/project/asset/asset.jpg"
+        )
 
     Attributes:
         name (str): Trait name.
@@ -72,7 +109,12 @@ class RootlessLocation(TraitBase):
 class Compressed(TraitBase):
     """Compressed trait model.
 
-    This model represents a compressed trait.
+    This trait can hold information about compressed content. What type
+    of compression is used.
+
+    Example::
+
+        Compressed("gzip")
 
     Attributes:
         name (str): Trait name.
@@ -96,6 +138,29 @@ class Bundle(TraitBase):
     a collection of representations that are part of a single
     entity.
 
+    Example::
+
+            Bundle(
+                items=[
+                    [
+                        Representation(
+                            traits=[
+                                MimeType(mime_type="image/jpeg"),
+                                FileLocation(file_path="/path/to/file.jpg")
+                            ]
+                        )
+                    ],
+                    [
+                        Representation(
+                            traits=[
+                                MimeType(mime_type="image/png"),
+                                FileLocation(file_path="/path/to/file.png")
+                            ]
+                        )
+                    ]
+                ]
+            )
+
     Attributes:
         name (str): Trait name.
         description (str): Trait description.
@@ -119,7 +184,19 @@ class Fragment(TraitBase):
     """Fragment trait model.
 
     This model represents a fragment trait. A fragment is a part of
-    a larger entity that is represented by a representation.
+    a larger entity that is represented by another representation.
+
+    Example::
+
+        main_representation = Representation(name="parent",
+            traits=[],
+        )
+        fragment_representation = Representation(
+            name="fragment",
+            traits=[
+                Fragment(parent=main_representation.id),
+            ]
+        )
 
     Attributes:
         name (str): Trait name.

client/ayon_core/pipeline/traits/cryptography.py

@@ -0,0 +1,42 @@
+"""Cryptography traits."""
+from __future__ import annotations
+
+from typing import ClassVar, Optional
+
+from pydantic import Field
+
+from .trait import TraitBase
+
+
+class DigitallySigned(TraitBase):
+    """Digitally signed trait.
+
+    This type trait means that the data is digitally signed.
+
+    Attributes:
+        signature (str): Digital signature.
+    """
+    id: ClassVar[str] = "ayon.cryptography.DigitallySigned.v1"
+    name: ClassVar[str] = "DigitallySigned"
+    description: ClassVar[str] = "Digitally signed trait."
+
+
+class GPGSigned(DigitallySigned):
+    """GPG signed trait.
+
+    This trait holds GPG signed data.
+
+    Attributes:
+        signature (str): GPG signature.
+    """
+    id: ClassVar[str] = "ayon.cryptography.GPGSigned.v1"
+    name: ClassVar[str] = "GPGSigned"
+    description: ClassVar[str] = "GPG signed trait."
+    signed_data: str = Field(
+        ...,
+        description="Signed data."
+    )
+    clear_text: Optional[str] = Field(
+        None,
+        description="Clear text."
+    )

client/ayon_core/pipeline/traits/lifecycle.py

@@ -1,30 +1,44 @@
 """Lifecycle traits."""
 from typing import ClassVar
 
+from . import Representation
 from .trait import TraitBase
 
 
 class Transient(TraitBase):
     """Transient trait model.
 
-    This model represents a transient trait.
+    Transient trait marks representation as transient. Such representations
+    are not persisted in the system.
 
     Attributes:
         name (str): Trait name.
         description (str): Trait description.
         id (str): id should be namespaced trait name with version
-        tags (List[str]): Tags.
     """
 
     name: ClassVar[str] = "Transient"
     description: ClassVar[str] = "Transient Trait Model"
     id: ClassVar[str] = "ayon.lifecycle.Transient.v1"
 
+    def validate(self, representation: Representation) -> bool:
+        """Validate representation is not Persistent.
+
+        Args:
+            representation (Representation): Representation model.
+
+        Returns:
+            bool: True if representation is valid, False otherwise.
+        """
+        return not representation.contains_trait(Persistent)
+
 
 class Persistent(TraitBase):
     """Persistent trait model.
 
-    This model represents a persistent trait.
+    Persistent trait is opposite to transient trait. It marks representation
+    as persistent. Such representations are persisted in the system (e.g. in
+    the database).
 
     Attributes:
         name (str): Trait name.
@@ -35,3 +49,14 @@ class Persistent(TraitBase):
     name: ClassVar[str] = "Persistent"
     description: ClassVar[str] = "Persistent Trait Model"
     id: ClassVar[str] = "ayon.lifecycle.Persistent.v1"
+
+    def validate(self, representation: Representation) -> bool:
+        """Validate representation is not Transient.
+
+        Args:
+            representation (Representation): Representation model.
+
+        Returns:
+            bool: True if representation is valid, False otherwise.
+        """
+        return not representation.contains_trait(Transient)

client/ayon_core/pipeline/traits/meta.py

@@ -9,7 +9,11 @@
 class Tagged(TraitBase):
     """Tagged trait model.
 
-    This model represents a tagged trait.
+    This trait can hold list of tags.
+
+    Example::
+
+        Tagged(tags=["tag1", "tag2"])
 
     Attributes:
         name (str): Trait name.
@@ -28,12 +32,17 @@ class TemplatePath(TraitBase):
     """TemplatePath trait model.
 
     This model represents a template path with formatting data.
+    Template path can be Anatomy template and data is used to format it.
+
+    Example::
+
+        TemplatePath(template="path/{key}/file", data={"key": "to"})
 
     Attributes:
         name (str): Trait name.
         description (str): Trait description.
         id (str): id should be namespaced trait name with version
-        template_path (str): Template path.
+        template (str): Template path.
         data (dict[str]): Formatting data.
     """