typed-ffmpeg-compatible 2.6.2__py3-none-any.whl → 2.6.4__py3-none-any.whl

typed_ffmpeg/streams/channel_layout.py

@@ -1,3 +1,16 @@
+"""
+Audio channel layout definitions for FFmpeg.
+
+This module defines a mapping between FFmpeg's channel layout names and
+the corresponding number of audio channels. This information is used for
+audio stream processing, filtering, and conversion operations.
+
+Channel layouts in FFmpeg represent different speaker configurations,
+such as mono (1 channel), stereo (2 channels), 5.1 (6 channels), etc.
+The names used in this dictionary match the standard names used by FFmpeg's
+channel layout API.
+"""
+
 CHANNEL_LAYOUT = {
     "mono": 1,
     "stereo": 2,

typed_ffmpeg/utils/escaping.py

@@ -1,17 +1,39 @@
+"""
+Utilities for escaping special characters in FFmpeg command arguments.
+
+This module provides functions for properly escaping special characters in
+FFmpeg command-line arguments and converting Python dictionaries to FFmpeg
+command-line parameter formats.
+"""
+
 from collections.abc import Iterable
 from typing import Any
 
 
 def escape(text: str | int | float, chars: str = "\\'=:") -> str:
     """
-    Helper function to escape uncomfortable characters.
+    Escape special characters in a string for use in FFmpeg commands.
+
+    This function adds backslash escaping to specified characters in a string,
+    making it safe to use in FFmpeg filter strings and command-line arguments
+    where certain characters have special meaning.
 
     Args:
-        text: The text to escape.
-        chars: The characters to escape.
+        text: The text to escape (will be converted to string if not already)
+        chars: A string containing all characters that should be escaped
+               (default: "\\'=:" which handles most common special chars in FFmpeg)
 
     Returns:
-        The escaped text.
+        The input text with all specified characters escaped with backslashes
+
+    Example:
+        ```python
+        # Escape a filename with spaces for FFmpeg
+        safe_filename = escape("input file.mp4")  # "input\\ file.mp4"
+
+        # Escape a filter parameter value
+        safe_value = escape("key=value", "=:")  # "key\\=value"
+        ```
     """
     text = str(text)
     _chars = list(set(chars))
@@ -27,13 +49,31 @@ def escape(text: str | int | float, chars: str = "\\'=:") -> str:
 
 def convert_kwargs_to_cmd_line_args(kwargs: dict[str, Any]) -> list[str]:
     """
-    Helper function to build command line arguments out of dict.
+    Convert a Python dictionary to FFmpeg command-line arguments.
+
+    This function takes a dictionary of parameter names and values and converts
+    them to a list of strings in the format expected by FFmpeg command-line tools.
+    Each key becomes a parameter prefixed with '-', and its value follows as a
+    separate argument.
 
     Args:
-        kwargs: The dict to convert.
+        kwargs: Dictionary mapping parameter names to their values
 
     Returns:
-        The command line arguments.
+        A list of strings representing FFmpeg command-line arguments
+
+    Example:
+        ```python
+        args = convert_kwargs_to_cmd_line_args(
+            {"c:v": "libx264", "crf": 23, "preset": "medium"}
+        )
+        # Returns ['-c:v', 'libx264', '-crf', '23', '-preset', 'medium']
+        ```
+
+    Note:
+        If a value is None, only the parameter name is included.
+        If a value is an iterable (but not a string), the parameter is repeated
+        for each value in the iterable.
     """
     args = []
     for k in sorted(kwargs.keys()):

typed_ffmpeg/utils/forzendict.py

@@ -0,0 +1,108 @@
+"""
+Provides an immutable dictionary implementation.
+
+This module implements a frozen (immutable) dictionary class that can be used
+where hashable dictionaries are needed, such as in sets or as keys in other
+dictionaries. Once created, a FrozenDict cannot be modified.
+"""
+
+from collections.abc import Iterator, Mapping
+from typing import Any, Generic, TypeVar
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+class FrozenDict(Mapping[K, V], Generic[K, V]):
+    """
+    An immutable dictionary implementation.
+
+    FrozenDict provides a hashable, immutable view of a dictionary. It implements
+    the Mapping interface but does not allow modification after creation.
+    This makes it suitable for use as dictionary keys or in sets where
+    mutability would cause issues.
+    """
+
+    def __init__(self, data: dict[K, V]):
+        """
+        Initialize a FrozenDict with the provided dictionary data.
+
+        Args:
+            data: Dictionary to create a frozen copy of
+        """
+        self._data = dict(data)
+        self._hash: int | None = None  # lazy computed
+
+    def __getitem__(self, key: K) -> V:
+        """
+        Retrieve a value from the dictionary by key.
+
+        Args:
+            key: The key to look up
+
+        Returns:
+            The value associated with the key
+
+        Raises:
+            KeyError: If the key is not found
+        """
+        return self._data[key]
+
+    def __iter__(self) -> Iterator[K]:
+        """
+        Return an iterator over the dictionary keys.
+
+        Returns:
+            An iterator yielding the dictionary keys
+        """
+        return iter(self._data)
+
+    def __len__(self) -> int:
+        """
+        Return the number of items in the dictionary.
+
+        Returns:
+            The number of key-value pairs in the dictionary
+        """
+        return len(self._data)
+
+    def __repr__(self) -> str:
+        """
+        Return a string representation of the FrozenDict.
+
+        Returns:
+            A string representation showing the dictionary contents
+        """
+        return f"FrozenDict({self._data})"
+
+    def __eq__(self, other: Any) -> bool:
+        """
+        Compare this FrozenDict with another object for equality.
+
+        Two FrozenDicts are equal if they contain the same key-value pairs.
+        A FrozenDict can also be equal to other Mapping objects with the same contents.
+
+        Args:
+            other: Object to compare with
+
+        Returns:
+            True if the objects are equal, False otherwise
+        """
+        if isinstance(other, Mapping):
+            return dict(self._data) == dict(other)
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        """
+        Compute a hash value for this FrozenDict.
+
+        The hash is lazily computed the first time it's needed and then cached.
+        This makes FrozenDict usable as a dictionary key or in sets.
+
+        Returns:
+            An integer hash value
+        """
+        if self._hash is None:
+            # Create a stable hash based on sorted key-value pairs
+            self._hash = hash(frozenset(self._data.items()))
+        return self._hash

typed_ffmpeg/utils/lazy_eval/operator.py

@@ -1,3 +1,12 @@
+"""
+Concrete operator implementations for lazy evaluation expressions.
+
+This module defines the specific operator classes that implement the LazyOperator
+abstract base class. Each class represents a mathematical operation like addition,
+subtraction, multiplication, etc., and provides the implementation for evaluating
+that operation when all required values are available.
+"""
+
 from dataclasses import dataclass
 from typing import Any
 
@@ -7,13 +16,46 @@ from .schema import LazyOperator
 @dataclass(frozen=True, kw_only=True)
 class Add(LazyOperator):
     """
-    A lazy operator for addition.
+    A lazy operator for addition operations.
+
+    This class implements the addition operation for lazy evaluation expressions.
+    It evaluates to the sum of its left and right operands when all required
+    values are available.
+
+    Example:
+        ```python
+        # Create an expression that adds width and height
+        from .schema import Symbol
+
+        width = Symbol("width")
+        height = Symbol("height")
+        expr = Add(left=width, right=height)
+
+        # Evaluate the expression with specific values
+        result = expr.eval(width=1280, height=720)  # Returns 2000
+        ```
     """
 
     def _eval(self, left: Any, right: Any) -> Any:
+        """
+        Evaluate the addition operation with the given operands.
+
+        Args:
+            left: The left operand
+            right: The right operand
+
+        Returns:
+            The sum of the left and right operands
+        """
         return left + right
 
     def __str__(self) -> str:
+        """
+        Get a string representation of this addition operation.
+
+        Returns:
+            A string in the format "(left+right)"
+        """
         return f"({self.left}+{self.right})"
 
 

typed_ffmpeg/utils/lazy_eval/schema.py

@@ -1,3 +1,13 @@
+"""
+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.
+"""
+
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
@@ -9,7 +19,15 @@ from ..typing import override
 
 class LazyValue(ABC):
     """
-    A base class for lazy evaluation.
+    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.
     """
 
     def __add__(self, v: Any) -> LazyValue:
@@ -132,6 +150,14 @@ class LazyValue(ABC):
     def ready(self) -> 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:
+            True if the lazy value can be evaluated without additional values,
+            False otherwise
         """
         return not self.keys()
 
@@ -139,6 +165,14 @@ class LazyValue(ABC):
     def keys(self) -> 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:
+            A set of strings representing the required symbol names
         """
         ...
 
@@ -146,33 +180,80 @@ class LazyValue(ABC):
 @dataclass(frozen=True)
 class Symbol(LazyValue):
     """
-    A symbol that represents a variable in the lazy evaluation.
+    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.
 
-    Such as `x`, `y`, `z`, etc.
+    Attributes:
+        key: The name of the variable this symbol represents
     """
 
     key: str
 
     def __str__(self) -> str:
+        """
+        Get a string representation of this symbol.
+
+        Returns:
+            The symbol's key as a string
+        """
         return str(self.key)
 
     @override
     def partial(self, **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).
+
+        Args:
+            **values: Dictionary mapping symbol names to their values
+
+        Returns:
+            The value for this symbol if available, otherwise the symbol itself
+        """
         if self.key in values:
             return values[self.key]
         return self
 
     @override
     def keys(self) -> 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:
+            A set containing the symbol's key
+        """
         return {self.key}
 
 
 @dataclass(frozen=True, kw_only=True)
 class LazyOperator(LazyValue):
     """
-    A base class for lazy operators.
+    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.
 
-    Such as `Add`, `Sub`, `Mul`, `TrueDiv`, `Pow`, `Neg`, `Pos`, `Abs`, `Mod`, `FloorDiv`.
+    Attributes:
+        left: The left operand of the operation (or the only operand for unary operations)
+        right: The right operand of the operation (None for unary operations)
+
+    Concrete implementations include:
+        Add, Sub, Mul, TrueDiv, Pow, Neg, Pos, Abs, Mod, FloorDiv
     """
 
     left: Any = None
@@ -181,12 +262,37 @@ class LazyOperator(LazyValue):
     @abstractmethod
     def _eval(self, left: Any, right: Any) -> Any:
         """
-        Evaluate the operator with the given values.
+        Evaluate the operator with the given operand values.
+
+        This abstract method must be implemented by concrete operator subclasses
+        to define the specific operation to perform (e.g., addition, multiplication).
+
+        Args:
+            left: The evaluated left operand (or only operand for unary operations)
+            right: The evaluated right operand (may be None for unary operations)
+
+        Returns:
+            The result of applying the operation to the operands
         """
         ...
 
     @override
     def partial(self, **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.
+
+        Args:
+            **values: Dictionary mapping symbol names to their values
+
+        Returns:
+            The result of applying the operation to the partially evaluated operands,
+            which may be a concrete value or another LazyValue if some symbols
+            remain unevaluated
+        """
         if isinstance(self.left, LazyValue):
             left = self.left.partial(**values)
         else:
@@ -201,6 +307,16 @@ class LazyOperator(LazyValue):
 
     @override
     def keys(self) -> 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:
+            A set of strings representing all symbol names required to
+            fully evaluate this operator
+        """
         r = set()
         if isinstance(self.left, LazyValue):
             r |= self.left.keys()

typed_ffmpeg/utils/run.py

@@ -1,27 +1,64 @@
+"""
+Utilities for executing FFmpeg commands and handling command arguments.
+
+This module provides helper functions for formatting command-line arguments,
+filtering default values, and preparing options for command execution.
+"""
+
 import shlex
+from collections.abc import Mapping
 
 from ..schema import Default
 from ..utils.lazy_eval.schema import LazyValue
+from .forzendict import FrozenDict
 
 
 def command_line(args: list[str]) -> str:
     """
-    Get the command line representation of the arguments.
+    Convert a list of command arguments to a properly escaped command-line string.
+
+    This function takes a list of command arguments and converts it to a single
+    string with proper shell escaping applied to each argument. This is useful
+    for logging commands or displaying them to users.
 
     Args:
-        args: The arguments to convert.
+        args: The command arguments to convert to a string
 
     Returns:
-        The command line representation of the arguments.
+        A properly escaped command-line string representation of the arguments
+
+    Example:
+        ```python
+        cmd = ["ffmpeg", "-i", "input file.mp4", "-c:v", "libx264"]
+        print(command_line(cmd))  # 'ffmpeg -i "input file.mp4" -c:v libx264'
+        ```
     """
     return " ".join(shlex.quote(arg) for arg in args)
 
 
 # Filter_Node_Option_Type
 def ignore_default(
-    kwargs: dict[str, str | int | float | bool | Default],
-) -> tuple[tuple[str, str | int | float | bool | LazyValue], ...]:
+    kwargs: Mapping[str, str | int | float | bool | Default],
+) -> FrozenDict[str, str | int | float | bool | LazyValue]:
     """
-    Convert the values of the dictionary to strings.
+    Filter out Default values from a dictionary of options.
+
+    This function is used to process FFmpeg filter options and command arguments,
+    removing any values that are instances of the Default class. This ensures
+    that only explicitly set options are passed to FFmpeg, allowing default values
+    to be applied by FFmpeg itself.
+
+    Args:
+        kwargs: A mapping containing parameter names and values,
+               which may include Default instances
+
+    Returns:
+        An immutable FrozenDict containing only non-Default values
+
+    Example:
+        ```python
+        options = {"width": 1920, "height": 1080, "format": Default("yuv420p")}
+        filtered = ignore_default(options)  # {"width": 1920, "height": 1080}
+        ```
     """
-    return tuple((k, v) for k, v in kwargs.items() if not isinstance(v, Default))
+    return FrozenDict({k: v for k, v in kwargs.items() if not isinstance(v, Default)})

typed_ffmpeg/utils/snapshot.py

@@ -1,3 +1,12 @@
+"""
+Snapshot testing utilities for FFmpeg DAG structures.
+
+This module provides extensions for the syrupy snapshot testing library that
+enable serialization and testing of FFmpeg's Directed Acyclic Graph (DAG)
+structures. It helps in writing tests that verify the correct structure and
+behavior of filter graphs.
+"""
+
 from dataclasses import asdict
 from typing import Optional
 
@@ -14,7 +23,16 @@ from ..dag.schema import Stream
 
 class DAGSnapshotExtenstion(JSONSnapshotExtension):
     """
-    A snapshot extension for the DAG. This extension is used to serialize and match the DAG.
+    A snapshot extension for serializing and testing FFmpeg DAG structures.
+
+    This extension extends the JSON snapshot extension from syrupy to handle
+    the special case of FFmpeg DAG nodes. It converts DAG nodes into a serializable
+    form suitable for snapshot testing by wrapping them in a Stream object and
+    converting to a dictionary.
+
+    This allows for robust testing of filter graph structures and ensures that
+    changes to the graph structure are intentional and documented through
+    snapshot testing.
     """
 
     def serialize(
@@ -25,6 +43,23 @@ class DAGSnapshotExtenstion(JSONSnapshotExtension):
         include: Optional["PropertyFilter"] = None,
         matcher: Optional["PropertyMatcher"] = None,
     ) -> "SerializedData":
+        """
+        Serialize a DAG node for snapshot testing.
+
+        This method converts a DAG node into a serializable format by wrapping
+        it in a Stream object and then converting that to a dictionary. This
+        approach ensures that all relevant properties of the node are captured
+        in the snapshot.
+
+        Args:
+            data: The DAG node to serialize
+            exclude: Optional filter specifying properties to exclude
+            include: Optional filter specifying properties to include
+            matcher: Optional property matcher
+
+        Returns:
+            The serialized representation of the DAG node
+        """
         stream = Stream(node=data)
 
         return super().serialize(asdict(stream))

typed_ffmpeg/utils/typing.py

@@ -1,3 +1,11 @@
+"""
+Typing utilities for enhanced type annotations.
+
+This module provides utilities for improving type annotations and enforcing
+typing conventions within the codebase, offering better support for type checking
+and documentation.
+"""
+
 from typing import TypeVar
 
 V = TypeVar("V")
@@ -5,13 +13,30 @@ V = TypeVar("V")
 
 def override(func: V) -> V:
     """
-    Decorator to indicate overriding a method.
-    the true override method is implemented until in python 3.12
+    Decorator to indicate a method that overrides a method in a superclass.
+
+    This decorator serves as a placeholder until Python 3.12, which introduces
+    a built-in @override decorator. Using this decorator helps with code clarity
+    and can catch errors where a method intended to override a parent class method
+    doesn't actually override anything (e.g., due to a typo in the method name).
 
     Args:
-        func: The function to decorate.
+        func: The function to mark as an override of a superclass method
 
     Returns:
-        The decorated function.
+        The original function, unchanged (the decorator is used only for documentation)
+
+    Example:
+        ```python
+        class Parent:
+            def method(self):
+                pass
+
+
+        class Child(Parent):
+            @override
+            def method(self):  # Correctly overrides Parent.method
+                pass
+        ```
     """
     return func