traits

@dataclass
class Bundle(TraitBase):
    """Bundle trait model.

    This model list of independent Representation traits
    that are bundled together. This is useful for representing
    a collection of sub-entities that are part of a single
    entity. You can easily reconstruct representations from
    the bundle.

    Example::

            Bundle(
                items=[
                    [
                        MimeType(mime_type="image/jpeg"),
                        FileLocation(file_path="/path/to/file.jpg")
                    ],
                    [

                        MimeType(mime_type="image/png"),
                        FileLocation(file_path="/path/to/file.png")
                    ]
                ]
            )

    Attributes:
        name (str): Trait name.
        description (str): Trait description.
        id (str): id should be a namespaced trait name with version
        items (list[list[TraitBase]]): List of representations.
    """

    name: ClassVar[str] = "Bundle"
    description: ClassVar[str] = "Bundle Trait"
    id: ClassVar[str] = "ayon.content.Bundle.v1"
    persistent: ClassVar[bool] = True
    items: list[list[TraitBase]]

    def to_representations(self) -> Generator[Representation]:
        """Convert a bundle to representations.

        Yields:
            Representation: Representation of the bundle.

        """
        for idx, item in enumerate(self.items):
            yield Representation(name=f"{self.name} {idx}", traits=item)

@dataclass
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"
    color_space: str
    description: ClassVar[str] = "Color Managed trait."
    persistent: ClassVar[bool] = True
    config: Optional[str] = None

@dataclass
class Compressed(TraitBase):
    """Compressed trait model.

    This trait can hold information about compressed content. What type
    of compression is used.

    Example::

        Compressed("gzip")

    Attributes:
        name (str): Trait name.
        description (str): Trait description.
        id (str): id should be a namespaced trait name with version
        compression_type (str): Compression type.
    """

    name: ClassVar[str] = "Compressed"
    description: ClassVar[str] = "Compressed Trait"
    id: ClassVar[str] = "ayon.content.Compressed.v1"
    persistent: ClassVar[bool] = True
    compression_type: str

@dataclass
class Deep(TraitBase):
    """Deep trait model.

    Type trait model for deep EXR images.

    Attributes:
        name (str): Trait name.
        description (str): Trait description.
        id (str): id should be a namespaced trait name with a version
    """

    name: ClassVar[str] = "Deep"
    description: ClassVar[str] = "Deep Trait Model"
    id: ClassVar[str] = "ayon.2d.Deep.v1"
    persistent: ClassVar[bool] = True

@dataclass
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."
    persistent: ClassVar[bool] = True

@dataclass
class FileLocation(TraitBase):
    """FileLocation trait model.

    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.
        description (str): Trait description.
        id (str): id should be a namespaced trait name with version
        file_path (str): File path.
        file_size (Optional[int]): File size in bytes.
        file_hash (Optional[str]): File hash.
    """

    name: ClassVar[str] = "FileLocation"
    description: ClassVar[str] = "FileLocation Trait Model"
    id: ClassVar[str] = "ayon.content.FileLocation.v1"
    persistent: ClassVar[bool] = True
    file_path: Path
    file_size: Optional[int] = None
    file_hash: Optional[str] = None

