Add function/decorator checks for variable-format/resolution clips

[OrangeChannel]

This prevents us having to write the same ValueError for every function that requires a clip to have a format because it tries to access the clip.format's attributes.

[tomato39]

Is there a way to get mypy to recognize this? Right now it doesn't seem smart enough to follow the None check through the decorator.

Edit: potentially something like

class ConstantFormatNode(vs.VideoNode):
    format: vs.Format

def disallow_variable_format(function: Callable[..., R]) -> Callable[..., R]:
    """
    Function decorator that raises an exception if the input clip has a variable format.
    """
    def _check(clip: vs.VideoNode, *args: Any, **kwargs: Any) -> R:
        if is_variable(clip, format=True):
            raise ValueError('Variable-format clips not supported.')
        clip.__class__ = ConstantFormatNode
        return function(clip, *args, **kwargs)
    return _check

and making the unwrapped functions take ConstantFormatNode

[stuxcrystal]

@heicrd yes. typing.cast

But it seems that all type-checkers hate Decorators and Descriptors.

[OrangeChannel]

This can all be squashed into one commit with the PR title and reference #.

[OrangeChannel]

Should we bump the version number in this update? This technically changes the exposed API by adding three new functions.
I don't know how git-tagging works for PRs or forks, I'd assume pushing tags directly to upstream/master is the better or only way to do it.

I recommend tagging ee49d9d as 0.3.0,
(and af4dd0a as 0.3.1 is we want to be specific), and whatever this squashed commit becomes as 0.4.0.

[OrangeChannel]

So, I've completely satisfied mypy's issues on vsutil's side here: https://www.diffchecker.com/tGKtXhE5
Not sure if this fits in this PR, or is even wanted but figured I'd show @stuxcrystal @heicrd.

[kageru]

So, I've completely satisfied mypy's issues on vsutil's side here: https://www.diffchecker.com/tGKtXhE5
Not sure if this fits in this PR, or is even wanted but figured I'd show @stuxcrystal @heicrd.

I’m against doing that. Having the casts inside the decorators is fine, but adding them everywhere just to make a dysfunctional typechecker happy is not what I want. We shouldn’t make code more complicated just to please the IDE or some third-party tool.
Having decorators at all is already a level of complexity that might scare away potential contributors (most VS users don’t know much about Python), but I think they’re quite self-explanatory in this case, so I’m fine with that.

In general, we might consider making some of these functions work with variable formats (e.g. I don’t see a reason why depth shouldn’t work on a variable-depth input), but that’s out of scope here.

As for the tags, I’ve tagged the commit you suggested as 0.3.0, and I agree with tagging this as 0.4.0. I’ll do that after merge.
The decorators are part of the public API, and I believe they can be useful to other script and library authors, so I’d definitely consider that a new feature, and thus a minor version bump.
We technically also change the existing API, but in a very minor way (i.e. always raising ValueErrors, where previously an unintended AttributeError could have occured), but I don’t think that matters in practive due to how Vapoursynth scripts are usually written.

[tomato39]

Yeah you can just cast inside the decorator and change the function signature to def fun(clip: _ConstantFormatVideoNode, ...) etc without having to use casts anywhere.

Having decorators at all is already a level of complexity that might scare away potential contributors

vsutil is already beyond this point with using typehints and unit tests in the first place imo. i don't think it's a good idea either way to try and draw contributors who have actually zero programming experience

[OrangeChannel]

I’ll make a more coherent response later but wanted to say that casting inside the decorator doesn’t solve mypy’s problem. It also creates another problem where another script calling get_subsampling(clip_VideoNode) is an error because isinstance(clip_VideoNode, _ConstantFormatNode) is False. mypy isn’t smart enough to know what to do with a changed signature via the decorator and casting inside the decorator means losing the ability to use the decorated functions with normal VideoNodes.

[kageru]

I’ll make a more coherent response later

@OrangeChannel I’m still kind of waiting for that.
Are there any other changes you still want to make here or can we merge this?

[OrangeChannel]

Oh I think I just explained the problem with typechecking the decorators in Light’s discord. There’s not much we can do here that wouldn’t be super over-engineered so as far as I’m concerned, the PR is ready to merge.

[OrangeChannel]

There’s a few open issues in mypy’s repo that might address this stuff in the future but for now the casting and stuff isn’t worth it.