typed-ffmpeg-compatible 2.6.3__py3-none-any.whl → 2.7.0__py3-none-any.whl

typed_ffmpeg/common/serialize.py

@@ -1,6 +1,14 @@
+"""
+Serialization utilities for FFmpeg filter graphs and components.
+
+This module provides functions for serializing and deserializing FFmpeg filter
+graph components to and from JSON. It handles dataclasses, enums, and other
+custom types used in the typed-ffmpeg library, enabling filter graphs to be
+saved to disk and loaded back.
+"""
+
 from __future__ import annotations
 
-import importlib
 import json
 from dataclasses import fields, is_dataclass
 from enum import Enum
@@ -8,60 +16,128 @@ from functools import partial
 from pathlib import Path
 from typing import Any
 
+from ..utils.forzendict import FrozenDict
+
+CLASS_REGISTRY: dict[str, type[Serializable | Enum]] = {}
+"""
+A registry of classes that have been loaded, and can be deserialized.
+"""
+
 
-def load_class(path: str, strict: bool = True) -> Any:
+def serializable(
+    cls: type[Serializable] | type[Enum],
+) -> type[Serializable] | type[Enum]:
     """
-    Load a class from a string path
+    Register a class with the serialization system.
+    """
+    assert cls.__name__ not in CLASS_REGISTRY, (
+        f"Class {cls.__name__} already registered"
+    )
+    CLASS_REGISTRY[cls.__name__] = cls
+
+    return cls
+
+
+class Serializable:
+    """
+    A base class for all serializable classes.
+    """
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        serializable(cls)
+
+
+def load_class(name: str) -> type[Serializable] | type[Enum]:
+    """
+    Load a class from its name.
+
+    This function looks up a class by its name in the CLASS_REGISTRY. It's used during
+    deserialization to reconstruct objects from their class names.
 
     Args:
-        path: The path to the class.
-        strict: If True, raise an error if the class is not in ffmpeg package.
+        name: The simple class name (e.g., 'FilterNode')
 
     Returns:
-        The class.
+        The class object that can be instantiated
+
+    Raises:
+        AssertionError: If the class name is not found in the registry
+
+    Example:
+        ```python
+        # Load the FilterNode class
+        FilterNode = load_class('FilterNode')
+        # Create an instance
+        node = FilterNode(name='scale', ...)
+        ```
     """
-    if strict:
-        assert path.startswith("ffmpeg."), (
-            f"Only support loading class from ffmpeg package: {path}"
-        )
-
-    module_path, class_name = path.rsplit(".", 1)
-    module = importlib.import_module(module_path)
-    return getattr(module, class_name)
+    assert name in CLASS_REGISTRY, f"Class {name} not registered"
+    return CLASS_REGISTRY[name]
 
 
 def frozen(v: Any) -> Any:
     """
-    Convert the instance to a frozen instance
+    Convert mutable data structures to immutable (frozen) equivalents.
+
+    This function recursively converts lists to tuples and dictionaries to
+    FrozenDict instances, ensuring that the resulting data structure is
+    completely immutable. This is important for dataclasses that are marked
+    as frozen, as they can only contain immutable data.
 
     Args:
-        v: The instance to convert.
+        v: The value to convert, which may be a list, dict, or any other type
 
     Returns:
-        The frozen instance.
+        An immutable version of the input value
+
+    Example:
+        ```python
+        # Convert a nested structure to immutable form
+        frozen_data = frozen(
+            {"options": ["option1", "option2"], "settings": {"key": "value"}}
+        )
+        # Result: FrozenDict with tuple instead of list and nested FrozenDict
+        ```
     """
     if isinstance(v, list):
         return tuple(frozen(i) for i in v)
 
     if isinstance(v, dict):
