generic ¶

def apply(self, clip: vs.VideoNode) -> vs.VideoNode:
    """
    Applies the property to the VideoNode.
    """
    return clip.std.SetFrameProp(self.prop_key, self.value)

@classmethod
def ensure_presence(cls, clip: vs.VideoNode, value: Any, func: FuncExcept | None = None) -> vs.VideoNode:
    """
    Ensure the presence of the property in the VideoNode.
    """
    enum_value = cls.from_param_or_video(value, clip, True, func)

    return clip.std.SetFrameProp(enum_value.prop_key, enum_value.value)

@staticmethod
def ensure_presences(
    clip: vs.VideoNode, prop_enums: Iterable[type[PropEnum] | PropEnum], func: FuncExcept | None = None
) -> vs.VideoNode:
    """
    Ensure the presence of multiple PropEnums at once.
    """
    return clip.std.SetFrameProps(
        **{
            value.prop_key: value.value
            for value in (
                prop_enum if isinstance(prop_enum, PropEnum) else prop_enum.from_video(clip, True, func)
                for prop_enum in prop_enums
            )
        },
    )

@classmethod
def from_param(cls, value: Any, func_except: FuncExcept | None = None) -> Self:
    """
    Return the enum value from a parameter.

    Args:
        value: Value to instantiate the enum class.
        func_except: Exception function.

    Returns:
        Enum value.

    Raises:
        NotFoundEnumValue: Variable not found in the given enum.
    """
    func_except = func_except or cls.from_param

    try:
        return cls(value)
    except (ValueError, TypeError):
        pass

    if isinstance(func_except, tuple):
        func_name, var_name = func_except
    else:
        func_name, var_name = func_except, repr(cls)

    raise NotFoundEnumValueError(
        'The given value for "{var_name}" argument must be a valid {enum_name}, not "{value}"!\n'
        "Valid values are: [{readable_enum}].",
        func_name,
        var_name=var_name,
        enum_name=cls,
        value=value,
        readable_enum=(f"{name} ({value!r})" for name, value in cls.__members__.items()),
        reason=value,
    ) from None

@classmethod
def from_param_or_video(
    cls,
    value: Any,
    src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any],
    strict: bool = False,
    func_except: FuncExcept | None = None,
) -> Self:
    """
    Get the enum member from a value that can be casted to this prop value or grab it from frame properties.

    If `strict=False`, gather the heuristics using the clip's size or format.

    Args:
        value: Value to cast.
        src: Clip to get prop from.
        strict: Be strict about the frame properties. Default: False.
        func_except: Function returned for custom error handling.
    """
    prop = cls.from_param_with_fallback(value, None)

    # Delay the `from_video` call here to avoid unnecessary frame rendering
    if prop is None:
        return cls.from_video(src, strict, func_except)

    return prop

@classmethod
def from_param_with_fallback[T](cls, value: Any, fallback: T | None = None) -> Self | T | None:
    """
    Attempts to obtain an enum member from a parameter value, returning a fallback if the value cannot be converted
    or represents an unspecified enum member.

    Args:
        value: The input value to convert into an enum member.
        fallback: The value to return if the input cannot be converted. Defaults to `None`.

    Returns:
        The corresponding enum member if conversion succeeds, otherwise the provided `fallback` value.
    """
    with suppress(NotFoundEnumValueError, CustomValueError):
        # Will raise a NotFoundEnumValueError if the value can't be casted
        casted = cls.from_param(value)

        # If unspecified, fallbacks to `fallback` value
        if casted.is_unspecified:
            raise CustomValueError

        return casted

    return fallback

@classmethod
def from_res(cls, frame: vs.VideoNode | vs.VideoFrame) -> ChromaLocation:
    """
    Guess the chroma location based on the clip's resolution.

    Args:
        frame: Input clip or frame.

    Returns:
        ChromaLocation object.
    """
    return ChromaLocation.LEFT

@classmethod
def from_string(cls, string: str, func: FuncExcept | None = None) -> Self:
    """
    Get the enum member whose `string` attribute matches the given value.

    Args:
        string: The string to match against the enum members `string` attribute.

    Raises:
        NotFoundEnumValueError: If no enum member has a `string` value equal to the provided one.
        CustomOverflowError: If multiple enum members share the same `string` value, making the lookup ambiguous.

    Returns:
        The matching enum member.
    """

    matched_strings = [m for m in cls if m.string == string]

    if not matched_strings:
        raise NotFoundEnumValueError(f"No enum member found with string value {string!r}.", func)

    if len(matched_strings) > 1:
        raise CustomOverflowError(
            f"Multiple enum members found with string value {string!r}; expected exactly one.", func
        )

    return matched_strings.pop()

