GH-12: Add docstrings to functions, methods and classes (GH-25)

* Cache the `arange` function
* Return the class after registering to factory
* Add the useful classes to the `__all__`
* Refactor the factory method name

Author: ArtyomVancyan

thumbnails/__init__.py

@@ -6,7 +6,7 @@
 
 from PIL import Image
 
-from .formatter import ThumbnailFactory
+from .formatter import FormatterFactory
 from .formatter import ThumbnailFormat
 from .thumbnails import Thumbnails
 from .thumbnails import arange
@@ -18,15 +18,24 @@
 
 
 def register_format(typename):
-    def _registrator(cls: ThumbnailFormat):
+    """Register a new thumbnail format to the factory."""
+
+    def _registrator(cls):
+        if not issubclass(cls, ThumbnailFormat):
+            raise ValueError("Thumbnail format must implement"
+                             "the ThumbnailFormat interface.")
+
         cls.extension = typename
-        ThumbnailFactory.thumbnails[typename] = cls
+        FormatterFactory.thumbnails[typename] = cls
+        return cls
 
     return _registrator
 
 
 @register_format("vtt")
 class VTT(ThumbnailFormat):
+    """Implements the methods for generating thumbnails in the WebVTT format."""
+
     def __init__(self, video):
         super().__init__(video)
         self._master_name = self.filename + ".png"
@@ -64,6 +73,8 @@ def _format_time(secs):
 
 @register_format("json")
 class JSON(ThumbnailFormat):
+    """Implements the methods for generating thumbnails in the JSON format."""
+
     def __init__(self, video):
         super().__init__(video)
         self._outdir = "outdir"  # temp dirname
@@ -92,4 +103,11 @@ def generate(self):
 
 
 __version__ = "v1.0"
-__all__ = (Thumbnails,)
+__all__ = (
+    FormatterFactory,
+    register_format,
+    ThumbnailFormat,
+    Thumbnails,
+    JSON,
+    VTT,
+)

thumbnails/__main__.py

@@ -8,19 +8,22 @@
 from . import DEFAULT_BASEPATH
 from . import DEFAULT_COMPRESS
 from . import DEFAULT_INTERVAL
-from . import ThumbnailFactory
+from . import FormatterFactory
 from . import Thumbnails
 from . import __version__
 
 
 def worker(video, as_):
+    """Generate thumbnails for a single video."""
     video.extract_frames()
-    formatter = ThumbnailFactory.get_formatter(as_, video)
+    formatter = FormatterFactory.create_formatter(as_, video)
     formatter.prepare_thumbnails()
     formatter.generate()
 
 
 class _ThumbnailsCLI(click.Command):
+    """This class overrides the usages section of the help message."""
+
     def format_usage(self, ctx, formatter):
         usages = (
             "[OPTIONS] INPUT_DIR OUTPUT_DIR",
@@ -32,15 +35,15 @@ def format_usage(self, ctx, formatter):
 
 @click.command(cls=_ThumbnailsCLI)
 @click.option("--as", "-F", default=DEFAULT_AS, help="Output format. Default is %s." % DEFAULT_AS,
-              type=click.Choice(ThumbnailFactory.thumbnails.keys(), case_sensitive=False))
+              type=click.Choice(FormatterFactory.thumbnails.keys(), case_sensitive=False))
 @click.option("--compress", "-C", default=DEFAULT_COMPRESS, help="The image scale coefficient. A number from 0 to 1.")
 @click.option("--interval", "-I", default=DEFAULT_INTERVAL, help="The interval between neighbor thumbnails in seconds.")
 @click.option("--basepath", "-B", default=DEFAULT_BASEPATH, help="The prefix of the thumbnails path can be customized.")
 @click.argument("inputs", required=True, type=click.Path(), nargs=-1)
 @click.argument("output", required=True, type=click.Path(), nargs=1)
 @click.version_option(__version__)
 def thumbnails_cli(compress, interval, basepath, inputs, output, **kwargs):
-    """TODO: Add more description about particular usages."""
+    """TODO: This section will be completed after fixing the issue #26."""
     as_ = kwargs.pop("as")
     output_is_directory = all((len(inputs) > 1, *map(os.path.isfile, inputs))) or os.path.isdir(inputs[0])
 
@@ -59,10 +62,5 @@ def thumbnails_cli(compress, interval, basepath, inputs, output, **kwargs):
         executor.map(functools.partial(worker, as_=as_), videos)
 
 
-# @click.confirmation_option("--overwrite", "-y", prompt="Are you sure you want to overwrite the existing output files?")
-# def overwrite():
-#     print("overwritten")
-
-
 if __name__ == "__main__":
     thumbnails_cli()

thumbnails/ffmpeg.py

@@ -9,6 +9,8 @@
 
 
 class _FFMpeg:
+    """This class is used to parse the metadata of a video file."""
+
     def __init__(self, filename):
         duration, self.size = self._parse_metadata(filename)
         self.duration = int(duration + 1)
@@ -27,22 +29,28 @@ def _cross_platform_popen_params(bufsize=100000):
 
     @staticmethod
     def _parse_duration(stdout):
+        """Parse the duration of a video from stdout."""
         duration_regex = r"duration[^\n]+([0-9][0-9]:[0-9][0-9]:[0-9][0-9].[0-9][0-9])"
         time = re.search(duration_regex, stdout, re.M | re.I).group(1)
         time = (float(part.replace(",", ".")) for part in time.split(":"))
         return sum(mult * part for mult, part in zip((3600, 60, 1), time))
 
     @staticmethod
     def _parse_size(stdout):