-        return tuple((key, frozen(value)) for key, value in v.items())
+        return FrozenDict({k: frozen(v) for k, v in v.items()})
 
     return v
 
 
 def object_hook(obj: Any, strict: bool = True) -> Any:
     """
-    Convert the dictionary to an instance
+    Custom JSON object hook for deserializing FFmpeg objects.
+
+    This function is used by the JSON decoder to convert dictionaries into
+    appropriate Python objects during deserialization. It looks for a special
+    '__class__' key that indicates the type of object to create.
 
     Args:
-        obj: The dictionary to convert.
+        obj: A dictionary from the JSON parser
+        strict: If True, only allow loading classes from the ffmpeg package
 
     Returns:
-        The instance.
+        Either the original dictionary or an instance of the specified class
+
+    Example:
+        ```python
+        # A JSON object with class information
+        json_obj = {
+            "__class__": "FilterNode",
+            "name": "scale",
+            "kwargs": {"width": 1280, "height": 720},
+        }
+        # Will be converted to a FilterNode instance
+        ```
     """
     if isinstance(obj, dict):
         if obj.get("__class__"):
-            cls = load_class(obj.pop("__class__"), strict=strict)
+            cls = load_class(obj.pop("__class__"))
 
             if is_dataclass(cls):
                 # NOTE: in our application, the dataclass is always frozen
@@ -74,13 +150,26 @@ def object_hook(obj: Any, strict: bool = True) -> Any:
 
 def loads(raw: str, strict: bool = True) -> Any:
     """
-    Deserialize the JSON string to an instance
+    Deserialize a JSON string into Python objects with proper class types.
+
+    This function parses a JSON string and reconstructs the original Python
+    objects, including dataclasses and enums, based on class information
+    embedded in the JSON.
 
     Args:
-        raw: The JSON string to deserialize.
+        raw: The JSON string to deserialize
+        strict: If True, only allow loading classes from the ffmpeg package
 
     Returns:
-        The deserialized instance.
+        The deserialized Python object with proper types
+
+    Example:
+        ```python
+        # Deserialize a filter graph from JSON
+        json_str = '{"__class__": "FilterNode", "name": "scale", ...}'
+        filter_node = loads(json_str)
+        # filter_node is now a FilterNode instance
+        ```
     """
     object_hook_strict = partial(object_hook, strict=strict)
 
@@ -89,16 +178,29 @@ def loads(raw: str, strict: bool = True) -> Any:
 
 def to_dict_with_class_info(instance: Any) -> Any:
     """
-    Convert the instance to a dictionary with class information
+    Convert Python objects to dictionaries with embedded class information.
+
+    This function recursively converts Python objects to dictionaries, lists,
+    and primitive types suitable for JSON serialization. For dataclasses and
+    enums, it adds a '__class__' key with the fully qualified class name,
+    allowing them to be reconstructed during deserialization.
 
     Args:
-        instance: The instance to convert.
+        instance: The Python object to convert
 
     Returns:
-        The dictionary with class information
+        A JSON-serializable representation with embedded class information
+
+    Example:
+        ```python
+        # Convert a FilterNode to a serializable dict
+        filter_node = FilterNode(name='scale', ...)
+        serializable = to_dict_with_class_info(filter_node)
+        # serializable now contains class information and all attributes
+        ```
     """
 
-    if isinstance(instance, dict):
+    if isinstance(instance, dict | FrozenDict):
         return {k: to_dict_with_class_info(v) for k, v in instance.items()}
     elif isinstance(instance, list):
         return [to_dict_with_class_info(v) for v in instance]