@classmethod
def from_video(
    cls, src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any], strict: bool = False, func: FuncExcept | None = None
) -> ChromaLocation:
    """
    Obtain the chroma location of a clip from the frame properties.

    Args:
        src: Input clip, frame, or props.
        strict: Be strict about the properties. The result may NOT be an unknown value.

    Returns:
        ChromaLocation object.

    Raises:
        UndefinedChromaLocationError: If chroma location is undefined or chroma location can not be determined
            from the frame properties.
    """
    return _base_from_video(cls, src, UndefinedChromaLocationError, strict, func)

def get_offsets(self, src: SupportsInt | VideoFormatLike | HoldsVideoFormat) -> tuple[float, float]:
    """
    Get (left,top) shift for chroma relative to luma.

    This is only useful if you MUST use a pre-specified chroma location and shift the chroma yourself.
    """
    from ..utils import get_video_format

    fmt = get_video_format(src)

    off_left = off_top = 0.0

    if self in [ChromaLocation.LEFT, ChromaLocation.TOP_LEFT, ChromaLocation.BOTTOM_LEFT]:
        off_left = 0.5 - 2 ** (fmt.subsampling_w - 1)

    if self in [ChromaLocation.TOP, ChromaLocation.TOP_LEFT]:
        off_top = 0.5 - 2 ** (fmt.subsampling_h - 1)
    elif self in [ChromaLocation.BOTTOM, ChromaLocation.BOTTOM_LEFT]:
        off_top = 2 ** (fmt.subsampling_h - 1) - 0.5

    return off_left, off_top

@cachedproperty
def pretty_string(self) -> str:
    """
    Get a pretty, displayable string of the enum member.
    """
    return self._pretty_string

@classproperty
@classmethod
def prop_key(cls) -> str:
    """
    The key used in props to store the enum.
    """
    return f"_{cls.__name__}"

@cachedproperty
def string(self) -> str:
    """
    Get the string representation used in resize plugin/encoders.
    """
    return self._string

@enum_property
def value(self) -> int: ...

def apply(self, clip: vs.VideoNode) -> vs.VideoNode:
    """
    Applies the property to the VideoNode.
    """
    return clip.std.SetFrameProp(self.prop_key, self.value)

@classmethod
def ensure_presence(cls, clip: vs.VideoNode, value: Any, func: FuncExcept | None = None) -> vs.VideoNode:
    """
    Ensure the presence of the property in the VideoNode.
    """
    enum_value = cls.from_param_or_video(value, clip, True, func)

    return clip.std.SetFrameProp(enum_value.prop_key, enum_value.value)

@staticmethod
def ensure_presences(
    clip: vs.VideoNode, prop_enums: Iterable[type[PropEnum] | PropEnum], func: FuncExcept | None = None
) -> vs.VideoNode:
    """
    Ensure the presence of multiple PropEnums at once.
    """
    return clip.std.SetFrameProps(
        **{
            value.prop_key: value.value
            for value in (
                prop_enum if isinstance(prop_enum, PropEnum) else prop_enum.from_video(clip, True, func)
                for prop_enum in prop_enums
            )
        },
    )

@classmethod
def from_param(cls, value: Any, func_except: FuncExcept | None = None) -> Self:
    """
    Return the enum value from a parameter.

    Args:
        value: Value to instantiate the enum class.
        func_except: Exception function.

    Returns:
        Enum value.

    Raises:
        NotFoundEnumValue: Variable not found in the given enum.
    """
    func_except = func_except or cls.from_param

    try:
        return cls(value)
    except (ValueError, TypeError):
        pass

    if isinstance(func_except, tuple):
        func_name, var_name = func_except
    else:
        func_name, var_name = func_except, repr(cls)

    raise NotFoundEnumValueError(
        'The given value for "{var_name}" argument must be a valid {enum_name}, not "{value}"!\n'
        "Valid values are: [{readable_enum}].",
        func_name,
        var_name=var_name,
        enum_name=cls,
        value=value,
        readable_enum=(f"{name} ({value!r})" for name, value in cls.__members__.items()),
        reason=value,
    ) from None

