docstrings

docs/src/utils/lazy_eval/operator.md

@@ -0,0 +1,4 @@
+::: ffmpeg.utils.lazy_eval.operator
+    options:
+      show_source: false
+      members_order: source

docs/src/utils/lazy_eval/schema.md

@@ -0,0 +1,4 @@
+::: ffmpeg.utils.lazy_eval.schema
+    options:
+      show_source: false
+      members_order: source

mkdocs.yml

@@ -63,14 +63,17 @@ nav:
           - utils: src/dag/utils.md
           - validate: src/dag/validate.md
           - global_runnable:
-            - runnable: src/dag/global_runnable/runnable.md
-            - global_args: src/dag/global_runnable/global_args.md
+              - runnable: src/dag/global_runnable/runnable.md
+              - global_args: src/dag/global_runnable/global_args.md
       - utils:
           - escaping: src/utils/escaping.md
           - run: src/utils/run.md
           - snapshot: src/utils/snapshot.md
           - typing: src/utils/typing.md
           - view: src/utils/view.md
+          - lazy_eval:
+              - schema: src/utils/lazy_eval/schema.md
+              - operator: src/utils/lazy_eval/operator.md
 watch:
   - "src"
   - "docs"

src/ffmpeg/dag/schema.py

@@ -5,7 +5,7 @@
 from functools import cached_property
 from typing import TYPE_CHECKING, Literal
 
-from ..types import Filter_Node_Option_Type
+from ..utils.lazy_eval.schema import LazyValue
 from .utils import is_dag
 
 if TYPE_CHECKING:
@@ -75,7 +75,8 @@ class Node(HashableBaseModel, ABC):
         Each node in the DAG represents a single operation that transforms the data from its input form to its output form. The node is an essential component of the DAG, as it defines the nature of the operations that are performed on the data.
     """
 
-    kwargs: tuple[tuple[str, Filter_Node_Option_Type], ...] = ()
+    # Filter_Node_Option_Type
+    kwargs: tuple[tuple[str, str | int | float | bool | LazyValue], ...] = ()
     """
     Represents the keyword arguments of the node.
     """

src/ffmpeg/types.py

@@ -109,3 +109,6 @@
 
 
 Filter_Node_Option_Type = str | int | float | bool | LazyValue
+"""
+This represents the type of options that can be used with FFmpeg's filter nodes.
+"""

src/ffmpeg/utils/lazy_eval/operator.py

@@ -6,6 +6,10 @@
 
 @dataclass(frozen=True, kw_only=True)
 class Add(LazyOperator):
+    """
+    A lazy operator for addition.
+    """
+
     def _eval(self, left: Any, right: Any) -> Any:
         return left + right
 
@@ -15,6 +19,10 @@ def __str__(self) -> str:
 
 @dataclass(frozen=True, kw_only=True)
 class Sub(LazyOperator):
+    """
+    A lazy operator for subtraction.
+    """
+
     def _eval(self, left: Any, right: Any) -> Any:
         return left - right
 
@@ -24,6 +32,10 @@ def __str__(self) -> str:
 
 @dataclass(frozen=True, kw_only=True)
 class Mul(LazyOperator):
+    """
+    A lazy operator for multiplication.
+    """
+
     def _eval(self, left: Any, right: Any) -> Any:
         return left * right
 
@@ -33,6 +45,10 @@ def __str__(self) -> str:
 
 @dataclass(frozen=True, kw_only=True)
 class TrueDiv(LazyOperator):
+    """
+    A lazy operator for true division.
+    """
+
     def _eval(self, left: Any, right: Any) -> Any:
         return left / right
 
@@ -42,6 +58,10 @@ def __str__(self) -> str:
 
 @dataclass(frozen=True, kw_only=True)
 class Pow(LazyOperator):
+    """
+    A lazy operator for exponentiation.
+    """
+
     def _eval(self, left: Any, right: Any) -> Any:
         return left**right
 
@@ -51,6 +71,10 @@ def __str__(self) -> str:
 
 @dataclass(frozen=True, kw_only=True)
 class Neg(LazyOperator):
+    """
+    A lazy operator for negation.
+    """
+
     def _eval(self, left: Any, right: Any) -> Any:
         return -left
 
@@ -60,6 +84,10 @@ def __str__(self) -> str:
 
 @dataclass(frozen=True, kw_only=True)
 class Pos(LazyOperator):
+    """
+    A lazy operator for positive.
+    """
+
     def _eval(self, left: Any, right: Any) -> Any:
         return +left
 
@@ -69,6 +97,10 @@ def __str__(self) -> str:
 
 @dataclass(frozen=True, kw_only=True)
 class Abs(LazyOperator):
+    """
+    A lazy operator for absolute value.
+    """
+
     def _eval(self, left: Any, right: Any) -> Any:
         return abs(left)
 
@@ -78,6 +110,10 @@ def __str__(self) -> str:
 
 @dataclass(frozen=True, kw_only=True)
 class Mod(LazyOperator):
+    """
+    A lazy operator for modulo.
+    """
+
     def _eval(self, left: Any, right: Any) -> Any:
         return left % right
 
@@ -87,6 +123,10 @@ def __str__(self) -> str:
 
 @dataclass(frozen=True, kw_only=True)
 class FloorDiv(LazyOperator):
+    """
+    A lazy operator for floor division.
+    """
+
     def _eval(self, left: Any, right: Any) -> Any:
         return left // right
 

src/ffmpeg/utils/lazy_eval/schema.py

@@ -8,6 +8,10 @@
 
 
 class LazyValue(ABC):
+    """
+    A base class for lazy evaluation.
+    """
+
     def __add__(self, v: Any) -> LazyValue:
         from .operator import Add
 
@@ -94,25 +98,59 @@ def __rfloordiv__(self, v: Any) -> LazyValue:
         return FloorDiv(left=v, right=self)
 
     def eval(self, **values: Any) -> Any:
+        """
+        Evaluate the lazy value with the given values.
+
+        Args:
+            **values: Values to be used for evaluation.
+
+        Returns:
+            Any: The evaluated value.
+
+        Raises:
+            ValueError: If the lazy value is not ready to be evaluated.
+        """
         v = self.partial(**values)
         if isinstance(v, LazyValue):
-            raise KeyError(v.keys())
+            raise ValueError(v.keys())
         return v
 
     @abstractmethod
     def partial(self, **values: Any) -> Any:
+        """
+        Partially evaluate the lazy value with the given values.
+
+        Args:
+            **values: Values to be used for evaluation.
+
+        Returns:
+            Any: The partially evaluated value.
+        """
+
         ...
 
     def ready(self) -> bool:
+        """
+        Check if the lazy value is ready to be evaluated.
+        """
         return not self.keys()
 
     @abstractmethod
     def keys(self) -> set[str]:
+        """
+        Get the keys that are required to evaluate the lazy value.
+        """
         ...
 
 
 @dataclass(frozen=True)
 class Symbol(LazyValue):
+    """
+    A symbol that represents a variable in the lazy evaluation.
+
+    Such as `x`, `y`, `z`, etc.
+    """
+
     key: str
 
     def __str__(self) -> str:
@@ -131,11 +169,20 @@ def keys(self) -> set[str]:
 
 @dataclass(frozen=True, kw_only=True)
 class LazyOperator(LazyValue):
+    """
+    A base class for lazy operators.
+
+    Such as `Add`, `Sub`, `Mul`, `TrueDiv`, `Pow`, `Neg`, `Pos`, `Abs`, `Mod`, `FloorDiv`.
+    """
+
     left: Any = None
     right: Any = None
 
     @abstractmethod
     def _eval(self, left: Any, right: Any) -> Any:
+        """
+        Evaluate the operator with the given values.
+        """
         ...
 
     @override

src/ffmpeg/utils/run.py

@@ -1,7 +1,7 @@
 import shlex
 
 from ..schema import Default
-from ..types import Filter_Node_Option_Type
+from ..utils.lazy_eval.schema import LazyValue
 
 
 def command_line(args: list[str]) -> str:
@@ -17,9 +17,10 @@ def command_line(args: list[str]) -> str:
     return " ".join(shlex.quote(arg) for arg in args)
 
 
+# Filter_Node_Option_Type
 def ignore_default(
-    kwargs: dict[str, Filter_Node_Option_Type | Default]
-) -> tuple[tuple[str, Filter_Node_Option_Type], ...]:
+    kwargs: dict[str, str | int | float | bool | Default]
+) -> tuple[tuple[str, str | int | float | bool | LazyValue], ...]:
     """
     Convert the values of the dictionary to strings.
     """