or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mddelta.mddifference.mdextract.mdhashing.mdindex.mdsearch.md
tile.json

tessl/pypi-deepdiff

Deep Difference and Search of any Python object/data with delta and hash capabilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/deepdiff@8.6.x

To install, run

npx @tessl/cli install tessl/pypi-deepdiff@8.6.0

index.mddocs/

DeepDiff

DeepDiff is a comprehensive Python library for analyzing differences, searching, and hashing complex data structures and objects. It provides advanced comparison capabilities beyond basic equality checks, offering detailed reporting of changes between dictionaries, lists, strings, and any Python objects. The library features multiple core modules for deep difference analysis, object searching, content-based hashing, delta storage and application, and path-based extraction from nested structures.

Package Information

  • Package Name: deepdiff
  • Language: Python
  • Installation: pip install deepdiff
  • Optional Dependencies: pip install deepdiff[cli] for command-line usage, pip install deepdiff[optimize] for performance optimizations

Core Imports

from deepdiff import DeepDiff, DeepSearch, DeepHash, Delta, extract, parse_path, grep

Basic Usage

from deepdiff import DeepDiff, DeepSearch, DeepHash, Delta, extract

# Deep difference analysis
t1 = {"name": "John", "age": 30, "hobbies": ["reading", "gaming"]}
t2 = {"name": "John", "age": 31, "hobbies": ["reading", "coding"]}

diff = DeepDiff(t1, t2)
print(diff)
# {'values_changed': {"root['age']": {'old_value': 30, 'new_value': 31}}, 
#  'iterable_item_added': {"root['hobbies'][1]": 'coding'}, 
#  'iterable_item_removed': {"root['hobbies'][1]": 'gaming'}}

# Deep search within nested structures
data = {"users": [{"id": 1, "name": "John"}, {"id": 2, "name": "Jane"}]}
search = DeepSearch(data, "John")
print(search)
# {'matched_values': {"root['users'][0]['name']"}}

# Content-based hashing
hash1 = DeepHash({"a": 1, "b": 2})
hash2 = DeepHash({"b": 2, "a": 1})  # Same content, different order
print(hash1 == hash2)  # True

# Delta creation and application
delta = Delta(diff)
t3 = delta + t1  # Apply delta to original object
print(t3 == t2)  # True

# Path-based extraction
nested_data = {"level1": {"level2": {"target": "found"}}}
value = extract(nested_data, "root['level1']['level2']['target']")
print(value)  # "found"

Architecture

The DeepDiff library is built around five core capabilities that work together to provide comprehensive object analysis:

  • DeepDiff: The primary comparison engine that analyzes differences between objects with extensive customization options
  • DeepSearch: Search functionality for finding objects within nested data structures
  • DeepHash: Content-based hashing system that generates consistent hashes regardless of object organization
  • Delta: Difference storage and application system for creating patches and applying changes
  • Extract: Path-based navigation system for retrieving values from deeply nested structures

All classes inherit from common base classes providing serialization, distance calculation, and other shared functionality.

Capabilities

Deep Difference Analysis

Comprehensive comparison of Python objects with detailed change reporting. Supports extensive customization through 40+ parameters including type handling, path filtering, numerical precision, and output formatting.

class DeepDiff:
    def __init__(
        self,
        t1: Any,
        t2: Any,
        ignore_order: bool = False,
        ignore_string_case: bool = False,
        ignore_numeric_type_changes: bool = False,
        ignore_type_in_groups: List[Tuple[type, ...]] = None,
        significant_digits: int = None,
        exclude_paths: List[str] = None,
        exclude_regex_paths: List[str] = None,
        exclude_types: List[type] = None,
        include_paths: List[str] = None,
        custom_operators: List = None,
        view: str = 'text',
        verbose_level: int = 1,
        **kwargs
    ): ...
    
    def get_stats(self) -> Dict[str, Any]: ...
    def get_affected_paths(self) -> List[str]: ...
    def to_json(self) -> str: ...
    def from_json(self, json_string: str) -> 'DeepDiff': ...