@classmethod
def from_param_or_video(
    cls,
    value: Any,
    src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any],
    strict: bool = False,
    func_except: FuncExcept | None = None,
) -> Self:
    """
    Get the enum member from a value that can be casted to this prop value or grab it from frame properties.

    If `strict=False`, gather the heuristics using the clip's size or format.

    Args:
        value: Value to cast.
        src: Clip to get prop from.
        strict: Be strict about the frame properties. Default: False.
        func_except: Function returned for custom error handling.
    """
    prop = cls.from_param_with_fallback(value, None)

    # Delay the `from_video` call here to avoid unnecessary frame rendering
    if prop is None:
        return cls.from_video(src, strict, func_except)

    return prop

@classmethod
def from_param_with_fallback[T](cls, value: Any, fallback: T | None = None) -> Self | T | None:
    """
    Attempts to obtain an enum member from a parameter value, returning a fallback if the value cannot be converted
    or represents an unspecified enum member.

    Args:
        value: The input value to convert into an enum member.
        fallback: The value to return if the input cannot be converted. Defaults to `None`.

    Returns:
        The corresponding enum member if conversion succeeds, otherwise the provided `fallback` value.
    """
    with suppress(NotFoundEnumValueError, CustomValueError):
        # Will raise a NotFoundEnumValueError if the value can't be casted
        casted = cls.from_param(value)

        # If unspecified, fallbacks to `fallback` value
        if casted.is_unspecified:
            raise CustomValueError

        return casted

    return fallback

@classmethod
def from_res(cls, frame: vs.VideoNode | vs.VideoFrame) -> NoReturn:
    raise CustomNotImplementedError

@classmethod
def from_string(cls, string: str, func: FuncExcept | None = None) -> Self:
    """
    Get the enum member whose `string` attribute matches the given value.

    Args:
        string: The string to match against the enum members `string` attribute.

    Raises:
        NotFoundEnumValueError: If no enum member has a `string` value equal to the provided one.
        CustomOverflowError: If multiple enum members share the same `string` value, making the lookup ambiguous.

    Returns:
        The matching enum member.
    """

    matched_strings = [m for m in cls if m.string == string]

    if not matched_strings:
        raise NotFoundEnumValueError(f"No enum member found with string value {string!r}.", func)

    if len(matched_strings) > 1:
        raise CustomOverflowError(
            f"Multiple enum members found with string value {string!r}; expected exactly one.", func
        )

    return matched_strings.pop()

@classmethod
def from_video(
    cls, src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any], strict: bool = False, func: FuncExcept | None = None
) -> Field:
    """
    Obtain the Field of a clip from the frame properties.

    Args:
        src: Input clip, frame, or props.
        strict: Be strict about the properties. Will ALWAYS error if the Field is missing.
        func: Function returned for custom error handling.

    Returns:
        Field object.

    Raises:
        UndefinedFieldError: if the Field is undefined or can not be determined from the frame properties.
    """
    return _base_from_video(cls, src, UndefinedFieldError, strict, func)

@cachedproperty
def pretty_string(self) -> str:
    """
    Get a pretty, displayable string of the enum member.
    """
    return self._pretty_string

@classproperty
@classmethod
def prop_key(cls) -> str:
    """
    The key used in props to store the enum.
    """
    return f"_{cls.__name__}"

@cachedproperty
def string(self) -> str:
    """
    Get the string representation used in resize plugin/encoders.
    """
    return self._string

@enum_property
def value(self) -> int: ...

def apply(self, clip: vs.VideoNode) -> vs.VideoNode:
    return clip.std.SetFieldBased(self.value)

@classmethod
def ensure_presence(cls, clip: vs.VideoNode, value: Any, func: FuncExcept | None = None) -> vs.VideoNode:
    """
    Ensure the presence of the property in the clip.

    Args:
        clip: Input clip.
        value: Value or FieldBased object. If it's bool, it specifies whether it's TFF or BFF.
        func: Function returned for custom error handling.

    Returns:
        Clip with the FieldBased set.
    """
    return clip.std.SetFieldBased(cls.from_param_or_video(value, clip, True, func))