@dataclass
class FileLocations(TraitBase):
    """FileLocation trait model.

    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.
        description (str): Trait description.
        id (str): id should be a namespaced trait name with version
        file_paths (list of FileLocation): File locations.

    """

    name: ClassVar[str] = "FileLocations"
    description: ClassVar[str] = "FileLocations Trait Model"
    id: ClassVar[str] = "ayon.content.FileLocations.v1"
    persistent: ClassVar[bool] = True
    file_paths: list[FileLocation]

    def get_files(self) -> Generator[Path, None, None]:
        """Get all file paths from the trait.

        This method will return all file paths from the trait.

        Yields:
            Path: List of file paths.

        """
        for file_location in self.file_paths:
            yield file_location.file_path

    def get_file_location_for_frame(
            self,
            frame: int,
            sequence_trait: Optional[Sequence] = None,
        ) -> Optional[FileLocation]:
        """Get a file location for a frame.

        This method will return the file location for a given frame. If the
        frame is not found in the file paths, it will return None.

        Args:
            frame (int): Frame to get the file location for.
            sequence_trait (Sequence): Sequence trait to get the
                frame range specs from.

        Returns:
            Optional[FileLocation]: File location for the frame.

        """
        frame_regex = re.compile(r"\.(?P<index>(?P<padding>0*)\d+)\.\D+\d?$")
        if sequence_trait and sequence_trait.frame_regex:
            frame_regex = sequence_trait.get_frame_pattern()

        for location in self.file_paths:
            result = re.search(frame_regex, location.file_path.name)
            if result:
                frame_index = int(result.group("index"))
                if frame_index == frame:
                    return location
        return None

    def validate_trait(self, representation: Representation) -> None:
        """Validate the trait.

        This method validates the trait against others in the representation.
        In particular, it checks that the sequence trait is present, and if
        so, it will compare the frame range to the file paths.

        Args:
            representation (Representation): Representation to validate.

        Raises:
            TraitValidationError: If the trait is invalid within the
                representation.

        """
        super().validate_trait(representation)
        if len(self.file_paths) == 0:
            # If there are no file paths, we can't validate
            msg = "No file locations defined (empty list)"
            raise TraitValidationError(self.name, msg)
        if representation.contains_trait(FrameRanged):
            self._validate_frame_range(representation)
        if not representation.contains_trait(Sequence) \
                and not representation.contains_trait(UDIM):
            # we have multiple files, but it is not a sequence
            # or UDIM tile set what is it then? If the files are not related
            # to each other, then this representation is invalid.
            msg = (
                 "Multiple file locations defined, but no Sequence "
                 "or UDIM trait defined. If the files are not related to "
                 "each other, the representation is invalid."
            )
            raise TraitValidationError(self.name, msg)

    def _validate_frame_range(self, representation: Representation) -> None:
        """Validate the frame range against the file paths.

        If the representation contains a FrameRanged trait, this method will
        validate the frame range against the file paths. If the frame range
        does not match the file paths, the trait is invalid. It takes into
        account the Handles and Sequence traits.

        Args:
            representation (Representation): Representation to validate.

        Raises:
            TraitValidationError: If the trait is invalid within the
                representation.

        """
        tmp_frame_ranged: FrameRanged = get_sequence_from_files(
                    [f.file_path for f in self.file_paths])

        frames_from_spec: list[int] = []
        with contextlib.suppress(MissingTraitError):
            sequence: Sequence = representation.get_trait(Sequence)
            frame_regex = sequence.get_frame_pattern()
            if sequence.frame_spec:
                frames_from_spec = sequence.get_frame_list(
                    self, frame_regex)

        frame_start_with_handles, frame_end_with_handles = \
            self._get_frame_info_with_handles(representation, frames_from_spec)

        if frame_start_with_handles \
                and tmp_frame_ranged.frame_start != frame_start_with_handles:
            # If the detected frame range does not match the combined
            # FrameRanged and Handles trait, the
            # trait is invalid.
            msg = (
                f"Frame range defined by {self.name} "
                f"({tmp_frame_ranged.frame_start}-"
                f"{tmp_frame_ranged.frame_end}) "
                "in files does not match "
                "frame range "
                f"({frame_start_with_handles}-"
                f"{frame_end_with_handles}) defined in FrameRanged trait."
            )

            raise TraitValidationError(self.name, msg)

        if frames_from_spec:
            if len(frames_from_spec) != len(self.file_paths):
                # If the number of file paths does not match the frame range,
                # the trait is invalid
                msg = (
                    f"Number of file locations ({len(self.file_paths)}) "
                    "does not match frame range defined by frame spec "
                    "on Sequence trait: "
                    f"({len(frames_from_spec)})"
                )
                raise TraitValidationError(self.name, msg)
            # if there is a frame spec on the Sequence trait,
            # we should not validate the frame range from the files.
            # the rest is validated by Sequence validators.
            return

        length_with_handles: int = (
            frame_end_with_handles - frame_start_with_handles + 1
        )

        if len(self.file_paths) != length_with_handles:
            # If the number of file paths does not match the frame range,
            # the trait is invalid
            msg = (
                f"Number of file locations ({len(self.file_paths)}) "
                "does not match frame range "
                f"({length_with_handles})"
            )
            raise TraitValidationError(self.name, msg)

        frame_ranged: FrameRanged = representation.get_trait(FrameRanged)

        if frame_start_with_handles != tmp_frame_ranged.frame_start or \
                frame_end_with_handles != tmp_frame_ranged.frame_end:
            # If the frame range does not match the FrameRanged trait, the
            # trait is invalid. Note that we don't check the frame rate
            # because it is not stored in the file paths and is not
            # determined by `get_sequence_from_files`.
            msg = (
                "Frame range "
                f"({frame_ranged.frame_start}-{frame_ranged.frame_end}) "
                "in sequence trait does not match "
                "frame range "
                f"({tmp_frame_ranged.frame_start}-"
                f"{tmp_frame_ranged.frame_end}) "
            )
            raise TraitValidationError(self.name, msg)

    @staticmethod
    def _get_frame_info_with_handles(
            representation: Representation,
            frames_from_spec: list[int]) -> tuple[int, int]:
        """Get the frame range with handles from the representation.

        This will return frame start and frame end with handles calculated
        in if there actually is the Handles trait in the representation.

        Args:
            representation (Representation): Representation to get the frame
                range from.
            frames_from_spec (list[int]): List of frames from the frame spec.
                This list is modified in place to take into
                account the handles.

        Mutates:
            frames_from_spec: List of frames from the frame spec.

        Returns:
            tuple[int, int]: Start and end frame with handles.

        """
        frame_start = frame_end = 0
        frame_start_handle = frame_end_handle = 0
        # If there is no sequence trait, we can't validate it
        if frames_from_spec and representation.contains_trait(FrameRanged):
            # if there is no FrameRanged trait (but really there should be)
            # we can use the frame range from the frame spec
            frame_start = min(frames_from_spec)
            frame_end = max(frames_from_spec)

        # Handle the frame range
        with contextlib.suppress(MissingTraitError):
            frame_start = representation.get_trait(FrameRanged).frame_start
            frame_end = representation.get_trait(FrameRanged).frame_end

        # Handle the handles :P
        with contextlib.suppress(MissingTraitError):
            handles: Handles = representation.get_trait(Handles)
            if not handles.inclusive:
                # if handless are exclusive, we need to adjust the frame range
                frame_start_handle = handles.frame_start_handle or 0
                frame_end_handle = handles.frame_end_handle or 0
                if frames_from_spec:
                    frames_from_spec.extend(
                        range(frame_start - frame_start_handle, frame_start)
                    )
                    frames_from_spec.extend(
                        range(frame_end + 1, frame_end_handle + frame_end + 1)
                    )

        frame_start_with_handles = frame_start - frame_start_handle
        frame_end_with_handles = frame_end + frame_end_handle

        return frame_start_with_handles, frame_end_with_handles

