schema

Schema for lazy evaluation of expressions in FFmpeg filter parameters.

This module defines the core classes for lazy evaluation of expressions in FFmpeg filter parameters. It provides a way to represent expressions that can be evaluated at a later time, when all required values are available. This is particularly useful for parameters that depend on runtime information or need to be computed based on other parameters.

Classes:

Name	Description
LazyValue	Abstract base class for lazy evaluation of expressions.
Symbol	A symbol that represents a variable in lazy evaluation expressions.
LazyOperator	Abstract base class for operators in lazy evaluation expressions.

LazyValue

Bases: ABC

Abstract base class for lazy evaluation of expressions.

LazyValue represents an expression that can be evaluated at a later time, when all required values are available. It supports various arithmetic operations, allowing complex expressions to be built and evaluated lazily.

This class serves as the foundation for the lazy evaluation system, with concrete implementations like Symbol and LazyOperator providing specific functionality.

Methods:

Name	Description
eval	Evaluate the lazy value with the given values.
partial	Partially evaluate the lazy value with the given values.
ready	Check if the lazy value is ready to be evaluated.
keys	Get the keys that are required to evaluate the lazy value.

eval

eval(**values: Any) -> Any

Evaluate the lazy value with the given values.

Parameters:

Name	Type	Description	Default
**values	Any	Values to be used for evaluation.	{}

Returns:

Name	Type	Description
Any	Any	The evaluated value.

Raises:

Type	Description
ValueError	If the lazy value is not ready to be evaluated.

partial abstractmethod

partial(**values: Any) -> Any

Partially evaluate the lazy value with the given values.

Parameters:

Name	Type	Description	Default
**values	Any	Values to be used for evaluation.	{}

Returns:

Name	Type	Description
Any	Any	The partially evaluated value.

ready

ready() -> bool

Check if the lazy value is ready to be evaluated.

A lazy value is considered ready for evaluation when it doesn't require any additional values to be provided. This is determined by checking if the set of required keys is empty.

Returns:

Type	Description
bool	True if the lazy value can be evaluated without additional values,
bool	False otherwise

keys abstractmethod

keys() -> set[str]

Get the keys that are required to evaluate the lazy value.

This method returns the set of symbol names that must be provided as values for the lazy value to be fully evaluated. For example, if the lazy value represents the expression 'width * height', this method would return {'width', 'height'}.

Returns:

Type	Description
set[str]	A set of strings representing the required symbol names

Symbol dataclass

Symbol(key: str)

Bases: LazyValue

A symbol that represents a variable in lazy evaluation expressions.

Symbol is a concrete implementation of LazyValue that represents a named variable in an expression. When evaluating the expression, the actual value of the symbol is provided through a dictionary of values.

Examples of symbols include variable names like 'width', 'height', or any other parameter that will be provided at evaluation time rather than at expression creation time.

Attributes:

Name	Type	Description
key	str	The name of the variable this symbol represents

Methods:

Name	Description
partial	Partially evaluate this symbol with the given values.
keys	Get the set of symbol names required to evaluate this symbol.
eval	Evaluate the lazy value with the given values.
ready	Check if the lazy value is ready to be evaluated.

partial

partial(**values: Any) -> Any

Partially evaluate this symbol with the given values.

If the symbol's key is present in the values dictionary, returns the corresponding value. Otherwise, returns the symbol itself (unchanged).

Parameters:

Name	Type	Description	Default
**values	Any	Dictionary mapping symbol names to their values	{}

Returns:

Type	Description
Any	The value for this symbol if available, otherwise the symbol itself

keys

keys() -> set[str]

Get the set of symbol names required to evaluate this symbol.

For a Symbol, this is simply a set containing its own key.

Returns:

Type	Description
set[str]	A set containing the symbol's key

eval

eval(**values: Any) -> Any

Evaluate the lazy value with the given values.

Parameters:

Name	Type	Description	Default
**values	Any	Values to be used for evaluation.	{}

Returns:

Name	Type	Description
Any	Any	The evaluated value.

Raises:

Type	Description
ValueError	If the lazy value is not ready to be evaluated.

ready

ready() -> bool

Check if the lazy value is ready to be evaluated.

A lazy value is considered ready for evaluation when it doesn't require any additional values to be provided. This is determined by checking if the set of required keys is empty.

Returns:

Type	Description
bool	True if the lazy value can be evaluated without additional values,
bool	False otherwise

LazyOperator dataclass

LazyOperator(*, left: Any = None, right: Any = None)

Bases: LazyValue

Abstract base class for operators in lazy evaluation expressions.

LazyOperator is an abstract implementation of LazyValue that represents mathematical operations in an expression. Concrete subclasses implement specific operations like addition, subtraction, multiplication, etc.

This class provides the common structure and behavior for all operators, including handling of operands that may themselves be LazyValues.

Attributes:

Name	Type	Description
left	Any	The left operand of the operation (or the only operand for unary operations)
right	Any	The right operand of the operation (None for unary operations)

Concrete implementations include

Add, Sub, Mul, TrueDiv, Pow, Neg, Pos, Abs, Mod, FloorDiv

Methods:

Name	Description
partial	Partially evaluate this operator with the given values.
keys	Get the set of symbol names required to evaluate this operator.
eval	Evaluate the lazy value with the given values.
ready	Check if the lazy value is ready to be evaluated.

partial

partial(**values: Any) -> Any

Partially evaluate this operator with the given values.

This method recursively evaluates the operands (which may themselves be LazyValues) with the provided values, then applies the operator's specific operation to the results.

Parameters:

Name	Type	Description	Default
**values	Any	Dictionary mapping symbol names to their values	{}

Returns:

Type	Description
Any	The result of applying the operation to the partially evaluated operands,
Any	which may be a concrete value or another LazyValue if some symbols
Any	remain unevaluated

keys

keys() -> set[str]

Get the set of symbol names required to evaluate this operator.

This method collects the required symbol names from both operands (if they are LazyValues) and returns their union.

Returns:

Type	Description
set[str]	A set of strings representing all symbol names required to
set[str]	fully evaluate this operator

eval

eval(**values: Any) -> Any

Evaluate the lazy value with the given values.

Parameters:

Name	Type	Description	Default
**values	Any	Values to be used for evaluation.	{}

Returns:

Name	Type	Description
Any	Any	The evaluated value.

Raises:

Type	Description
ValueError	If the lazy value is not ready to be evaluated.

ready

ready() -> bool

Check if the lazy value is ready to be evaluated.

A lazy value is considered ready for evaluation when it doesn't require any additional values to be provided. This is determined by checking if the set of required keys is empty.

Returns:

Type	Description
bool	True if the lazy value can be evaluated without additional values,
bool	False otherwise