+        """Parse the size of a video from stdout."""
         size_regex = r"\s(\d+)x(\d+)[,\s]"
         match_size = re.search(size_regex, stdout, re.M)
         return tuple(map(int, match_size.groups()))
 
     def _parse_metadata(self, filename):
+        """Parse the metadata of a video file."""
         meta = immeta(filename)
         duration, size = meta.get("duration"), meta.get("size")
 
         if not all((duration, size)):
+            # Parse the metadata of the video formats
+            # that are not supported by imageio.
+
             cmd = (ffmpeg_bin, "-hide_banner", "-i", filename)
 
             popen_params = self._cross_platform_popen_params()

thumbnails/formatter.py

@@ -1,10 +1,13 @@
 class ThumbnailFormat:
+    """The interface of the thumbnails' final output format generator."""
+
     extension = None
 
     def __init__(self, video):
         self.video = video
 
     def __getattr__(self, item):
+        """Delegate all other attributes to the video."""
         return getattr(self.video, item)
 
     @property
@@ -20,12 +23,15 @@ def generate(self):
         raise NotImplementedError
 
 
-class ThumbnailFactory:
+class FormatterFactory:
+    """A factory for creating thumbnail formatter."""
+
     thumbnails = {}
 
     @classmethod
-    def get_formatter(cls, typename, *args, **kwargs) -> ThumbnailFormat:
+    def create_formatter(cls, typename, *args, **kwargs) -> ThumbnailFormat:
+        """Create a new thumbnail formatter by the given typename."""
         try:
             return cls.thumbnails[typename](*args, **kwargs)
         except KeyError:
-            raise ValueError("Thumbnail type '%s' is not supported." % typename)
+            raise ValueError("Thumbnail format '%s' is not supported." % typename)

thumbnails/thumbnails.py

@@ -1,4 +1,5 @@
 import concurrent.futures
+import functools
 import glob
 import math
 import os
@@ -13,7 +14,10 @@
 ffmpeg_bin = get_ffmpeg_exe()
 
 
+@functools.cache
 def arange(start, stop, step):
+    """Roughly equivalent to numpy.arange."""
+
     def _generator():
         nonlocal start
         while start < stop:
@@ -24,10 +28,9 @@ def _generator():
 
 
 class _ThumbnailMixin:
-    def __init__(self, size):
-        self._w = None
-        self._h = None
+    """This mixin class is used to optimally calculate the size of a thumbnail frame."""
 
+    def __init__(self, size):
         width, height = size
         _min_width = 300
         _min_height = math.ceil(_min_width * height / width)
@@ -39,22 +42,23 @@ def __init__(self, size):
 
     @property
     def compress(self):
+        """Defines an interface for the compress property."""
         raise NotImplementedError
 
-    @property
+    @functools.cached_property
     def width(self):
-        if not self._w:
-            self._w = max(self._min_width, self._width * self.compress)
-        return self._w
+        """Calculates and caches the width."""
+        return max(self._min_width, self._width * self.compress)
 
-    @property
+    @functools.cached_property
     def height(self):
-        if not self._h:
-            self._h = max(self._min_height, self._height * self.compress)
-        return self._h
+        """Calculates and caches the height."""
+        return max(self._min_height, self._height * self.compress)
 
 
 class Thumbnails(_ThumbnailMixin, _FFMpeg):
+    """The main class for processing the thumbnail generation of a video."""
+
     def __init__(self, filename, compress, interval, basepath):
         self.__compress = float(compress)
         self.__interval = float(interval)
@@ -83,12 +87,14 @@ def basepath(self):
 
     @staticmethod
     def calc_columns(frames_count, width, height):
+        """Calculates an optimal number of columns for 16:9 aspect ratio."""
         ratio = 16 / 9
         for col in range(1, frames_count):
             if (col * width) / (frames_count // col * height) > ratio:
                 return col
 
     def _extract_frame(self, start_time):
+        """Extracts a single frame from the video by the given time."""
         _input_file = self.filename
         _timestamp = str(timedelta(seconds=start_time))
         _output_file = "%s/%s-%s.png" % (self.tempdir.name, _timestamp, self.filename)
@@ -106,11 +112,25 @@ def _extract_frame(self, start_time):
         subprocess.Popen(cmd).wait()
 
     def extract_frames(self):
+        """Extracts the frames from the video by given intervals."""
         _intervals = arange(0, self.duration, self.interval)
         with concurrent.futures.ThreadPoolExecutor() as executor:
             executor.map(self._extract_frame, _intervals)
 
     def thumbnails(self, master_size=False):
+        """This generator function yields a thumbnail on each iteration.
+
+        A thumbnail is a tuple of data describing the current frame.
+        The thumbnail structure is (frame, start, end, x, y) where:
+            - frame: Filename of the current frame in temp-files.
+            - start: The start point of the time range the frame belongs to.
+            - end: The end point of the time range the frame belongs to.
+            - x: The X coordinate of the frame in the final image.
+            - y: The Y coordinate of the frame in the final image.
+
+        :param master_size:
+            If True, the master size will be yielded on the first iteration. Default is False.
+        """
         line, column = 0, 0
         frames = sorted(glob.glob(self.tempdir.name + os.sep + "*.png"))
         frames_count = len(arange(0, self.duration, self.interval))