@dataclass
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 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.
        description (str): Trait description.
        id (str): id should be namespaced trait name with version
        parent (str): Parent representation id.
    """

    name: ClassVar[str] = "Fragment"
    description: ClassVar[str] = "Fragment Trait"
    id: ClassVar[str] = "ayon.content.Fragment.v1"
    persistent: ClassVar[bool] = True
    parent: str

@dataclass
class FrameRanged(TraitBase):
    """Frame ranged trait model.

    Model representing a frame-ranged trait.

    Sync with OpenAssetIO MediaCreation Traits. For compatibility with
    OpenAssetIO, we'll need to handle different names of attributes:

        * frame_start -> start_frame
        * frame_end -> end_frame
        ...

    Note: frames_per_second is a string to allow various precision
        formats. FPS is a floating point number, but it can be also
        represented as a fraction (e.g. "30000/1001") or as a decimal
        or even as an irrational number. We need to support all these
        formats. To work with FPS, we'll need some helper function
        to convert FPS to Decimal from string.

    Attributes:
        name (str): Trait name.
        description (str): Trait description.
        id (str): id should be a namespaced trait name with a version
        frame_start (int): Frame start.
        frame_end (int): Frame end.
        frame_in (int): Frame in.
        frame_out (int): Frame out.
        frames_per_second (str): Frames per second.
        step (int): Step.
    """

    name: ClassVar[str] = "FrameRanged"
    description: ClassVar[str] = "Frame Ranged Trait"
    id: ClassVar[str] = "ayon.time.FrameRanged.v1"
    persistent: ClassVar[bool] = True
    frame_start: int
    frame_end: int
    frame_in: Optional[int] = None
    frame_out: Optional[int] = None
    frames_per_second: str = None
    step: Optional[int] = None

class GapPolicy(Enum):
    """Gap policy enumeration.

    This type defines how to handle gaps in a sequence.

    Attributes:
        forbidden (int): Gaps are forbidden.
        missing (int): Gaps are interpreted as missing frames.
        hold (int): Gaps are interpreted as hold frames (last existing frames).
        black (int): Gaps are interpreted as black frames.
    """

    forbidden = auto()
    missing = auto()
    hold = auto()
    black = auto()

@dataclass
class Geometry(TraitBase):
    """Geometry type trait model.

    Type trait for geometry data.

    Sync with OpenAssetIO MediaCreation Traits.
    """

    id: ClassVar[str] = "ayon.3d.Geometry.v1"
    name: ClassVar[str] = "Geometry"
    description: ClassVar[str] = "Geometry trait model."
    persistent: ClassVar[bool] = True

@dataclass
class Handles(TraitBase):
    """Handles trait model.

    Handles define the range of frames that are included or excluded
    from the sequence.

    Attributes:
        name (str): Trait name.
        description (str): Trait description.
        id (str): id should be a namespaced trait name with a version
        inclusive (bool): Handles are inclusive.
        frame_start_handle (int): Frame start handle.
        frame_end_handle (int): Frame end handle.
    """

    name: ClassVar[str] = "Handles"
    description: ClassVar[str] = "Handles Trait"
    id: ClassVar[str] = "ayon.time.Handles.v1"
    persistent: ClassVar[bool] = True
    inclusive: Optional[bool] = False
    frame_start_handle: Optional[int] = None
    frame_end_handle: Optional[int] = None

@dataclass
class IESProfile(TraitBase):
    """IES profile (IES-LM-64) type trait model.

    Sync with OpenAssetIO MediaCreation Traits.
    """

    id: ClassVar[str] = "ayon.3d.IESProfile.v1"
    name: ClassVar[str] = "IESProfile"
    description: ClassVar[str] = "IES profile trait model."
    persistent: ClassVar[bool] = True

@dataclass
class Image(TraitBase):
    """Image trait model.

    Type trait model for image.

    Attributes:
        name (str): Trait name.
        description (str): Trait description.
        id (str): id should be a namespaced trait name with version
    """

    name: ClassVar[str] = "Image"
    description: ClassVar[str] = "Image Trait"
    id: ClassVar[str] = "ayon.2d.Image.v1"
    persistent: ClassVar[bool] = True

@dataclass
class IntendedUse(TraitBase):
    """Intended use of the representation.

    This trait describes the intended use of the representation. It
    can be used in cases where the other traits are not enough to
    describe the intended use. For example, a txt file with tracking
    points can be used as a corner pin in After Effect but not in Nuke.

    Attributes:
        use (str): Intended use description.

    """
    name: ClassVar[str] = "IntendedUse"
    description: ClassVar[str] = "Intended Use Trait Model"
    id: ClassVar[str] = "ayon.meta.IntendedUse.v1"
    persistent: ClassVar[bool] = True
    use: str

@dataclass
class KeepOriginalLocation(TraitBase):
    """Keep files in its original location.

    Note:
        This is not a persistent trait.

    """
    name: ClassVar[str] = "KeepOriginalLocation"
    description: ClassVar[str] = "Keep Original Location Trait Model"
    id: ClassVar[str] = "ayon.meta.KeepOriginalLocation.v1"
    persistent: ClassVar[bool] = False

@dataclass
class Lighting(TraitBase):
    """Lighting trait model.

    Type trait for lighting data.

    Sync with OpenAssetIO MediaCreation Traits.
    """

    id: ClassVar[str] = "ayon.3d.Lighting.v1"
    name: ClassVar[str] = "Lighting"
    description: ClassVar[str] = "Lighting trait model."
    persistent: ClassVar[bool] = True

@dataclass
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 a namespaced trait name with version
        location (str): Location.
        is_templated (Optional[bool]): Is the location templated?
            Default is None.
    """

    name: ClassVar[str] = "LocatableContent"
    description: ClassVar[str] = "LocatableContent Trait Model"
    id: ClassVar[str] = "ayon.content.LocatableContent.v1"
    persistent: ClassVar[bool] = True
    location: str
    is_templated: Optional[bool] = None

