dir-content-diff 1.13.0__tar.gz → 1.14.1__tar.gz

{dir_content_diff-1.13.0 → dir_content_diff-1.14.1}/.github/workflows/commitlint.yml

@@ -11,8 +11,8 @@ jobs:
     env:
       PR_TITLE: ${{ github.event.pull_request.title }}
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-node@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
           node-version: '20'
       - run: npm install -g --force commitlint @commitlint/cli commitlint-plugin-cleanfeet

{dir_content_diff-1.13.0 → dir_content_diff-1.14.1}/.github/workflows/publish-sdist.yml

@@ -10,7 +10,7 @@ jobs:
     name: Build and publish on PyPI
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Set up Python 3.10
         uses: actions/setup-python@v6
         with:

{dir_content_diff-1.13.0 → dir_content_diff-1.14.1}/.github/workflows/run-tox.yml

@@ -24,7 +24,7 @@ jobs:
             min_versions: "min_versions"
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v6
       with:
@@ -36,7 +36,7 @@ jobs:
       run: |
         sudo apt-get install -y poppler-utils imagemagick
     - name: Cache tox and precommit environments
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       with:
         path: |
           .tox
@@ -58,7 +58,7 @@ jobs:
         pip install tox
         tox run -e min_versions
     - name: JUnit Report Action
-      uses: mikepenz/action-junit-report@v5
+      uses: mikepenz/action-junit-report@v6
       if: always() # always run even if the previous step fails
       with:
         report_paths: 'reports/pytest-*.xml'
@@ -81,7 +81,7 @@ jobs:
       env:
         CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
     - name: Upload test artifacts
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v6
       if: always()
       with:
         name: tests-${{ matrix.python-version }}-${{ matrix.min_versions }}

