From 0751d072d9b61be3466f39184beba004d61104f1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81lvaro=20Mond=C3=A9jar?= <mondejar1994@gmail.com>
Date: Wed, 2 Jun 2021 16:06:44 +0200
Subject: [PATCH] Add missing modules docstrings (except for FXs) (#1611)

* Add module docstrings except in FXs

* Update flake8 config

* Remove 'find_latest_imagemagick_version.py'

* Add tests modules docstrings

* Don't execute doctests for tests/ modules

* Prevent test error in Windows
---
 .github/workflows/format_check.yml            |  2 +-
 .github/workflows/test_suite.yml              |  4 ++--
 docs/conf.py                                  | 13 ++---------
 find_latest_imagemagick_version.py            | 23 -------------------
 moviepy/audio/AudioClip.py                    |  6 +++++
 moviepy/audio/io/AudioFileClip.py             |  2 ++
 moviepy/audio/io/ffmpeg_audiowriter.py        |  2 ++
 moviepy/audio/io/preview.py                   |  2 ++
 moviepy/audio/io/readers.py                   |  2 ++
 moviepy/audio/tools/cuts.py                   |  2 ++
 moviepy/config.py                             |  2 ++
 moviepy/utils.py                              |  2 ++
 moviepy/video/VideoClip.py                    |  3 ++-
 .../video/compositing/CompositeVideoClip.py   |  2 ++
 moviepy/video/compositing/concatenate.py      |  2 ++
 moviepy/video/io/ImageSequenceClip.py         |  4 ++++
 moviepy/video/io/VideoFileClip.py             |  2 ++
 moviepy/video/io/gif_writers.py               |  2 ++
 moviepy/video/io/preview.py                   |  2 ++
 moviepy/video/io/sliders.py                   |  2 ++
 moviepy/video/tools/segmenting.py             |  2 ++
 setup.cfg                                     | 10 ++++----
 tests/test_BitmapClip.py                      |  2 ++
 tests/test_Clip.py                            |  2 ++
 tests/test_TextClip.py                        |  2 ++
 tests/test_VideoClip.py                       |  2 ++
 tests/test_examples.py                        |  2 ++
 tests/test_ffmpeg_writer.py                   |  5 +++-
 tests/test_fx.py                              |  2 ++
 tests/test_tools.py                           |  2 +-
 30 files changed, 68 insertions(+), 44 deletions(-)
 delete mode 100644 find_latest_imagemagick_version.py

diff --git a/.github/workflows/format_check.yml b/.github/workflows/format_check.yml
index 1c9ae1ac..1ef9158f 100644
--- a/.github/workflows/format_check.yml
+++ b/.github/workflows/format_check.yml
@@ -29,7 +29,7 @@ jobs:
       - name: Lint examples
         run: flake8 examples --show-source
       - name: Lint scripts
-        run: flake8 setup.py find_latest_imagemagick_version.py docs/conf.py --show-source
+        run: flake8 setup.py docs/conf.py --show-source
       - name: Lint tests
         run: flake8 tests --show-source
       - name: Lint moviepy
diff --git a/.github/workflows/test_suite.yml b/.github/workflows/test_suite.yml
index d257fb72..f358d021 100644
--- a/.github/workflows/test_suite.yml
+++ b/.github/workflows/test_suite.yml
@@ -59,7 +59,7 @@ jobs:
 
     - name: Test with pytest
       run: |
-        pythonw -m pytest tests/ --doctest-modules -v --cov moviepy --cov-report term-missing
+        pythonw -m pytest --doctest-glob "moviepy/**/**.py" -v --cov moviepy --cov-report term-missing
 
     - name: Coveralls
       run: coveralls
@@ -172,7 +172,7 @@ jobs:
 
       - name: PyTest
         run: |
-          pytest tests/ --doctest-modules -v --cov moviepy --cov-report term-missing
+          python -m pytest --doctest-glob "moviepy/**/**.py" --cov moviepy --cov-report term-missing
 
       - name: Test pip installation
         run: |
diff --git a/docs/conf.py b/docs/conf.py
index 2c895f80..dfd0cc3a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,15 +1,6 @@
 # -*- coding: utf-8 -*-
-#
-# MoviePy documentation build configuration file, created by
-# sphinx-quickstart on Sat Jul 13 14:47:48 2013.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
+
+"""MoviePy documentation build configuration file."""
 
 import os
 import sys
diff --git a/find_latest_imagemagick_version.py b/find_latest_imagemagick_version.py
deleted file mode 100644
index 8e0de40c..00000000
--- a/find_latest_imagemagick_version.py
+++ /dev/null
@@ -1,23 +0,0 @@
-"""Parses url below to extract latest image magick version (major version 6.9),
-to feed it into CI system. Not the best way for reproducible builds, but it's
-preferred for now over storing imagemagick installer into the GIT repository.
-"""
-
-import re
-from urllib import request
-
-
-url = "https://legacy.imagemagick.org/script/index.php"
-
-response = request.urlopen(url)
-html = response.read().decode(r"utf-8")
-r = re.compile(r"6\.9\.[0-9]+-[0-9]+")
-version = r.findall(html)
-if len(version) == 0:
-    raise ValueError(
-        "Could not find latest legacy 6.9.X-Y ImageMagick version from {}".format(url)
-    )
-version = version[0]
-# Append Q16 build
-version += "-Q16"
-print(version)
diff --git a/moviepy/audio/AudioClip.py b/moviepy/audio/AudioClip.py
index c56661b1..002cd737 100644
--- a/moviepy/audio/AudioClip.py
+++ b/moviepy/audio/AudioClip.py
@@ -1,3 +1,9 @@
+"""Implements AudioClip (base class for audio clips) and its main subclasses:
+
+- Audio clips: AudioClip, AudioFileClip, AudioArrayClip
+- Composition: CompositeAudioClip
+"""
+
 import numbers
 import os
 
diff --git a/moviepy/audio/io/AudioFileClip.py b/moviepy/audio/io/AudioFileClip.py
index d539d8ab..4ab79b40 100644
--- a/moviepy/audio/io/AudioFileClip.py
+++ b/moviepy/audio/io/AudioFileClip.py
@@ -1,3 +1,5 @@
+"""Implements AudioFileClip, a class for audio clips creation using audio files."""
+
 from moviepy.audio.AudioClip import AudioClip
 from moviepy.audio.io.readers import FFMPEG_AudioReader
 from moviepy.decorators import convert_path_to_string
diff --git a/moviepy/audio/io/ffmpeg_audiowriter.py b/moviepy/audio/io/ffmpeg_audiowriter.py
index b224cb57..f39f24ba 100644
--- a/moviepy/audio/io/ffmpeg_audiowriter.py
+++ b/moviepy/audio/io/ffmpeg_audiowriter.py
@@ -1,3 +1,5 @@
+"""MoviePy audio writing with ffmpeg."""
+
 import subprocess as sp
 
 import proglog
diff --git a/moviepy/audio/io/preview.py b/moviepy/audio/io/preview.py
index 8bc0166a..662cf43c 100644
--- a/moviepy/audio/io/preview.py
+++ b/moviepy/audio/io/preview.py
@@ -1,3 +1,5 @@
+"""Audio preview functions for MoviePy editor."""
+
 import time
 
 import numpy as np
diff --git a/moviepy/audio/io/readers.py b/moviepy/audio/io/readers.py
index e1da7bd4..c714c69d 100644
--- a/moviepy/audio/io/readers.py
+++ b/moviepy/audio/io/readers.py
@@ -1,3 +1,5 @@
+"""MoviePy audio reading with ffmpeg."""
+
 import subprocess as sp
 import warnings
 
diff --git a/moviepy/audio/tools/cuts.py b/moviepy/audio/tools/cuts.py
index 24ec220d..6abf5ea2 100644
--- a/moviepy/audio/tools/cuts.py
+++ b/moviepy/audio/tools/cuts.py
@@ -1,3 +1,5 @@
+"""Cutting utilities working with audio."""
+
 import numpy as np
 
 
diff --git a/moviepy/config.py b/moviepy/config.py
index 9be17234..20563e59 100644
--- a/moviepy/config.py
+++ b/moviepy/config.py
@@ -1,3 +1,5 @@
+"""Third party programs configuration for MoviePy."""
+
 import os
 import subprocess as sp
 from pathlib import Path
diff --git a/moviepy/utils.py b/moviepy/utils.py
index 5c345ccc..eb7a0958 100644
--- a/moviepy/utils.py
+++ b/moviepy/utils.py
@@ -1,3 +1,5 @@
+"""Useful utilities working with MoviePy."""
+
 from moviepy.audio.io.AudioFileClip import AudioFileClip
 from moviepy.video.io.VideoFileClip import VideoFileClip
 from moviepy.video.VideoClip import ImageClip
diff --git a/moviepy/video/VideoClip.py b/moviepy/video/VideoClip.py
index e6567064..bb290521 100644
--- a/moviepy/video/VideoClip.py
+++ b/moviepy/video/VideoClip.py
@@ -1,8 +1,9 @@
 """Implements VideoClip (base class for video clips) and its main subclasses:
 
-- Animated clips:     VideofileClip, ImageSequenceClip
+- Animated clips:     VideoFileClip, ImageSequenceClip, BitmapClip
 - Static image clips: ImageClip, ColorClip, TextClip,
 """
+
 import copy as _copy
 import os
 import subprocess as sp
diff --git a/moviepy/video/compositing/CompositeVideoClip.py b/moviepy/video/compositing/CompositeVideoClip.py
index 016b9133..b7df1654 100644
--- a/moviepy/video/compositing/CompositeVideoClip.py
+++ b/moviepy/video/compositing/CompositeVideoClip.py
@@ -1,3 +1,5 @@
+"""Main video composition interface of MoviePy."""
+
 import numpy as np
 from PIL import Image
 
diff --git a/moviepy/video/compositing/concatenate.py b/moviepy/video/compositing/concatenate.py
index 5e445f3d..76ea098d 100644
--- a/moviepy/video/compositing/concatenate.py
+++ b/moviepy/video/compositing/concatenate.py
@@ -1,3 +1,5 @@
+"""Video clips concatenation."""
+
 from functools import reduce
 
 import numpy as np
diff --git a/moviepy/video/io/ImageSequenceClip.py b/moviepy/video/io/ImageSequenceClip.py
index 2965f819..fd939c49 100644
--- a/moviepy/video/io/ImageSequenceClip.py
+++ b/moviepy/video/io/ImageSequenceClip.py
@@ -1,3 +1,7 @@
+"""Implements ImageSequenceClip, a class to create a video clip from a set
+of image files.
+"""
+
 import os
 
 import numpy as np
diff --git a/moviepy/video/io/VideoFileClip.py b/moviepy/video/io/VideoFileClip.py
index a4bb5b76..f7d6d11f 100644
--- a/moviepy/video/io/VideoFileClip.py
+++ b/moviepy/video/io/VideoFileClip.py
@@ -1,3 +1,5 @@
+"""Implements VideoFileClip, a class for video clips creation using video files."""
+
 from moviepy.audio.io.AudioFileClip import AudioFileClip
 from moviepy.decorators import convert_path_to_string
 from moviepy.video.io.ffmpeg_reader import FFMPEG_VideoReader
diff --git a/moviepy/video/io/gif_writers.py b/moviepy/video/io/gif_writers.py
index 630ae24c..d750765a 100644
--- a/moviepy/video/io/gif_writers.py
+++ b/moviepy/video/io/gif_writers.py
@@ -1,3 +1,5 @@
+"""MoviePy video GIFs writing."""
+
 import os
 import subprocess as sp
 
diff --git a/moviepy/video/io/preview.py b/moviepy/video/io/preview.py
index 1f8f7d2f..1b7e85ba 100644
--- a/moviepy/video/io/preview.py
+++ b/moviepy/video/io/preview.py
@@ -1,3 +1,5 @@
+"""Video preview functions for MoviePy editor."""
+
 import threading
 import time
 
diff --git a/moviepy/video/io/sliders.py b/moviepy/video/io/sliders.py
index 34f3975e..d8172407 100644
--- a/moviepy/video/io/sliders.py
+++ b/moviepy/video/io/sliders.py
@@ -1,3 +1,5 @@
+"""GUI matplotlib utility to tune the outputs of a function."""
+
 import matplotlib.pyplot as plt
 from matplotlib.widgets import Slider
 
diff --git a/moviepy/video/tools/segmenting.py b/moviepy/video/tools/segmenting.py
index 42d060a7..96c53f9d 100644
--- a/moviepy/video/tools/segmenting.py
+++ b/moviepy/video/tools/segmenting.py
@@ -1,3 +1,5 @@
+"""Utilities related with segmenting useful working with video clips."""
+
 import numpy as np
 import scipy.ndimage as ndi
 
diff --git a/setup.cfg b/setup.cfg
index fd41e180..df55fff3 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -6,8 +6,6 @@ extend-ignore =
     W503,
     # allow lambda expressions
     E731,
-    # don't require docstrings for public modules
-    D100,
     # don't require docstrings for public packages
     D104,
     # don't require docstrings for magic methods
@@ -26,12 +24,16 @@ per-file-ignores =
     # allow imports not placed at the top of the file
     # allow 'from moviepy import *' in editor.py
     moviepy/editor.py: E402, F403, F405
-    # the version file doesn't need module level docstring
+    # the version file doesn't require module docstring
     moviepy/version.py: D100
+    # FX modules don't require module docstring
+    moviepy/audio/fx/*.py: D100
+    moviepy/video/fx/*.py: D100
     # tests doesn't require docstring (although is recommended)
     tests/*.py: D101,D102,D103
+    # examples don't require module docstring
     # allow 'from moviepy import *' in examples
-    examples/*.py: F403, F405
+    examples/*.py: D100, F403, F405
 docstring-convention = numpy
 
 # Complexity should be decreased before uncomment:
diff --git a/tests/test_BitmapClip.py b/tests/test_BitmapClip.py
index 85b81bd2..cdaa9077 100644
--- a/tests/test_BitmapClip.py
+++ b/tests/test_BitmapClip.py
@@ -1,3 +1,5 @@
+"""BitmapClip tests."""
+
 import numpy as np
 import pytest
 
diff --git a/tests/test_Clip.py b/tests/test_Clip.py
index 950463f5..0372692f 100644
--- a/tests/test_Clip.py
+++ b/tests/test_Clip.py
@@ -1,3 +1,5 @@
+"""Clip tests."""
+
 import copy
 
 import numpy as np
diff --git a/tests/test_TextClip.py b/tests/test_TextClip.py
index d494c6d4..a9ca51d8 100644
--- a/tests/test_TextClip.py
+++ b/tests/test_TextClip.py
@@ -1,3 +1,5 @@
+"""TextClip tests."""
+
 import pytest
 
 from moviepy.utils import close_all_clips
diff --git a/tests/test_VideoClip.py b/tests/test_VideoClip.py
index 053f8cc4..787635fd 100644
--- a/tests/test_VideoClip.py
+++ b/tests/test_VideoClip.py
@@ -1,3 +1,5 @@
+"""VideoClip tests."""
+
 import copy
 import os
 
diff --git a/tests/test_examples.py b/tests/test_examples.py
index 035157e1..e61afd3b 100644
--- a/tests/test_examples.py
+++ b/tests/test_examples.py
@@ -1,3 +1,5 @@
+"""MoviePy examples tests."""
+
 import os
 
 import numpy as np
diff --git a/tests/test_ffmpeg_writer.py b/tests/test_ffmpeg_writer.py
index d1185363..a3c7e515 100644
--- a/tests/test_ffmpeg_writer.py
+++ b/tests/test_ffmpeg_writer.py
@@ -57,7 +57,10 @@ def test_ffmpeg_write_video(
 ):
     filename = os.path.join(TMP_DIR, f"moviepy_ffmpeg_write_video{ext}")
     if os.path.isfile(filename):
-        os.remove(filename)
+        try:
+            os.remove(filename)
+        except PermissionError:
+            pass
 
     logfile_name = filename + ".log"
     if os.path.isfile(logfile_name):
diff --git a/tests/test_fx.py b/tests/test_fx.py
index cf35a919..5699bf4f 100644
--- a/tests/test_fx.py
+++ b/tests/test_fx.py
@@ -1,3 +1,5 @@
+"""MoviePy video and audio effects tests."""
+
 import decimal
 import importlib
 import math
diff --git a/tests/test_tools.py b/tests/test_tools.py
index 1c974e53..7c4f7764 100644
--- a/tests/test_tools.py
+++ b/tests/test_tools.py
@@ -292,7 +292,7 @@ def test_decorators_argument_converters_consistency(decorator_name):
     This test is util to prevent next case in which the parameter names doesn't
     match between the decorator and the function definition:
 
-    >>> @convert_parameter_to_seconds(['foo'])  # doctest: +SKIP
+    >>> @convert_parameter_to_seconds(['foo'])
     >>> def whatever_function(bar):  # bar not converted to seconds
     ...     pass