@dataclass
class MimeType(TraitBase):
    """MimeType trait model.

    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 a namespaced trait name with version
        mime_type (str): Mime type like image/jpeg.
    """

    name: ClassVar[str] = "MimeType"
    description: ClassVar[str] = "MimeType Trait Model"
    id: ClassVar[str] = "ayon.content.MimeType.v1"
    persistent: ClassVar[bool] = True
    mime_type: str

class MissingTraitError(TypeError):
    """Missing trait error exception.

    This exception is raised when the trait is missing.
    """

@dataclass
class Overscan(TraitBase):
    """Overscan trait model.

    This model represents an overscan (or underscan) trait. Defines the
    extra pixels around the image.

    Attributes:
        name (str): Trait name.
        description (str): Trait description.
        id (str): id should be a namespaced trait name with a version
        left (int): Left overscan/underscan.
        right (int): Right overscan/underscan.
        top (int): Top overscan/underscan.
        bottom (int): Bottom overscan/underscan.
    """

    name: ClassVar[str] = "Overscan"
    description: ClassVar[str] = "Overscan Trait"
    id: ClassVar[str] = "ayon.2d.Overscan.v1"
    persistent: ClassVar[bool] = True
    left: int
    right: int
    top: int
    bottom: int

@dataclass
class PGPSigned(DigitallySigned):
    """PGP signed trait.

    This trait holds PGP (RFC-4880) signed data.

    Attributes:
        signed_data (str): Signed data.
        clear_text (str): Clear text.
    """

    id: ClassVar[str] = "ayon.cryptography.PGPSigned.v1"
    name: ClassVar[str] = "PGPSigned"
    description: ClassVar[str] = "PGP signed trait."
    persistent: ClassVar[bool] = True
    signed_data: str
    clear_text: Optional[str] = None