@staticmethod
def ensure_presences(
    clip: vs.VideoNode, prop_enums: Iterable[type[PropEnum] | PropEnum], func: FuncExcept | None = None
) -> vs.VideoNode:
    """
    Ensure the presence of multiple PropEnums at once.
    """
    return clip.std.SetFrameProps(
        **{
            value.prop_key: value.value
            for value in (
                prop_enum if isinstance(prop_enum, PropEnum) else prop_enum.from_video(clip, True, func)
                for prop_enum in prop_enums
            )
        },
    )

@classmethod
def from_param(cls, value: Any, func_except: FuncExcept | None = None) -> FieldBased:
    """
    Determine the type of field through a parameter.

    Args:
        value: Value or FieldBased object. If it's bool, it specifies whether it's TFF or BFF.
        func_except: Function returned for custom error handling.

    Returns:
        FieldBased object.
    """
    if isinstance(value, bool):
        return cls(1 + value)

    return super().from_param(value, func_except)

@classmethod
def from_param_or_video(
    cls,
    value: Any,
    src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any],
    strict: bool = False,
    func_except: FuncExcept | None = None,
) -> Self:
    """
    Get the enum member from a value that can be casted to this prop value or grab it from frame properties.

    If `strict=False`, gather the heuristics using the clip's size or format.

    Args:
        value: Value to cast.
        src: Clip to get prop from.
        strict: Be strict about the frame properties. Default: False.
        func_except: Function returned for custom error handling.
    """
    prop = cls.from_param_with_fallback(value, None)

    # Delay the `from_video` call here to avoid unnecessary frame rendering
    if prop is None:
        return cls.from_video(src, strict, func_except)

    return prop

@classmethod
def from_param_with_fallback[T](cls, value: Any, fallback: T | None = None) -> Self | T | None:
    """
    Attempts to obtain an enum member from a parameter value, returning a fallback if the value cannot be converted
    or represents an unspecified enum member.

    Args:
        value: The input value to convert into an enum member.
        fallback: The value to return if the input cannot be converted. Defaults to `None`.

    Returns:
        The corresponding enum member if conversion succeeds, otherwise the provided `fallback` value.
    """
    with suppress(NotFoundEnumValueError, CustomValueError):
        # Will raise a NotFoundEnumValueError if the value can't be casted
        casted = cls.from_param(value)

        # If unspecified, fallbacks to `fallback` value
        if casted.is_unspecified:
            raise CustomValueError

        return casted

    return fallback

@classmethod
def from_res(cls, frame: vs.VideoNode | vs.VideoFrame) -> FieldBased:
    """
    Guess the Field order from the frame resolution.
    """
    return cls.PROGRESSIVE

@classmethod
def from_string(cls, string: str, func: FuncExcept | None = None) -> Self:
    """
    Get the enum member whose `string` attribute matches the given value.

    Args:
        string: The string to match against the enum members `string` attribute.

    Raises:
        NotFoundEnumValueError: If no enum member has a `string` value equal to the provided one.
        CustomOverflowError: If multiple enum members share the same `string` value, making the lookup ambiguous.

    Returns:
        The matching enum member.
    """

    matched_strings = [m for m in cls if m.string == string]

    if not matched_strings:
        raise NotFoundEnumValueError(f"No enum member found with string value {string!r}.", func)

    if len(matched_strings) > 1:
        raise CustomOverflowError(
            f"Multiple enum members found with string value {string!r}; expected exactly one.", func
        )

    return matched_strings.pop()

@classmethod
def from_video(
    cls, src: vs.VideoNode | vs.VideoFrame | Mapping[str, Any], strict: bool = False, func: FuncExcept | None = None
) -> FieldBased:
    """
    Obtain the Field order of a clip from the frame properties.

    Args:
        src: Input clip, frame, or props.
        strict: Be strict about the properties. Will ALWAYS error if the FieldBased is missing.
        func: Function returned for custom error handling.

    Returns:
        FieldBased object.

    Raises:
        UndefinedFieldBasedError: If the Field order is undefined or can not be determined
            from the frame properties.
    """
    return _base_from_video(cls, src, UndefinedFieldBasedError, strict, func)

@classproperty
@classmethod
def prop_key(cls) -> str:
    """
    The key used in props to store the enum.
    """
    return f"_{cls.__name__}"

@cachedproperty
def string(self) -> str:
    """
    Get the string representation used in resize plugin/encoders.
    """
    return self._string

@enum_property
def value(self) -> int: ...