{dir_content_diff-1.13.0 → dir_content_diff-1.14.1}/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [1.14.1](https://github.com/BlueBrain/dir-content-diff/compare/1.14.0..1.14.1)
+
+> 15 January 2026
+
+### Chores And Housekeeping
+
+- Bump copyright (Adrien Berchet - [#99](https://github.com/BlueBrain/dir-content-diff/pull/99))
+
+### Documentation Changes
+
+- Change theme to Furo because BBP theme is deprecated (Adrien Berchet - [#100](https://github.com/BlueBrain/dir-content-diff/pull/100))
+
+## [1.14.0](https://github.com/BlueBrain/dir-content-diff/compare/1.13.0..1.14.0)
+
+> 13 September 2025
+
+### New Features
+
+- Add parallel iteration over compared files (Adrien Berchet - [#89](https://github.com/BlueBrain/dir-content-diff/pull/89))
+
+### Documentation Changes
+
+- Improve README to describe parallel execution (Adrien Berchet - [#91](https://github.com/BlueBrain/dir-content-diff/pull/91))
+
+### Refactoring and Updates
+
+- Reorganize the code (Adrien Berchet - [#90](https://github.com/BlueBrain/dir-content-diff/pull/90))
+
 ## [1.13.0](https://github.com/BlueBrain/dir-content-diff/compare/1.12.1..1.13.0)
 
 > 12 September 2025

{dir_content_diff-1.13.0/dir_content_diff.egg-info → dir_content_diff-1.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dir-content-diff
-Version: 1.13.0
+Version: 1.14.1
 Summary: Simple tool to compare directory contents.
 Author: Blue Brain Project, EPFL
 License: Apache License 2.0
@@ -40,7 +40,7 @@ Requires-Dist: pynrrd<1.1,>=0.4; extra == "all-comparators"
 Provides-Extra: docs
 Requires-Dist: myst_parser; extra == "docs"
 Requires-Dist: sphinx; extra == "docs"
-Requires-Dist: sphinx-bluebrain-theme; extra == "docs"
+Requires-Dist: furo; extra == "docs"
 Provides-Extra: test
 Requires-Dist: dicttoxml>=1.7.16; extra == "test"
 Requires-Dist: matplotlib>=3.4; extra == "test"
@@ -76,7 +76,7 @@ Dynamic: provides-extra
 This project provides simple tools to compare the content of a directory against a reference
 directory.
 
-This is useful to check the results of a process that generate several files, like a luigi
+This is useful to check the results of a process that generates several files, like a luigi
 workflow for example.
 
 
@@ -102,6 +102,8 @@ the files, so it is not able to report which values are different.
 
 ### Compare two directories
 
+#### Basic Directory Comparison
+
 Let's compare two directories with the following structures:
 
 ```bash
@@ -142,6 +144,8 @@ was detected. As mentioned previously, this is because `dir-content-diff` is onl
 in the compared directory that are also present in the reference directory, so the file
 `sub_file_3.b` is just ignored in this case.
 
+#### Using Custom Comparators
+
 If ``reference_dir/file_1.c`` is the following JSON-like file:
 
 ```json
@@ -183,6 +187,8 @@ The previous code will output the following dictionary:
 }
 ```
 
+#### Assertion-based Comparison
+
 It is also possible to check whether the two directories are equal or not with the following code:
 
 ```python
@@ -201,7 +207,9 @@ Changed the value of '[a]' from 1 to 2.
 Changed the value of '[b][0]' from 1 to 10.
 ```
 
-Finally, the comparators have parameters that can be passed either to be used for all files of a
+#### Advanced Configuration Options
+
+The comparators have parameters that can be passed either to be used for all files of a
 given extension or only for a specific file:
 
 ```python
@@ -229,6 +237,8 @@ dir_content_diff.assert_equal_trees(
 
 Each comparator has different arguments that are detailed in the documentation.
 
+##### File-specific Comparators
+
 It's also possible to specify a arbitrary comparator for a specific file:
 
 ```python
@@ -240,6 +250,8 @@ specific_args = {
 }
 ```
 
+##### Pattern-based Configuration
+
 Another possibility is to use regular expressions to associate specific arguments to
 a set of files:
 
@@ -252,7 +264,9 @@ specific_args = {
 }
 ```
 
-And last but not least, it's possible to filter files from the reference directory (for example
+##### File Filtering
+
+Last but not least, it's possible to filter files from the reference directory (for example
 because the reference directory contains temporary files that should not be compared). For
 example, the following code will ignore all files whose name does not start with `file_` and does
 not ends with `_tmp.yaml`:
@@ -269,6 +283,73 @@ dir_content_diff.compare_trees(
 ```
 
 
+### Parallel Execution
+
+By default, `dir-content-diff` runs file comparisons sequentially. However, for improved performance when comparing large numbers of files, parallel execution is available using either thread-based or process-based concurrency.
+
+#### Configuration Options
+
+Parallel execution can be configured using the following parameters:
+
+- **`executor_type`**: Controls the type of parallel execution:
+  - `"sequential"` (default): No parallel execution, files are compared one by one
+  - `"thread"`: Uses `ThreadPoolExecutor` (recommended for I/O-bound tasks)
+  - `"process"`: Uses `ProcessPoolExecutor` (recommended for CPU-intensive comparisons)
+
+- **`max_workers`**: Maximum number of worker threads/processes. If `None` (default), it defaults to `min(32, (os.cpu_count() or 1) + 4)`.
+
+#### Usage Examples
+
+Enable thread-based parallel execution:
+
+```python
+import dir_content_diff
+
+dir_content_diff.compare_trees(
+    "reference_dir",
+    "compared_dir",
+    executor_type="thread",
+    max_workers=8
+)
+```
+
+Enable process-based parallel execution with automatic worker count:
+
+```python
+import dir_content_diff
+
+dir_content_diff.compare_trees(
+    "reference_dir",
+    "compared_dir",
+    executor_type="process"
+)
+```
+
+Using a configuration object:
+
+```python
+import dir_content_diff
+
+config = dir_content_diff.ComparisonConfig(
+    executor_type="thread",
+    max_workers=4
+)
+
+dir_content_diff.compare_trees(
+    "reference_dir",
+    "compared_dir",
+    config=config
+)
+```
+
+#### Performance Considerations
+
+- **Thread-based execution** (`executor_type="thread"`) is generally recommended for most use cases as file comparisons are typically I/O-bound operations
+- **Process-based execution** (`executor_type="process"`) may be beneficial when using computationally intensive comparators or when dealing with very large files
+- Parallel execution is automatically disabled for single file comparisons and falls back to sequential execution when only one file needs to be compared
+- The optimal number of workers depends on your system's capabilities and the nature of your files; too many workers may actually decrease performance due to overhead
+
+
 ### Export formatted data
 
 Some comparators have to format the data before comparing them. For example, if one wants to

{dir_content_diff-1.13.0 → dir_content_diff-1.14.1}/README.md

@@ -10,7 +10,7 @@
 This project provides simple tools to compare the content of a directory against a reference
 directory.
 
-This is useful to check the results of a process that generate several files, like a luigi
+This is useful to check the results of a process that generates several files, like a luigi
 workflow for example.
 
 
@@ -36,6 +36,8 @@ the files, so it is not able to report which values are different.
 
 ### Compare two directories
 
+#### Basic Directory Comparison
+
 Let's compare two directories with the following structures:
 
 ```bash
@@ -76,6 +78,8 @@ was detected. As mentioned previously, this is because `dir-content-diff` is onl
 in the compared directory that are also present in the reference directory, so the file
 `sub_file_3.b` is just ignored in this case.
 
+#### Using Custom Comparators
+
 If ``reference_dir/file_1.c`` is the following JSON-like file:
 
 ```json
@@ -117,6 +121,8 @@ The previous code will output the following dictionary:
 }
 ```
 
+#### Assertion-based Comparison
+
 It is also possible to check whether the two directories are equal or not with the following code:
 
 ```python
@@ -135,7 +141,9 @@ Changed the value of '[a]' from 1 to 2.
 Changed the value of '[b][0]' from 1 to 10.
 ```
 
-Finally, the comparators have parameters that can be passed either to be used for all files of a
+#### Advanced Configuration Options
+
+The comparators have parameters that can be passed either to be used for all files of a
 given extension or only for a specific file:
 
 ```python
@@ -163,6 +171,8 @@ dir_content_diff.assert_equal_trees(
 
 Each comparator has different arguments that are detailed in the documentation.
 
+##### File-specific Comparators
+
 It's also possible to specify a arbitrary comparator for a specific file:
 
 ```python
@@ -174,6 +184,8 @@ specific_args = {
 }
 ```
 
+##### Pattern-based Configuration
+
 Another possibility is to use regular expressions to associate specific arguments to
 a set of files:
 
@@ -186,7 +198,9 @@ specific_args = {
 }
 ```
 
-And last but not least, it's possible to filter files from the reference directory (for example
+##### File Filtering
+
+Last but not least, it's possible to filter files from the reference directory (for example
 because the reference directory contains temporary files that should not be compared). For
 example, the following code will ignore all files whose name does not start with `file_` and does
 not ends with `_tmp.yaml`:
@@ -203,6 +217,73 @@ dir_content_diff.compare_trees(
 ```
 
 
+### Parallel Execution
+
+By default, `dir-content-diff` runs file comparisons sequentially. However, for improved performance when comparing large numbers of files, parallel execution is available using either thread-based or process-based concurrency.
+
+#### Configuration Options
+
+Parallel execution can be configured using the following parameters:
+
+- **`executor_type`**: Controls the type of parallel execution:
+  - `"sequential"` (default): No parallel execution, files are compared one by one
+  - `"thread"`: Uses `ThreadPoolExecutor` (recommended for I/O-bound tasks)
+  - `"process"`: Uses `ProcessPoolExecutor` (recommended for CPU-intensive comparisons)
+
+- **`max_workers`**: Maximum number of worker threads/processes. If `None` (default), it defaults to `min(32, (os.cpu_count() or 1) + 4)`.
+
+#### Usage Examples
+
+Enable thread-based parallel execution:
+
+```python
+import dir_content_diff
+
+dir_content_diff.compare_trees(
+    "reference_dir",
+    "compared_dir",
+    executor_type="thread",
+    max_workers=8
+)
+```
+
+Enable process-based parallel execution with automatic worker count:
+
+```python
+import dir_content_diff
+
+dir_content_diff.compare_trees(
+    "reference_dir",
+    "compared_dir",
+    executor_type="process"
+)
+```
+
+Using a configuration object:
+
+```python
+import dir_content_diff
+
+config = dir_content_diff.ComparisonConfig(
+    executor_type="thread",
+    max_workers=4
+)
+
+dir_content_diff.compare_trees(
+    "reference_dir",
+    "compared_dir",
+    config=config
+)
+```
+
+#### Performance Considerations
+
+- **Thread-based execution** (`executor_type="thread"`) is generally recommended for most use cases as file comparisons are typically I/O-bound operations
+- **Process-based execution** (`executor_type="process"`) may be beneficial when using computationally intensive comparators or when dealing with very large files
+- Parallel execution is automatically disabled for single file comparisons and falls back to sequential execution when only one file needs to be compared
+- The optimal number of workers depends on your system's capabilities and the nature of your files; too many workers may actually decrease performance due to overhead
+
+
 ### Export formatted data
 
 Some comparators have to format the data before comparing them. For example, if one wants to

dir_content_diff-1.14.1/dir_content_diff/__init__.py

@@ -0,0 +1,53 @@
+"""dir-content-diff package.
+
+Simple tool to compare directory contents.
+"""
+
+# LICENSE HEADER MANAGED BY add-license-header
+# Copyright (c) 2023-2026 Blue Brain Project, EPFL.
+#
+# This file is part of dir-content-diff.
+# See https://github.com/BlueBrain/dir-content-diff for further info.
+#
+# SPDX-License-Identifier: Apache-2.0
+# LICENSE HEADER MANAGED BY add-license-header
+
+import importlib.metadata
+
+# Import base comparators
+from dir_content_diff.base_comparators import BaseComparator
+from dir_content_diff.base_comparators import DefaultComparator
+
+# Import core comparison functionality
+from dir_content_diff.config import ComparisonConfig
+from dir_content_diff.core import ComparatorType
+from dir_content_diff.core import assert_equal_trees
+from dir_content_diff.core import compare_files
+from dir_content_diff.core import compare_trees
+from dir_content_diff.core import export_formatted_file
+from dir_content_diff.core import pick_comparator
+
+# Import comparator registry functionality
+from dir_content_diff.registry import get_comparators
+from dir_content_diff.registry import register_comparator
+from dir_content_diff.registry import reset_comparators
+from dir_content_diff.registry import unregister_comparator
+
+__version__ = importlib.metadata.version("dir-content-diff")
+
+# For backward compatibility, ensure all public functions are available
+__all__ = [
+    "ComparisonConfig",
+    "ComparatorType",
+    "assert_equal_trees",
+    "compare_files",
+    "compare_trees",
+    "export_formatted_file",
+    "pick_comparator",
+    "get_comparators",
+    "register_comparator",
+    "reset_comparators",
+    "unregister_comparator",
+    "BaseComparator",
+    "DefaultComparator",
+]

{dir_content_diff-1.13.0 → dir_content_diff-1.14.1}/dir_content_diff/base_comparators.py

@@ -1,7 +1,7 @@
 """Module containing the base comparators."""
 
 # LICENSE HEADER MANAGED BY add-license-header
-# Copyright (c) 2023-2025 Blue Brain Project, EPFL.
+# Copyright (c) 2023-2026 Blue Brain Project, EPFL.
 #
 # This file is part of dir-content-diff.
 # See https://github.com/BlueBrain/dir-content-diff for further info.
@@ -513,7 +513,7 @@ class XmlComparator(DictComparator):
             elif str(text).lower() == "false":
                 res = False
             else:
-                raise ValueError("Bool attributes expect 'true' or 'false'.")
+                raise ValueError("Boolean attributes expect 'true' or 'false'.")
         elif value_type == "list":
             res = []
         elif value_type == "dict":

{dir_content_diff-1.13.0 → dir_content_diff-1.14.1}/dir_content_diff/cli/__init__.py

@@ -1,7 +1,7 @@
 """Main entry point of the Command Line Interface for the dir-content-diff package."""
 
 # LICENSE HEADER MANAGED BY add-license-header
-# Copyright (c) 2023-2025 Blue Brain Project, EPFL.
+# Copyright (c) 2023-2026 Blue Brain Project, EPFL.
 #
 # This file is part of dir-content-diff.
 # See https://github.com/BlueBrain/dir-content-diff for further info.
@@ -13,15 +13,17 @@ import json
 import logging
 import sys
 from pathlib import Path
+from typing import Optional
+from typing import Union
 
 import click
 from yaml import safe_load
 
-from dir_content_diff import _DEFAULT_EXPORT_SUFFIX
 from dir_content_diff import compare_files
 from dir_content_diff import compare_trees
 from dir_content_diff import export_formatted_file
 from dir_content_diff import pick_comparator
+from dir_content_diff.core import _DEFAULT_EXPORT_SUFFIX
 from dir_content_diff.util import LOGGER
 
 
@@ -102,6 +104,19 @@ def load_config(ctx, param, value):  # pylint: disable=unused-argument
     default=False,
     help="Sort the differences by file name.",
 )
+@click.option(
+    "--executor-type",
+    type=click.Choice(["sequential", "thread", "process"]),
+    default="sequential",
+    help="Type of executor for execution. 'sequential' for single-threaded, "
+    "'thread' for I/O-bound tasks, 'process' for CPU-bound tasks.",
+)
+@click.option(
+    "--max-workers",
+    type=int,
+    help="Maximum number of worker threads/processes for parallel execution. "
+    "Only used with 'thread' or 'process' executor types.",
+)
 @click.version_option()
 @click.pass_context
 def main(ctx, *args, **kwargs):
@@ -120,16 +135,31 @@ def main(ctx, *args, **kwargs):
 
     ref = Path(kwargs.pop("reference_input"))
     comp = Path(kwargs.pop("compared_input"))
+
+    # Extract execution options
+    executor_type = kwargs.pop("executor_type", "sequential")
+    max_workers = kwargs.pop("max_workers", None)
+
     input_diff(
         ref,
         comp,
         ctx.config,
         kwargs.pop("export_formatted_files", False),
         kwargs.pop("sort_diffs", False),
+        executor_type,
+        max_workers,
     )
 
 
-def input_diff(ref, comp, config, export_formatted_files=False, sort_diffs=False):
+def input_diff(
+    ref: Union[str, Path],
+    comp: Union[str, Path],
+    config,
+    export_formatted_files: Union[bool, str] = False,
+    sort_diffs: bool = False,
+    executor_type: str = "sequential",
+    max_workers: Optional[int] = None,
+):
     """Compute and display differences from given inputs."""
     ref = Path(ref)
     comp = Path(comp)
@@ -145,6 +175,8 @@ def input_diff(ref, comp, config, export_formatted_files=False, sort_diffs=False
             comp,
             specific_args=config,
             export_formatted_files=export_formatted_files,
+            executor_type=executor_type,
+            max_workers=max_workers,
         )
     else:
         comparator_name = config.pop("comparator", None)

{dir_content_diff-1.13.0 → dir_content_diff-1.14.1}/dir_content_diff/comparators/__init__.py

@@ -1,7 +1,7 @@
 """Sub-package of dir-content-diff for specific comparators."""
 
 # LICENSE HEADER MANAGED BY add-license-header
-# Copyright (c) 2023-2025 Blue Brain Project, EPFL.
+# Copyright (c) 2023-2026 Blue Brain Project, EPFL.
 #
 # This file is part of dir-content-diff.
 # See https://github.com/BlueBrain/dir-content-diff for further info.

{dir_content_diff-1.13.0 → dir_content_diff-1.14.1}/dir_content_diff/comparators/morphio.py

@@ -1,7 +1,7 @@
 """Extension module to process morphology files with MorphIO and morph-tool."""
 
 # LICENSE HEADER MANAGED BY add-license-header
-# Copyright (c) 2023-2025 Blue Brain Project, EPFL.
+# Copyright (c) 2023-2026 Blue Brain Project, EPFL.
 #
 # This file is part of dir-content-diff.
 # See https://github.com/BlueBrain/dir-content-diff for further info.

{dir_content_diff-1.13.0 → dir_content_diff-1.14.1}/dir_content_diff/comparators/pandas.py

@@ -1,7 +1,7 @@
 """Extension module to process files with Pandas."""
 
 # LICENSE HEADER MANAGED BY add-license-header
-# Copyright (c) 2023-2025 Blue Brain Project, EPFL.
+# Copyright (c) 2023-2026 Blue Brain Project, EPFL.
 #
 # This file is part of dir-content-diff.
 # See https://github.com/BlueBrain/dir-content-diff for further info.

{dir_content_diff-1.13.0 → dir_content_diff-1.14.1}/dir_content_diff/comparators/voxcell.py

@@ -1,7 +1,7 @@
 """Extension module to process files with Voxcell."""
 
 # LICENSE HEADER MANAGED BY add-license-header
-# Copyright (c) 2023-2025 Blue Brain Project, EPFL.
+# Copyright (c) 2023-2026 Blue Brain Project, EPFL.
 #
 # This file is part of dir-content-diff.
 # See https://github.com/BlueBrain/dir-content-diff for further info.