@dataclass
class Persistent(TraitBase):
    """Persistent trait model.

    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.
        description (str): Trait description.
        id (str): id should be a namespaced trait name with the version
    """

    name: ClassVar[str] = "Persistent"
    description: ClassVar[str] = "Persistent Trait Model"
    id: ClassVar[str] = "ayon.lifecycle.Persistent.v1"
    # Note that this affects the persistence of the trait itself, not
    # the representation. This is a class variable, so it is shared
    # among all instances of the class.
    persistent: bool = True

    def validate_trait(self, representation) -> None:  # noqa: ANN001
        """Validate representation is not Transient.

        Args:
            representation (Representation): Representation model.

        Raises:
            TraitValidationError: If representation is marked
                as both Persistent and Transient.

        """
        if representation.contains_trait(Transient):
            msg = "Representation is marked as both Persistent and Transient."
            raise TraitValidationError(self.name, msg)

@dataclass
class PixelBased(TraitBase):
    """PixelBased trait model.

    The pixel-related trait for image data.

    Attributes:
        name (str): Trait name.
        description (str): Trait description.
        id (str): id should be a namespaced trait name with a version
        display_window_width (int): Width of the image display window.
        display_window_height (int): Height of the image display window.
        pixel_aspect_ratio (float): Pixel aspect ratio.
    """

    name: ClassVar[str] = "PixelBased"
    description: ClassVar[str] = "PixelBased Trait Model"
    id: ClassVar[str] = "ayon.2d.PixelBased.v1"
    persistent: ClassVar[bool] = True
    display_window_width: int
    display_window_height: int
    pixel_aspect_ratio: float

@dataclass
class Planar(TraitBase):
    """Planar trait model.

    This model represents an Image with planar configuration.

    Todo:
        * (antirotor): Is this really a planar configuration? As with
            bit planes and everything? If it serves as differentiator for
            Deep images, should it be named differently? Like Raster?

    Attributes:
        name (str): Trait name.
        description (str): Trait description.
        id (str): id should be namespaced trait name with version
        planar_configuration (str): Planar configuration.
    """

    name: ClassVar[str] = "Planar"
    description: ClassVar[str] = "Planar Trait Model"
    id: ClassVar[str] = "ayon.2d.Planar.v1"
    persistent: ClassVar[bool] = True
    planar_configuration: str