@@ -108,7 +210,7 @@ def to_dict_with_class_info(instance: Any) -> Any:
         return str(instance)
     elif is_dataclass(instance):
         return {
-            "__class__": f"{instance.__class__.__module__}.{instance.__class__.__name__}",
+            "__class__": instance.__class__.__name__,
             **{
                 k.name: to_dict_with_class_info(getattr(instance, k.name))
                 for k in fields(instance)
@@ -116,7 +218,7 @@ def to_dict_with_class_info(instance: Any) -> Any:
         }
     elif isinstance(instance, Enum):
         return {
-            "__class__": f"{instance.__class__.__module__}.{instance.__class__.__name__}",
+            "__class__": instance.__class__.__name__,
             "value": instance.value,
         }
     return instance
@@ -125,13 +227,26 @@ def to_dict_with_class_info(instance: Any) -> Any:
 # Serialization
 def dumps(instance: Any) -> str:
     """
-    Serialize the instance to a JSON string
+    Serialize a Python object to a JSON string with class information.
+
+    This function converts a Python object (including dataclasses, enums,
+    and other custom types) to a JSON string that includes class information,
+    allowing it to be deserialized back into the original object types.
 
     Args:
-        instance: The instance to serialize.
+        instance: The Python object to serialize
 
     Returns:
-        The serialized instance.
+        A JSON string representation of the object with class information
+
+    Example:
+        ```python
+        # Serialize a filter graph to JSON
+        filter_node = FilterNode(name='scale', ...)
+        json_str = dumps(filter_node)
+        # json_str can be saved to a file and later deserialized
+        # with loads() to reconstruct the original object
+        ```
     """
     obj = to_dict_with_class_info(instance)
     return json.dumps(obj, indent=2)

typed_ffmpeg/dag/__init__.py

@@ -1,3 +1,16 @@
+"""
+Directed Acyclic Graph (DAG) implementation for FFmpeg filter chains.
+
+This package provides the core components for representing FFmpeg filter chains
+as directed acyclic graphs. It includes classes for different types of nodes
+(inputs, filters, outputs) and streams, as well as utilities for validating,
+compiling, and manipulating these graphs.
+
+The DAG structure enables type-safe construction and validation of complex
+FFmpeg filter chains, ensuring that the resulting FFmpeg commands are valid
+and correctly structured.
+"""
+
 from .nodes import (
     FilterableStream,
     FilterNode,

typed_ffmpeg/dag/compile.py

@@ -1,3 +1,12 @@
+"""
+Compiles FFmpeg filter graphs into command-line arguments.
+
+This module provides functionality to convert the internal DAG (Directed Acyclic Graph)
+representation of an FFmpeg filter chain into the actual command-line arguments
+that would be passed to FFmpeg. It traverses the graph in the correct order,
+handling global options, inputs, complex filtergraphs, and outputs.
+"""
+
 from __future__ import annotations
 
 from .context import DAGContext
@@ -8,14 +17,40 @@ from .validate import validate
 
 def compile(stream: Stream, auto_fix: bool = True) -> list[str]:
     """
-    Compile the stream into a list of arguments.
+    Compile a stream into a list of FFmpeg command-line arguments.
+
+    This function takes a Stream object representing an FFmpeg filter graph
+    and converts it into a list of command-line arguments that can be passed
+    to FFmpeg. It processes the graph in the correct order:
+    1. Global nodes (general FFmpeg options)
+    2. Input nodes (input files and their options)
+    3. Filter nodes (combined into a -filter_complex argument)
+    4. Output nodes (output files and their options)
+
+    The function validates the graph before compilation to ensure it's properly
+    formed. If auto_fix is enabled, it will attempt to fix common issues.
 
     Args:
-        stream: The stream to compile.
-        auto_fix: Whether to automatically fix the stream.
+        stream: The Stream object to compile into arguments
+        auto_fix: Whether to automatically fix issues in the stream
+                 (e.g., reconnecting disconnected nodes)
 
     Returns:
-        The list of arguments.
+        A list of strings representing FFmpeg command-line arguments
+
+    Example:
+        ```python
+        # Create a simple video scaling filter graph
+        input_stream = ffmpeg.input("input.mp4")
+        scaled = input_stream.filter("scale", 1280, 720)
+        output_stream = scaled.output("output.mp4")
+
+        # Compile to FFmpeg arguments
+        args = ffmpeg.dag.compile(output_stream)
+        print(
+            args
+        )  # ['ffmpeg', '-i', 'input.mp4', '-filter_complex', '...', 'output.mp4']
+        ```
     """
 
     stream = validate(stream, auto_fix=auto_fix)

typed_ffmpeg/dag/context.py

@@ -1,3 +1,12 @@
+"""
+Context management for FFmpeg filter graph traversal and manipulation.
+
+This module provides the DAGContext class, which represents the context
+of a Directed Acyclic Graph (DAG) of FFmpeg filter nodes. It provides methods
+for traversing, manipulating, and rendering the graph structure, and is used
+during graph validation and command-line compilation.
+"""
+
 from __future__ import annotations
 
 from collections import defaultdict
@@ -14,13 +23,17 @@ T = TypeVar("T")
 
 def _remove_duplicates(seq: list[T]) -> list[T]:
     """
-    Remove duplicates from a list while preserving order.
+    Remove duplicates from a list while preserving the original order.
+
+    This helper function processes a list and removes any duplicate elements
+    while maintaining the relative ordering of elements. The first occurrence
+    of each element is kept, subsequent duplicates are removed.
 
     Args:
-        seq: The list to remove duplicates from.
+        seq: The list to remove duplicates from
 
     Returns:
-        The list with duplicates removed.
+        A new list with duplicates removed, preserving the original order
     """
     seen = set()
     output = []
@@ -35,13 +48,19 @@ def _remove_duplicates(seq: list[T]) -> list[T]:
 
 def _collect(node: Node) -> tuple[list[Node], list[Stream]]:
     """
-    Collect all nodes and streams that are upstreamed to the given node
+    Recursively collect all nodes and streams in the upstream path of a given node.
+
+    This function traverses the graph starting from the given node and collects
+    all nodes and streams that are upstream (input sources) to the node. The
+    traversal is performed recursively to ensure all dependencies are captured.
 
     Args:
-        node: The node to collect from.
+        node: The starting node to collect dependencies from
 
     Returns:
-        A tuple of all nodes and streams that are upstreamed to the given node.
+        A tuple containing two lists:
+        - A list of all nodes in the upstream path (including the starting node)
+        - A list of all streams connecting these nodes
     """
     nodes, streams = [node], [*node.inputs]
 
@@ -56,34 +75,53 @@ def _collect(node: Node) -> tuple[list[Node], list[Stream]]:
 @dataclass(frozen=True, kw_only=True)
 class DAGContext:
     """
-    A context for a directed acyclic graph (DAG).
+    Context class for working with a Directed Acyclic Graph (DAG) of FFmpeg filter nodes.
+
+    This immutable class provides methods and properties for analyzing, traversing,
+    and manipulating a filter graph. It maintains information about nodes and streams
+    in the graph, their relationships, and provides efficient lookups for graph operations.
+
+    The context is built from a "root" node (typically an output node) and captures all
+    upstream dependencies (input nodes, filter nodes, and connecting streams).
     """
 
     node: Node
     """
     The root node (the destination) of the DAG.
+
+    This is typically an output node where the graph traversal begins.
+    All nodes collected in the context are upstream from this node.
     """
 
     nodes: tuple[Node, ...]
     """
-    All nodes in the graph.
+    All nodes in the graph as an immutable tuple.
+
+    This includes the root node and all upstream nodes (inputs, filters)
+    that contribute to the filter graph.
     """
 
     streams: tuple[Stream, ...]
     """
-    All streams in the graph.
+    All streams in the graph as an immutable tuple.
+
+    These streams represent the connections between nodes in the filter graph.
     """
 
     @classmethod
     def build(cls, node: Node) -> DAGContext:
         """
-        create a DAG context based on the given node
+        Create a DAG context by traversing the graph from the specified root node.
+
+        This factory method builds a complete DAGContext by recursively collecting
+        all nodes and streams that are upstream from the specified node. It removes
+        duplicates to ensure each node and stream is represented only once in the context.
 
         Args:
-            node: The root node of the DAG.
+            node: The root node to build the context from (typically an output node)
 
         Returns:
-            A DAG context based on the given node.
+            A fully initialized DAGContext containing all nodes and streams in the graph
         """
         nodes, streams = _collect(node)
 
@@ -96,14 +134,29 @@ class DAGContext:
     @cached_property
     def all_nodes(self) -> list[Node]:
         """
-        All nodes in the graph sorted by the number of upstream nodes.
+        Get all nodes in the graph sorted by their position in the processing chain.
+
+        This property returns a list of all nodes in the graph, sorted by the number
+        of upstream nodes. This ensures that nodes earlier in the processing chain
+        (closer to inputs) come before nodes later in the chain (closer to outputs).
+
+        Returns:
+            A sorted list of all nodes in the graph
         """
         return sorted(self.nodes, key=lambda node: len(node.upstream_nodes))
 
     @cached_property
     def all_streams(self) -> list[Stream]:
         """
-        All streams in the graph sorted by the number of upstream nodes and the index of the stream.
+        Get all streams in the graph sorted by their position in the processing chain.
+
+        This property returns a list of all streams in the graph, sorted first by the
+        number of upstream nodes of the source node, and then by the stream index.
+        This ensures a consistent and logical ordering of streams based on their
+        position in the processing pipeline.
+
+        Returns:
+            A sorted list of all streams in the graph
         """
         return sorted(
             self.streams,
@@ -113,7 +166,15 @@ class DAGContext:
     @cached_property
     def outgoing_nodes(self) -> dict[Stream, list[tuple[Node, int]]]:
         """
-        A dictionary of outgoing nodes for each stream.
+        Get a mapping of streams to the nodes they connect to.
+
+        This property builds a dictionary that maps each stream to a list of
+        tuples containing (node, input_index) pairs. Each tuple represents a node
+        that receives this stream as input, along with the index position where
+        the stream connects to that node.
+
+        Returns:
+            A dictionary mapping streams to their destination nodes and connection indices
         """
         outgoing_nodes: dict[Stream, list[tuple[Node, int]]] = defaultdict(list)
 
@@ -126,7 +187,14 @@ class DAGContext:
     @cached_property
     def outgoing_streams(self) -> dict[Node, list[Stream]]:
         """
-        A dictionary of outgoing streams for each node.
+        Get a mapping of nodes to the streams they output.
+
+        This property builds a dictionary that maps each node to a list of streams
+        that originate from it. This is particularly useful for determining all the
+        outputs from a specific filter or input node.
+
+        Returns:
+            A dictionary mapping nodes to their output streams
         """
 
         outgoing_streams: dict[Node, list[Stream]] = defaultdict(list)
@@ -139,7 +207,18 @@ class DAGContext:
     @cached_property
     def node_labels(self) -> dict[Node, str]:
         """
-        A dictionary of outgoing streams for each node.
+        Get a mapping of nodes to their string labels used in FFmpeg filter graphs.
+
+        This property assigns a unique label to each node in the graph, following
+        the FFmpeg filter graph labeling conventions:
+        - Input nodes are labeled with sequential numbers (0, 1, 2...)
+        - Filter nodes are labeled with 's' followed by a number (s0, s1, s2...)
+        - Output nodes are labeled as 'out'
+
+        These labels are used when generating the filter_complex argument for FFmpeg.
+
+        Returns:
+            A dictionary mapping nodes to their string labels
         """
 
         input_node_index = 0
@@ -161,26 +240,38 @@ class DAGContext:
     @override
     def get_outgoing_nodes(self, stream: Stream) -> list[tuple[Node, int]]:
         """
-        Get all outgoing nodes of the stream.
+        Get all nodes that receive a specific stream as input.
+
+        This method returns a list of (node, index) tuples representing the nodes
+        that receive the given stream as input, along with the input index position
+        where the stream connects to each node.
 
         Args:
-            stream: The stream to get the outgoing nodes of.
+            stream: The stream to get the destination nodes for
 
         Returns:
-            The outgoing nodes of the stream.
+            A list of (node, input_index) tuples for nodes that receive this stream
         """
         return self.outgoing_nodes[stream]
 
     @override
     def get_node_label(self, node: Node) -> str:
         """
-        Get the label of the node.
+        Get the string label for a specific node in the filter graph.
+
+        This method returns the label assigned to the node, which is used in FFmpeg
+        filter graph notation. The label format depends on the node type:
+        - Input nodes: sequential numbers (0, 1, 2...)
+        - Filter nodes: 's' prefix followed by a number (s0, s1, s2...)
 
         Args:
-            node: The node to get the label of.
+            node: The node to get the label for (must be an InputNode or FilterNode)
 
         Returns:
-            The label of the node.
+            The string label for the node
+
+        Raises:
+            AssertionError: If the node is not an InputNode or FilterNode
         """
 
         assert isinstance(node, (InputNode, FilterNode)), (
@@ -191,25 +282,42 @@ class DAGContext:
     @override
     def get_outgoing_streams(self, node: Node) -> list[Stream]:
         """
-        Extract all node's outgoing streams from the given set of streams, Because a node only know its incoming streams.
+        Get all streams that originate from a specific node.
+
+        This method returns all streams where the given node is the source.
+        It's particularly useful because nodes natively only track their inputs,
+        not their outputs, so this context method provides a way to look up
+        a node's outputs.
 
         Args:
-            node: The node to get the outgoing streams of.
+            node: The node to get the output streams for
 
         Returns:
-            The outgoing streams of the node.
+            A list of streams that originate from this node
         """
         return self.outgoing_streams[node]
 
     def render(self, obj: Any) -> Any:
         """
-        Render the object to a string.
+        Recursively convert graph objects to a human-readable representation.
+
+        This method processes arbitrary objects, with special handling for graph
+        elements like nodes and streams. It converts them to a readable string format
+        that includes node labels. It recursively handles nested structures like
+        lists, tuples, and dictionaries.
+
+        This is primarily used for debugging, logging, and visualization purposes.
 
         Args:
-            obj: The object to render.
+            obj: The object to render, which may be a Node, Stream, or a container
+                 with these objects nested inside
 
         Returns:
-            The rendered object.
+            The rendered representation of the object:
+            - For nodes: "Node(repr#label)"
+            - For streams: "Stream(node_repr#label#index)"
+            - For containers: recursively rendered contents
+            - For other objects: the original object unchanged
         """
 
         if isinstance(obj, (list, tuple)):

typed_ffmpeg/dag/factory.py

@@ -1,3 +1,11 @@
+"""
+Factory functions for creating FFmpeg filter nodes.
+
+This module provides factory functions that create filter nodes based on
+FFmpeg filter definitions. These factories handle the evaluation of automatic
+parameters and the conversion of input/output typing specifications.
+"""
+
 import re
 from typing import Any
 
@@ -10,6 +18,25 @@ from .nodes import FilterableStream, FilterNode
 def filter_node_factory(
     ffmpeg_filter_def: FFMpegFilterDef, *inputs: FilterableStream, **kwargs: Any
 ) -> FilterNode:
+    """
+    Create a FilterNode from an FFmpeg filter definition.
+
+    This function creates a FilterNode based on the provided FFmpeg filter definition.
+    It handles the evaluation of Auto parameters and the conversion of input/output
+    typing specifications from the filter definition.
+
+    Args:
+        ffmpeg_filter_def: The FFmpeg filter definition to create a node from
+        *inputs: The input streams to connect to the filter
+        **kwargs: Filter-specific parameters as keyword arguments
+
+    Returns:
+        A FilterNode configured according to the filter definition
+
+    Note:
+        This function is primarily used internally by the filter generation system
+        to create filter nodes from the FFmpeg filter definitions.
+    """
     for k, v in kwargs.items():
         if isinstance(v, Auto):
             kwargs[k] = eval(