GH-34: Fix the route prefix calculation by --base (GH-35)

* Optimize the `thumbnail_dir` calculation and usage
* Optimize the code with pathtools
* Add a short CLI description
* Fix FFmpeg input path value

Author: ArtyomVancyan

thumbnails/__init__.py

@@ -1,3 +1,19 @@
+"""
+   Copyright 2023 Artyom Vancyan
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+"""
+
 from .thumbnail import Thumbnail
 from .thumbnail import ThumbnailExistsError
 from .thumbnail import ThumbnailFactory
@@ -6,7 +22,7 @@
 from .thumbnail import register_thumbnail
 from .video import Video
 
-__version__ = "v1.0"
+__version__ = "0.0.1"
 __all__ = (
     "Thumbnail",
     "ThumbnailExistsError",

thumbnails/__main__.py

@@ -5,32 +5,28 @@
 
 import click
 
-from . import Thumbnail
 from . import ThumbnailExistsError
 from . import ThumbnailFactory
 from . import Video
 from .cli import cli
+from .pathtools import listdir
+from .pathtools import metadata_path
 
 
 def worker(video, fmt, base, skip, output):
-    """Generate thumbnails for a single video."""
+    """Executes the required workflows for generating a thumbnail(s)."""
     try:
         thumbnail = ThumbnailFactory.create_thumbnail(fmt, video, base, skip, output)
     except ThumbnailExistsError:
-        return print("Skipping '%s'" % video.filepath)
+        return print("Skipping '%s'" % os.path.relpath(video.filepath))
     thumbnail.prepare_frames()
     thumbnail.generate()
 
 
 @cli
 def main(compress=None, interval=None, base=None, inputs=None, output=None, skip=None, **kwargs):
-    """TODO: This section will be completed after fixing the issue #26."""
-
-    def listdir(directory):
-        """Lists all files in the given directory with absolute paths."""
-        for basedir, _, files in os.walk(directory):
-            for file in filter(os.path.isfile, files):
-                yield os.path.abspath(os.path.join(basedir, file))
+    """This command delegates the functionality of the `thumbnails` Python package
+    to the CLI. Read more at https://github.com/pysnippet/thumbnails#readme."""
 
     if all(map(os.path.isfile, inputs)):
         inputs = set(map(os.path.abspath, inputs))
@@ -40,7 +36,7 @@ def listdir(directory):
         exit("Inputs must be all files or all directories.")
 
     fmt = kwargs.pop("format")
-    inputs = dict(zip(map(lambda i: Thumbnail.metadata_path(i, output, fmt), inputs), inputs))
+    inputs = dict(zip(map(lambda i: metadata_path(i, output, fmt), inputs), inputs))
 
     if not skip and any(map(os.path.exists, inputs.keys())):
         skip = not click.confirm("Do you want to overwrite already existing files?")

thumbnails/frame.py

@@ -3,7 +3,7 @@
 
 
 class _Frame:
-    """This mixin class is used to optimally calculate the size of a thumbnail frame."""
+    """This class is used to calculate the optimal size of a thumbnail frame."""
 
     def __init__(self, size):
         width, height = size
@@ -22,10 +22,10 @@ def compress(self):
 
     @functools.cached_property
     def width(self):
-        """Calculates and caches the width."""
+        """Calculates and caches the frame width."""
         return max(self._min_width, self._width * self.compress)
 
     @functools.cached_property
     def height(self):
-        """Calculates and caches the height."""
+        """Calculates and caches the frame height."""
         return max(self._min_height, self._height * self.compress)

thumbnails/pathtools.py

@@ -0,0 +1,31 @@
+import functools
+import os
+from distutils.dir_util import create_tree
+
+
+def listdir(directory):
+    """Lists all files in the given directory with absolute paths."""
+    for basedir, _, files in os.walk(directory):
+        for file in filter(os.path.isfile, files):
+            yield os.path.abspath(os.path.join(basedir, file))
+
+
+@functools.cache
+def metadata_path(path, out, fmt):
+    """Calculates the thumbnail metadata output path."""
+    out = os.path.abspath(out or os.path.dirname(path))
+    return os.path.join(out, "%s.%s" % (extract_name(path), fmt))
+
+
+def extract_name(path):
+    """Extracts the name of the file from the path."""
+    return os.path.splitext(os.path.basename(path))[0]
+
+
+def ensure_tree(basedir, isdir=False, *args, **kwargs):
+    """Ensures the existence of basedir and returns."""
+    basedir, file = os.path.abspath(basedir), ""
+    if not isdir:
+        basedir, file = os.path.split(basedir)
+    create_tree(basedir, [file], *args, **kwargs)
+    return basedir

thumbnails/thumbnail.py

@@ -1,22 +1,24 @@
-import functools
 import json
 import os
 from abc import ABCMeta
 from abc import abstractmethod
 from datetime import timedelta
 from distutils.dir_util import copy_tree
-from distutils.dir_util import create_tree
 from distutils.dir_util import remove_tree
 
 from PIL import Image
 
+from .pathtools import ensure_tree
+from .pathtools import extract_name
+from .pathtools import metadata_path
+
 
 def register_thumbnail(typename):
-    """Register a new thumbnail formatter to the factory."""
+    """Register a new type of thumbnail generator into the factory."""
 
     def _register_factory(cls):
         if not issubclass(cls, Thumbnail):
-            raise ValueError("The formatter must implement the Thumbnail interface.")
+            raise ValueError("%s should be a Thumbnail." % cls.__name__)
 
         cls.extension = typename
         ThumbnailFactory.thumbnails[typename] = cls
@@ -30,7 +32,7 @@ class ThumbnailExistsError(Exception):
 
 
 class Thumbnail(metaclass=ABCMeta):
-    """Any thumbnail describing format should implement the base Formatter."""
+    """Any thumbnail describing format should implement the base Thumbnail."""
 
     extension = None
 
@@ -39,73 +41,63 @@ def __init__(self, video, base, skip, output):
         self.base = base
         self.skip = skip
         self.output = output
+        self.thumbnail_dir = self.calc_thumbnail_dir()
+        self.metadata_path = self._get_metadata_path()
         self._perform_skip()
         self.extract_frames()
 
+    def _get_metadata_path(self):
+        """Initiates the name of the thumbnail metadata file."""
+        return metadata_path(self.filepath, self.output, self.extension)
+
     def _perform_skip(self):
-        """Raises ThumbnailExistsError to skip."""
-        if os.path.exists(self.get_metadata_path()) and self.skip:
+        """Checks the file existence and decide whether to skip or not."""
+        if os.path.exists(self.metadata_path) and self.skip:
             raise ThumbnailExistsError
-        basedir, file = os.path.split(self.get_metadata_path())
-        create_tree(basedir, [file])
+        ensure_tree(self.metadata_path)
 
     def __getattr__(self, item):
-        """Delegate all other attributes to the video."""
+        """Delegates all other attributes to the video."""
         return getattr(self.video, item)
 
-    def get_metadata_path(self):
-        """Return the name of the thumbnail file."""
-        return self.metadata_path(self.filepath, self.output, self.extension)
-
-    @staticmethod
-    @functools.cache
-    def metadata_path(path, out, fmt):
-        """Calculate the thumbnail metadata output path."""
-        out = os.path.abspath(out or os.path.dirname(path))
-        filename = os.path.splitext(os.path.basename(path))[0]
-        return os.path.join(out, "%s.%s" % (filename, fmt))
-
     @abstractmethod
-    def thumbnail_dir(self):
-        """Creates and returns the thumbnail's output directory."""
+    def calc_thumbnail_dir(self):
+        """Calculates and returns the thumbnail's output directory."""
 
     @abstractmethod
     def prepare_frames(self):
-        """Prepare the thumbnails before generating the output."""
+        """Prepares the thumbnail frames before generating the output."""
 
     @abstractmethod
     def generate(self):
-        """Generate the thumbnails for the given video."""
+        """Generates the thumbnail metadata for the given video."""
 
 
 class ThumbnailFactory:
-    """A factory for creating thumbnail formatter."""
+    """A factory for creating a thumbnail for a particular format."""
 
     thumbnails = {}
 
     @classmethod
     def create_thumbnail(cls, typename, *args, **kwargs) -> Thumbnail:
-        """Create a new thumbnail formatter by the given typename."""
+        """Create a Thumbnail instance by the given typename."""
         try:
             return cls.thumbnails[typename](*args, **kwargs)
         except KeyError:
-            raise ValueError("The formatter type '%s' is not registered." % typename)
+            raise ValueError("The thumbnail type '%s' is not registered." % typename)
 
 
 @register_thumbnail("vtt")
 class ThumbnailVTT(Thumbnail):
     """Implements the methods for generating thumbnails in the WebVTT format."""
 
-    def thumbnail_dir(self):
-        basedir = self.output or os.path.dirname(self.filepath)
-        create_tree(os.path.abspath(basedir), [self.filepath])
-        return os.path.abspath(basedir)
+    def calc_thumbnail_dir(self):
+        return ensure_tree(self.output or os.path.dirname(self.filepath), True)
 
     def prepare_frames(self):
         thumbnails = self.thumbnails(True)
         master = Image.new(mode="RGBA", size=next(thumbnails))
-        master_name = os.path.splitext(os.path.basename(self.filepath))[0]
-        master_path = os.path.join(self.thumbnail_dir(), master_name + ".png")
+        master_path = os.path.join(self.thumbnail_dir, extract_name(self.filepath) + ".png")
 
         for frame, *_, x, y in self.thumbnails():
             with Image.open(frame) as image:
@@ -121,8 +113,8 @@ def format_time(secs):
             return ("0%s.000" % delta)[:12]
 
         metadata = ["WEBVTT\n\n"]
-        prefix = self.base or os.path.relpath(self.thumbnail_dir())
-        route = os.path.join(prefix, os.path.basename(self.filepath))
+        prefix = self.base or os.path.relpath(self.thumbnail_dir)
+        route = os.path.join(prefix, extract_name(self.filepath) + ".png")
 
         for _, start, end, x, y in self.thumbnails():
             thumbnail_data = "%s --> %s\n%s#xywh=%d,%d,%d,%d\n\n" % (
@@ -131,40 +123,38 @@ def format_time(secs):
             )
             metadata.append(thumbnail_data)
 
-        with open(self.get_metadata_path(), "w") as fp:
+        with open(self.metadata_path, "w") as fp:
             fp.writelines(metadata)
 
 
 @register_thumbnail("json")
 class ThumbnailJSON(Thumbnail):
     """Implements the methods for generating thumbnails in the JSON format."""
 
-    def thumbnail_dir(self):
+    def calc_thumbnail_dir(self):
         basedir = os.path.abspath(self.output or os.path.dirname(self.filepath))
-        subdir = os.path.splitext(os.path.basename(self.filepath))[0]
-        basedir = os.path.join(basedir, subdir)
-        create_tree(basedir, [self.filepath])
-        return basedir
+        return ensure_tree(os.path.join(basedir, extract_name(self.filepath)), True)
 
     def prepare_frames(self):
-        thumbnail_dir = self.thumbnail_dir()
-        if os.path.exists(thumbnail_dir):
-            remove_tree(thumbnail_dir)
-        copy_tree(self.tempdir.name, thumbnail_dir)
+        if os.path.exists(self.thumbnail_dir):
+            remove_tree(self.thumbnail_dir)
+        copy_tree(self.tempdir.name, self.thumbnail_dir)
         self.tempdir.cleanup()
 
     def generate(self):
         metadata = {}
 
         for frame, start, *_ in self.thumbnails():
-            frame = os.path.join(self.thumbnail_dir(), os.path.basename(frame))
+            frame = os.path.join(self.thumbnail_dir, os.path.basename(frame))
             with Image.open(frame) as image:
                 image.resize((self.width, self.height), Image.ANTIALIAS).save(frame)
+                prefix = self.base or os.path.relpath(self.thumbnail_dir)
+                route = os.path.join(prefix, os.path.basename(frame))
                 thumbnail_data = {
-                    "src": self.base + frame,
+                    "src": route,
                     "width": "%spx" % self.width,
                 }
                 metadata[int(start)] = thumbnail_data
 
-        with open(self.get_metadata_path(), "w") as fp:
+        with open(self.metadata_path, "w") as fp:
             json.dump(metadata, fp, indent=2)

thumbnails/video.py

@@ -29,7 +29,7 @@ def _generator():
 
 
 class Video(_FFMpeg, _Frame):
-    """The main class for processing the thumbnail generation of a video."""
+    """This class gives methods to extract the thumbnail frames of a video."""
 
     def __init__(self, filepath, compress, interval):
         self.__filepath = filepath
@@ -65,35 +65,33 @@ def calc_columns(frames_count, width, height):
                 return col
 
     def _extract_frame(self, start_time):
-        """Extracts a single frame from the video by the given time."""
-        _input_file = os.path.basename(self.filepath)
-        _timestamp = str(timedelta(seconds=start_time))
-        _output_file = "%s/%s-%s.png" % (self.tempdir.name, _timestamp, _input_file)
+        """Extracts a single frame from the video by the offset."""
+        offset = str(timedelta(seconds=start_time))
+        output = "%s/%s.png" % (self.tempdir.name, offset)
 
         cmd = (
             ffmpeg_bin,
-            "-ss", _timestamp,
-            "-i", _input_file,
+            "-ss", offset,
+            "-i", self.filepath,
             "-loglevel", "error",
             "-vframes", "1",
-            _output_file,
+            output,
             "-y",
         )
 
         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)
+            executor.map(self._extract_frame, arange(0, self.duration, self.interval))
 
     def thumbnails(self, master_size=False):
-        """This generator function yields a thumbnail on each iteration.
+        """This generator function yields a thumbnail data 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.
+        The thumbnail data is a tuple of fields describing the current frame.
+        The structure of the thumbnail data is (frame, start, end, x, y).
+            - frame: The filename of the current frame (usually 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.