class Representation(Generic[T]):  # noqa: PLR0904
    """Representation of products.

    Representation defines a collection of individual properties that describe
    the specific "form" of the product. A trait represents a set of
    properties therefore, the Representation is a collection of traits.

    It holds methods to add, remove, get, and check for the existence of a
    trait in the representation.

    Note:
        `PLR0904` is the rule for checking the number of public methods
        in a class.

    Arguments:
        name (str): Representation name. Must be unique within instance.
        representation_id (str): Representation ID.
    """

    _data: dict[str, T]
    _module_blacklist: ClassVar[list[str]] = [
        "_", "builtins", "pydantic",
    ]
    name: str
    representation_id: str

    def __hash__(self):
        """Return hash of the representation ID."""
        return hash(self.representation_id)

    def __getitem__(self, key: str) -> T:
        """Get the trait by ID.

        Args:
            key (str): Trait ID.

        Returns:
            TraitBase: Trait instance.

        """
        return self.get_trait_by_id(key)

    def __setitem__(self, key: str, value: T) -> None:
        """Set the trait by ID.

        Args:
            key (str): Trait ID.
            value (TraitBase): Trait instance.

        """
        with contextlib.suppress(KeyError):
            self._data.pop(key)

        self.add_trait(value)

    def __delitem__(self, key: str) -> None:
        """Remove the trait by ID.

        Args:
            key (str): Trait ID.


        """
        self.remove_trait_by_id(key)

    def __contains__(self, key: str) -> bool:
        """Check if the trait exists by ID.

        Args:
            key (str): Trait ID.

        Returns:
            bool: True if the trait exists, False otherwise.

        """
        return self.contains_trait_by_id(key)

    def __iter__(self):
        """Return the trait ID iterator."""
        return iter(self._data)

    def __str__(self):
        """Return the representation name."""
        return self.name

    def items(self) -> ItemsView[str, T]:
        """Return the traits as items."""
        return ItemsView(self._data)

    def add_trait(self, trait: T, *, exists_ok: bool = False) -> None:
        """Add a trait to the Representation.

        Args:
            trait (TraitBase): Trait to add.
            exists_ok (bool, optional): If True, do not raise an error if the
                trait already exists. Defaults to False.

        Raises:
            ValueError: If the trait ID is not provided, or the trait already
                exists.

        """
        if not hasattr(trait, "id"):
            error_msg = f"Invalid trait {trait} - ID is required."
            raise ValueError(error_msg)
        if trait.id in self._data and not exists_ok:
            error_msg = f"Trait with ID {trait.id} already exists."
            raise ValueError(error_msg)
        self._data[trait.id] = trait

    def add_traits(
            self, traits: list[T], *, exists_ok: bool = False) -> None:
        """Add a list of traits to the Representation.

        Args:
            traits (list[TraitBase]): List of traits to add.
            exists_ok (bool, optional): If True, do not raise an error if the
                trait already exists. Defaults to False.

        """
        for trait in traits:
            self.add_trait(trait, exists_ok=exists_ok)

    def remove_trait(self, trait: Type[TraitBase]) -> None:
        """Remove a trait from the data.

        Args:
            trait (TraitBase, optional): Trait class.

        Raises:
            ValueError: If the trait is not found.

        """
        try:
            self._data.pop(str(trait.id))
        except KeyError as e:
            error_msg = f"Trait with ID {trait.id} not found."
            raise ValueError(error_msg) from e

    def remove_trait_by_id(self, trait_id: str) -> None:
        """Remove a trait from the data by its ID.

        Args:
            trait_id (str): Trait ID.

        Raises:
            ValueError: If the trait is not found.

        """
        try:
            self._data.pop(trait_id)
        except KeyError as e:
            error_msg = f"Trait with ID {trait_id} not found."
            raise ValueError(error_msg) from e

    def remove_traits(self, traits: list[Type[T]]) -> None:
        """Remove a list of traits from the Representation.

        If no trait IDs or traits are provided, all traits will be removed.

        Args:
            traits (list[TraitBase]): List of trait classes.

        """
        if not traits:
            self._data = {}
            return

        for trait in traits:
            self.remove_trait(trait)

    def remove_traits_by_id(self, trait_ids: list[str]) -> None:
        """Remove a list of traits from the Representation by their ID.

        If no trait IDs or traits are provided, all traits will be removed.

        Args:
            trait_ids (list[str], optional): List of trait IDs.

        """
        for trait_id in trait_ids:
            self.remove_trait_by_id(trait_id)

    def has_traits(self) -> bool:
        """Check if the Representation has any traits.

        Returns:
            bool: True if the Representation has any traits, False otherwise.

        """
        return bool(self._data)

    def contains_trait(self, trait: Type[T]) -> bool:
        """Check if the trait exists in the Representation.

        Args:
            trait (TraitBase): Trait class.

        Returns:
            bool: True if the trait exists, False otherwise.

        """
        return bool(self._data.get(str(trait.id)))

    def contains_trait_by_id(self, trait_id: str) -> bool:
        """Check if the trait exists using trait id.

        Args:
            trait_id (str): Trait ID.

        Returns:
            bool: True if the trait exists, False otherwise.

        """
        return bool(self._data.get(trait_id))

    def contains_traits(self, traits: list[Type[T]]) -> bool:
        """Check if the traits exist.

        Args:
            traits (list[TraitBase], optional): List of trait classes.

        Returns:
            bool: True if all traits exist, False otherwise.

        """
        return all(self.contains_trait(trait=trait) for trait in traits)

    def contains_traits_by_id(self, trait_ids: list[str]) -> bool:
        """Check if the traits exist by id.

        If no trait IDs or traits are provided, it will check if the
        representation has any traits.

        Args:
            trait_ids (list[str]): List of trait IDs.

        Returns:
            bool: True if all traits exist, False otherwise.

        """
        return all(
            self.contains_trait_by_id(trait_id) for trait_id in trait_ids
        )

    def get_trait(self, trait: Type[T]) -> T:
        """Get a trait from the representation.

        Args:
            trait (TraitBase, optional): Trait class.

        Returns:
            TraitBase: Trait instance.

        Raises:
            MissingTraitError: If the trait is not found.

        """
        try:
            return self._data[str(trait.id)]
        except KeyError as e:
            msg = f"Trait with ID {trait.id} not found."
            raise MissingTraitError(msg) from e

    def get_trait_by_id(self, trait_id: str) -> T:
        # sourcery skip: use-named-expression
        """Get a trait from the representation by id.

        Args:
            trait_id (str): Trait ID.

        Returns:
            TraitBase: Trait instance.

        Raises:
            MissingTraitError: If the trait is not found.

        """
        version = _get_version_from_id(trait_id)
        if version:
            try:
                return self._data[trait_id]
            except KeyError as e:
                msg = f"Trait with ID {trait_id} not found."
                raise MissingTraitError(msg) from e

        result = next(
            (
                self._data.get(trait_id)
                for trait_id in self._data
                if trait_id.startswith(trait_id)
            ),
            None,
        )
        if result is None:
            msg = f"Trait with ID {trait_id} not found."
            raise MissingTraitError(msg)
        return result

    def get_traits(self,
                     traits: Optional[list[Type[T]]] = None
     ) -> dict[str, T]:
        """Get a list of traits from the representation.

        If no trait IDs or traits are provided, all traits will be returned.

        Args:
            traits (list[TraitBase], optional): List of trait classes.

        Returns:
            dict: Dictionary of traits.

        """
        result: dict[str, T] = {}
        if not traits:
            for trait_id in self._data:
                result[trait_id] = self.get_trait_by_id(trait_id=trait_id)
            return result

        for trait in traits:
            result[str(trait.id)] = self.get_trait(trait=trait)
        return result

    def get_traits_by_ids(self, trait_ids: list[str]) -> dict[str, T]:
        """Get a list of traits from the representation by their id.

        If no trait IDs or traits are provided, all traits will be returned.

        Args:
            trait_ids (list[str]): List of trait IDs.

        Returns:
            dict: Dictionary of traits.

        """
        return {
            trait_id: self.get_trait_by_id(trait_id)
            for trait_id in trait_ids
        }

    def traits_as_dict(self) -> dict:
        """Return the traits from Representation data as a dictionary.

        Returns:
            dict: Traits data dictionary.

        """
        return {
            trait_id: trait.as_dict()
            for trait_id, trait in self._data.items()
            if trait and trait_id
        }

    def __len__(self):
        """Return the length of the data."""
        return len(self._data)

    def __init__(
            self,
            name: str,
            representation_id: Optional[str] = None,
            traits: Optional[list[T]] = None):
        """Initialize the data.

        Args:
            name (str): Representation name. Must be unique within instance.
            representation_id (str, optional): Representation ID.
            traits (list[TraitBase], optional): List of traits.

        """
        self.name = name
        self.representation_id = representation_id or uuid.uuid4().hex
        self._data = {}
        if traits:
            for trait in traits:
                self.add_trait(trait)

    @staticmethod
    def _get_version_from_id(trait_id: str) -> Union[int, None]:
        # sourcery skip: use-named-expression
        """Check if the trait has a version specified.

        Args:
            trait_id (str): Trait ID.

        Returns:
            int: Trait version.
            None: If the trait id does not have a version.

        """
        version_regex = r"v(\d+)$"
        match = re.search(version_regex, trait_id)
        return int(match[1]) if match else None

    def __eq__(self, other: object) -> bool:  # noqa: PLR0911
        """Check if the representation is equal to another.

        Args:
            other (Representation): Representation to compare.

        Returns:
            bool: True if the representations are equal, False otherwise.

        """
        if not isinstance(other, Representation):
            return False

        if self.representation_id != other.representation_id:
            return False

        if self.name != other.name:
            return False

        # number of traits
        if len(self) != len(other):
            return False

        for trait_id, trait in self._data.items():
            if trait_id not in other._data:
                return False
            if trait != other._data[trait_id]:
                return False

        return True

    @classmethod
    @lru_cache(maxsize=64)
    def _get_possible_trait_classes_from_modules(
            cls,
            trait_id: str) -> set[type[T]]:
        """Get possible trait classes from modules.

        Args:
            trait_id (str): Trait ID.

        Returns:
            set[type[T]]: Set of trait classes.

        """
        modules = sys.modules.copy()
        filtered_modules = modules.copy()
        for module_name in modules:
            for bl_module in cls._module_blacklist:
                if module_name.startswith(bl_module):
                    filtered_modules.pop(module_name)

        trait_candidates = set()
        for module in filtered_modules.values():
            if not module:
                continue

            for attr_name in dir(module):
                klass = getattr(module, attr_name)
                if not inspect.isclass(klass):
                    continue
                # This needs to be done because of the bug? In
                # python ABCMeta, where ``issubclass`` is not working
                # if it hits the GenericAlias (that is in fact
                # tuple[int, int]). This is added to the scope by
                # the ``types`` module.
                if type(klass) is GenericAlias:
                    continue
                if issubclass(klass, TraitBase) \
                        and str(klass.id).startswith(trait_id):
                    trait_candidates.add(klass)
        # I
        return trait_candidates  # type: ignore[return-value]

    @classmethod
    @lru_cache(maxsize=64)
    def _get_trait_class(
            cls, trait_id: str) -> Union[Type[T], None]:
        """Get the trait class with corresponding to given ID.

        This method will search for the trait class in all the modules except
        the blocklisted modules. There is some issue in Pydantic where
        ``issubclass`` is not working properly, so we are excluding explicit
        modules with offending classes. This list can be updated as needed to
        speed up the search.

        Args:
            trait_id (str): Trait ID.

        Returns:
            Type[TraitBase]: Trait class.

        """
        version = cls._get_version_from_id(trait_id)

        trait_candidates = cls._get_possible_trait_classes_from_modules(
            trait_id
        )
        if not trait_candidates:
            return None

        for trait_class in trait_candidates:
            if trait_class.id == trait_id:
                # we found a direct match
                return trait_class

        # if we didn't find direct match, we will search for the highest
        # version of the trait.
        if not version:
            # sourcery skip: use-named-expression
            trait_versions = [
                trait_class for trait_class in trait_candidates
                if re.match(
                    rf"{trait_id}.v(\d+)$", str(trait_class.id))
            ]
            if trait_versions:
                def _get_version_by_id(trait_klass: Type[T]) -> int:
                    match = re.search(r"v(\d+)$", str(trait_klass.id))
                    return int(match[1]) if match else 0

                error: LooseMatchingTraitError = LooseMatchingTraitError(
                    "Found trait that might match.")
                error.found_trait = max(
                    trait_versions, key=_get_version_by_id)
                error.expected_id = trait_id
                raise error

        return None

    @classmethod
    def get_trait_class_by_trait_id(cls, trait_id: str) -> Type[T]:
        """Get the trait class for the given trait ID.

        Args:
            trait_id (str): Trait ID.

        Returns:
            type[TraitBase]: Trait class.

        Raises:
            IncompatibleTraitVersionError: If the trait version is incompatible
                with the current version of the trait.

        """
        try:
            trait_class = cls._get_trait_class(trait_id=trait_id)
        except LooseMatchingTraitError as e:
            requested_version = _get_version_from_id(trait_id)
            found_version = _get_version_from_id(e.found_trait.id)
            if found_version is None and not requested_version:
                msg = (
                    "Trait found with no version and requested version "
                    "is not specified."
                )
                raise IncompatibleTraitVersionError(msg) from e

            if found_version is None:
                msg = (
                    f"Trait {e.found_trait.id} found with no version, "
                    "but requested version is specified."
                )
                raise IncompatibleTraitVersionError(msg) from e

            if requested_version is None:
                trait_class = e.found_trait
                requested_version = found_version

            if requested_version > found_version:
                error_msg = (
                    f"Requested trait version {requested_version} is "
                    f"higher than the found trait version {found_version}."
                )
                raise IncompatibleTraitVersionError(error_msg) from e

            if requested_version < found_version and hasattr(
                    e.found_trait, "upgrade"):
                error_msg = (
                    "Requested trait version "
                    f"{requested_version} is lower "
                    f"than the found trait version {found_version}."
                )
                error: UpgradableTraitError = UpgradableTraitError(error_msg)
                error.trait = e.found_trait
                raise error from e
        return trait_class  # type: ignore[return-value]

    @classmethod
    def from_dict(
            cls: Type[Representation],
            name: str,
            representation_id: Optional[str] = None,
            trait_data: Optional[dict] = None) -> Representation:
        """Create a representation from a dictionary.

        Args:
            name (str): Representation name.
            representation_id (str, optional): Representation ID.
            trait_data (dict): Representation data. Dictionary with keys
                as trait ids and values as trait data. Example::

                    {
                        "ayon.2d.PixelBased.v1": {
                            "display_window_width": 1920,
                            "display_window_height": 1080
                        },
                        "ayon.2d.Planar.v1": {
                            "channels": 3
                        }
                    }

        Returns:
            Representation: Representation instance.

        Raises:
            ValueError: If the trait model with ID is not found.
            TypeError: If the trait data is not a dictionary.
            IncompatibleTraitVersionError: If the trait version is incompatible

        """
        if not trait_data:
            trait_data = {}
        traits = []
        for trait_id, value in trait_data.items():
            if not isinstance(value, dict):
                msg = (
                    f"Invalid trait data for trait ID {trait_id}. "
                    "Trait data must be a dictionary."
                )
                raise TypeError(msg)

            try:
                trait_class = cls.get_trait_class_by_trait_id(trait_id)
            except UpgradableTraitError as e:
                # we found a newer version of trait, we will upgrade the data
                if hasattr(e.trait, "upgrade"):
                    traits.append(e.trait.upgrade(value))
                else:
                    msg = (
                        f"Newer version of trait {e.trait.id} found "
                        f"for requested {trait_id} but without "
                        "upgrade method."
                    )
                    raise IncompatibleTraitVersionError(msg) from e
            else:
                if not trait_class:
                    error_msg = f"Trait model with ID {trait_id} not found."
                    raise ValueError(error_msg)

                traits.append(trait_class(**value))

        return cls(
            name=name, representation_id=representation_id, traits=traits)

    def validate(self) -> None:
        """Validate the representation.

        This method will validate all the traits in the representation.

        Raises:
            TraitValidationError: If the trait is invalid within representation

        """
        errors = []
        for trait in self._data.values():
            # we do this in the loop to catch all the errors
            try:
                trait.validate_trait(self)
            except TraitValidationError as e:  # noqa: PERF203
                errors.append(str(e))
        if errors:
            msg = "\n".join(errors)
            scope = self.name
            raise TraitValidationError(scope, msg)