Deep Difference Analysis

Deep Search and Grep

Search for objects within nested data structures using flexible matching criteria. Includes both class-based search and pipe-friendly grep functionality.

class DeepSearch:
    def __init__(
        self,
        obj: Any,
        item: Any,
        exclude_paths: List[str] = None,
        exclude_regex_paths: List[str] = None,
        exclude_types: List[type] = None,
        verbose_level: int = 1,
        case_sensitive: bool = True,
        match_string: bool = False,
        use_regexp: bool = False,
        **kwargs
    ): ...
    
    def get_stats(self) -> Dict[str, Any]: ...
    def get_paths(self) -> List[str]: ...

def grep(item: Any, **kwargs) -> Callable: ...

Deep Search and Grep

Deep Hashing

Content-based hashing that generates consistent hashes for objects regardless of key ordering or minor structural differences. Supports custom hash functions and extensive filtering options.

class DeepHash:
    def __init__(
        self,
        obj: Any,
        hasher: Any = None,
        ignore_type_in_groups: List[Tuple[type, ...]] = None,
        ignore_encoding_errors: bool = False,
        ignore_numeric_type_changes: bool = False,
        significant_digits: int = None,
        exclude_types: List[type] = None,
        exclude_paths: List[str] = None,
        **kwargs
    ): ...
    
    def get(self, path: str = None) -> str: ...
    def hexdigest(self) -> str: ...

Deep Hashing

Delta Operations

Store differences as delta objects and apply them to create new objects or modify existing ones. Supports multiple serialization formats and bidirectional operations.

class Delta:
    def __init__(
        self,
        diff: Union['DeepDiff', Dict],
        mutate: bool = False,
        log_errors: bool = False,
        safe_to_import: List[str] = None,
        bidirectional: bool = False
    ): ...
    
    def dump(self, file_path: str, **kwargs) -> None: ...
    def dumps(self, **kwargs) -> str: ...
    def load(self, file_path: str, **kwargs) -> 'Delta': ...
    def loads(self, string: str, **kwargs) -> 'Delta': ...
    def apply_to(self, obj: Any) -> Any: ...
    def create_new_from(self, obj: Any) -> Any: ...

Delta Operations

Path Extraction and Parsing

Navigate and extract values from deeply nested Python objects using string-based path notation. Includes both extraction and path parsing utilities.

def extract(obj: Any, path: Union[str, List]) -> Any:
    """Extract item from nested object using path notation."""

def parse_path(path: str) -> List:
    """Parse path string to machine-readable format."""

Path Operations

Command Line Interface

Full-featured CLI providing access to all core functionality through command-line tools with extensive options and output formatting.

# Compare objects from files or command line
deep diff file1.json file2.json

# Search within objects  
deep grep "search_term" data.json

# Extract values using paths
deep extract "root['key']['subkey']" data.json

# Apply delta patches
deep patch original.json delta.json

Command Line Interface

Exception Classes

class DeltaError(ValueError):
    """Exception raised during Delta operations."""

class DeltaNumpyOperatorOverrideError(ValueError):
    """Exception raised when Delta NumPy operator override fails."""

class PathExtractionError(ValueError):
    """Exception raised during path extraction operations."""

class RootCanNotBeModified(ValueError):
    """Exception raised when attempting to modify root in path operations."""

class UnsupportedFormatErr(TypeError):
    """Exception raised for unsupported serialization formats."""

class CannotCompare(Exception):
    """Exception raised when objects cannot be compared."""

class DoesNotExist(Exception):
    """Exception raised when a required object does not exist."""

Common Types

# Result types used across multiple modules
TreeResult = Dict[str, Any]
DiffLevel = Dict[str, Any]

# Path types
PathStr = str
PathList = List[Union[str, int]]

# Comparison customization types
CustomOperator = Callable
TypeGroup = Tuple[type, ...]
HashFunction = Callable[[Any], str]