enforce the presence of docstrings on classes and modules

.pylintrc

@@ -69,8 +69,6 @@ disable=raw-checker-failed,
         deprecated-pragma,
         use-symbolic-message-instead,
         missing-function-docstring,
-        missing-class-docstring,
-        missing-module-docstring,
         unsubscriptable-object,
         consider-using-with
 

duplicate_images/__init__.py

@@ -0,0 +1,3 @@
+"""
+Given a big set of images, find duplicate and similar images
+"""

duplicate_images/common.py

@@ -1,3 +1,6 @@
+"""
+Functions used in multiple places
+"""
 __author__ = 'Lene Preuss <[email protected]>'
 
 import logging

duplicate_images/duplicate.py

@@ -1,4 +1,7 @@
 #!/usr/bin/env /usr/bin/python3
+"""
+The main script for the `find-dups` command line tool.
+"""
 
 import logging
 import re

duplicate_images/function_types.py

@@ -1,3 +1,7 @@
+"""
+Shorter and more descriptive type aliases used in static type checking for the
+`duplicate_images` package.
+"""
 __author__ = 'Lene Preuss <[email protected]>'
 
 from argparse import Namespace

duplicate_images/hash_scanner/__init__.py

@@ -1,3 +1,6 @@
+"""
+Functionality to compute and store the image hashes of a set of images
+"""
 __author__ = 'Lene Preuss <[email protected]>'
 
 from duplicate_images.hash_scanner.image_hash_scanner import (

duplicate_images/hash_scanner/image_hash_scanner.py

@@ -1,3 +1,6 @@
+"""
+Calculate the image hashes of a given set of images
+"""
 __author__ = 'Lene Preuss <[email protected]>'
 
 import logging
@@ -19,6 +22,11 @@
 
 
 class ImageHashScanner:
+    """
+    Reads images from the given list of files and calculates their image hashes,
+    using a single thread only
+    """
+
     @staticmethod
     def create(
             files: List[Path], hash_algorithm: HashFunction,
@@ -75,6 +83,10 @@ def get_hash(self, file: Path) -> CacheEntry:
 
 
 class ParallelImageHashScanner(ImageHashScanner):
+    """
+    Reads images from the given list of files and calculates their image hashes,
+    using a specified number of threads in parallel
+    """
 
     def __init__(  # pylint: disable = too-many-arguments
             self,

duplicate_images/hash_store.py

@@ -1,3 +1,6 @@
+"""
+Persistent storage for calculated image hashes
+"""
 __author__ = 'Lene Preuss <[email protected]>'
 
 import json
@@ -13,6 +16,11 @@
 
 
 class NullHashStore:
+    """
+    Hash store that does not store anything but can be used as a drop-in
+    replacement for `FileHashStore` and `PickleHashStore` when no persistent
+    storage is desired
+    """
 
     def __init__(self) -> None:
         logging.info('No persistent storage for calculated image hashes set up')
@@ -34,7 +42,11 @@ def add(self, _: Path, __: ImageHash) -> None:
 
 
 class FileHashStore:
-
+    """
+    Base class for persistent storage of calculated image hashes, providing all
+    necessary functionality except for reading and writing data to various file
+    formats
+    """
     @staticmethod
     def create(
             store_path: Optional[Path], algorithm: str, hash_size_kwargs: Dict
@@ -117,6 +129,10 @@ def dump(self) -> None:
 
 
 class PickleHashStore(FileHashStore):
+    """
+    Implementation of `FileHashStore` that reads and stores the calculated
+    image hashes in Pickle format
+    """
 
     @log_execution_time()
     def load(self) -> None:
@@ -144,6 +160,10 @@ def load_values_and_metadata(file: IO) -> Tuple[Cache, Dict]:
 
 
 class JSONHashStore(FileHashStore):
+    """
+    Implementation of `FileHashStore` that reads and stores the calculated
+    image hashes in JSON format
+    """
 
     @log_execution_time()
     def load(self) -> None:

duplicate_images/image_pair_finder.py

@@ -1,3 +1,7 @@
+"""
+Finds duplicate images by comparing their image hashes using the given hash
+algorithm
+"""
 __author__ = 'Lene Preuss <[email protected]>'
 
 import logging
@@ -31,6 +35,9 @@ def group_results_as_tuples(results: ResultsGenerator) -> Results:
 
 
 class ImagePairFinder:
+    """
+    Finds duplicate images by comparing their image hashes
+    """
 
     @classmethod
     def create(

duplicate_images/log.py

@@ -1,3 +1,6 @@
+"""
+Logging setup
+"""
 __author__ = 'Lene Preuss <[email protected]>'
 
 import logging

duplicate_images/methods.py

@@ -1,3 +1,6 @@
+"""
+Definition of the possible actions run on sets of equal images
+"""
 __author__ = 'Lene Preuss <[email protected]>'
 
 import logging

duplicate_images/pair_finder_options.py

@@ -1,3 +1,6 @@
+"""
+Encapsulates the options for scanning images and detecting duplicates
+"""
 __author__ = 'Lene Preuss <[email protected]>'
 
 from argparse import Namespace
@@ -7,6 +10,10 @@
 
 @dataclass(frozen=True)
 class PairFinderOptions:
+    """
+    Encapsulates the options for scanning images and detecting duplicates and
+    reads them from an `argparse.Namespace` object
+    """
     max_distance: int = 0
     hash_size: Optional[int] = None
     show_progress_bars: bool = False

duplicate_images/parse_commandline.py

@@ -1,4 +1,7 @@
-__author__ = 'lene'
+"""
+Define and parse command line arguments for the `find-dups` command line tool
+"""
+__author__ = 'Lene Preuss <[email protected]>'
 
 from os import cpu_count
 from argparse import ArgumentParser, Namespace

duplicate_images/progress_bar_manager.py

@@ -1,3 +1,6 @@
+"""
+Controlling the progress bars shown during processing images
+"""
 __author__ = 'Lene Preuss <[email protected]>'
 
 from typing import Optional
@@ -6,7 +9,10 @@
 
 
 class ProgressBarManager:
-
+    """
+    Manages the progress bars shown during image scan and, optionally, duplicate
+    detection
+    """
     @classmethod
     def create(cls, files_length: int, active: bool = False) -> 'ProgressBarManager':
         return ProgressBarManager(files_length) if active else NullProgressBarManager()
@@ -44,7 +50,10 @@ def close(self) -> None:
 
 
 class NullProgressBarManager(ProgressBarManager):
-
+    """
+    Implementation of `ProgressBarManager` that does nothing but can be used in
+    place of one
+    """
     def __init__(self) -> None:
         super().__init__(0)
 

tests/integration/__init__.py

@@ -0,0 +1,2 @@
+# pylint: disable=missing-docstring
+__author__ = 'Lene Preuss <[email protected]>'

tests/integration/conftest.py

@@ -1,3 +1,6 @@
+# pylint: disable=missing-docstring
+__author__ = 'Lene Preuss <[email protected]>'
+
 from pathlib import Path
 from tempfile import TemporaryDirectory
 from typing import Generator

tests/integration/test_is_image_file.py

@@ -1,3 +1,6 @@
+# pylint: disable=missing-docstring
+__author__ = 'Lene Preuss <[email protected]>'
+
 from pathlib import Path
 from typing import List
 

tests/integration/test_persistent_storage.py

@@ -1,3 +1,5 @@
+# pylint: disable=missing-docstring
+__author__ = 'Lene Preuss <[email protected]>'
 
 import json
 import pickle

tests/integration/test_real_images.py

@@ -1,3 +1,4 @@
+# pylint: disable=missing-docstring
 __author__ = 'Lene Preuss <[email protected]>'
 
 from pathlib import Path

tests/unit/__init__.py

@@ -1 +1,2 @@
+# pylint: disable=missing-docstring
 __author__ = 'Lene Preuss <[email protected]>'

tests/unit/conftest.py

@@ -1,3 +1,4 @@
+# pylint: disable=missing-docstring
 __author__ = 'Lene Preuss <[email protected]>'
 
 import random

tests/unit/test_actions.py

@@ -1,3 +1,4 @@
+# pylint: disable=missing-docstring
 __author__ = 'Lene Preuss <[email protected]>'
 
 import shlex

tests/unit/test_files_in_dirs.py

@@ -1,3 +1,4 @@
+# pylint: disable=missing-docstring
 __author__ = 'Lene Preuss <[email protected]>'
 
 from pathlib import Path

tests/unit/test_image_hash_scanner.py

@@ -1,3 +1,4 @@
+# pylint: disable=missing-docstring
 __author__ = 'Lene Preuss <[email protected]>'
 
 from pathlib import Path

tests/unit/test_image_pair_finder.py

@@ -1,4 +1,5 @@
-__author__ = 'lene'
+# pylint: disable=missing-docstring
+__author__ = 'Lene Preuss <[email protected]>'
 
 from pathlib import Path
 from tempfile import TemporaryDirectory

tests/unit/test_imagehash.py

@@ -1,3 +1,6 @@
+# pylint: disable=missing-docstring
+__author__ = 'Lene Preuss <[email protected]>'
+
 from pathlib import Path
 from typing import List
 

tests/unit/test_parse_commandline.py

@@ -1,3 +1,4 @@
+# pylint: disable=missing-docstring
 __author__ = 'Lene Preuss <[email protected]>'
 
 from os import cpu_count

tests/unit/test_persistent_storage.py

@@ -1,3 +1,4 @@
+# pylint: disable=missing-docstring
 __author__ = 'Lene Preuss <[email protected]>'
 
 import json