Merge pull request gpodder#1674 from tpikonen/docstrings

Fix docstring formatting

Author: elelay

setup.cfg

@@ -10,4 +10,4 @@ known_first_party=gpodder,soco
 
 [flake8]
 max-line-length = 142
-ignore = BLK100, CCR001, CNL100, D1, E126, E128, E402, I, W503, Q000
+ignore = BLK100, CCR001, CNL100, D1, E126, E128, E402, I, W503, Q000, SC

share/gpodder/examples/hello_world.py

@@ -40,9 +40,7 @@ def on_unload(self):
         logger.info('Extension is being unloaded.')
 
     def on_ui_object_available(self, name, ui_object):
-        """
-        Called by gPodder when ui is ready.
-        """
+        """Called by gPodder when ui is ready."""  # noqa: D401
         if name == 'gpodder-gtk':
             self.gpodder = ui_object
 

share/gpodder/extensions/enqueue_in_mediaplayer.py

@@ -81,9 +81,8 @@ def open_files(self, filenames):
 
 
 class MPRISResumer(FreeDesktopPlayer):
-    """
-    resume episod playback at saved time
-    """
+    """Resume episode playback at saved time."""
+
     OBJECT_PLAYER = '/org/mpris/MediaPlayer2'
     OBJECT_DBUS = '/org/freedesktop/DBus'
     INTERFACE_PLAYER = 'org.mpris.MediaPlayer2.Player'

share/gpodder/extensions/filter.py

@@ -24,13 +24,15 @@
 
 
 class BlockExceptFrame:
-    """
-    Utility class to manage a Block or Except frame, with sub-widgets:
+    """Utility class to manage a Block or Except frame.
+
+    With sub-widgets:
      - Creation as well as internal UI change is handled;
      - Changes to the other widget and to the model have to be handled outside.
     It's less optimized than mapping each widget to a different signal handler,
     but makes shorter code.
     """
+
     def __init__(self, value, enable_re, enable_ic, on_change_cb):
         self.on_change_cb = on_change_cb
         self.frame = Gtk.Frame()

share/gpodder/extensions/mpris-listener.py

@@ -51,9 +51,11 @@ def subsecond_difference(usec1, usec2):
 
 
 class CurrentTrackTracker(object):
-    """An instance of this class is responsible for tracking the state of the
-    currently playing track -- it's playback status, playing position, etc.
+    """This class tracks the state of the currently playing track.
+
+    Playback status, playing position, etc.
     """
+
     def __init__(self, notifier):
         self.uri = None
         self.length = None

share/gpodder/extensions/notification-win32.py

@@ -17,9 +17,9 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
-# Notification implementation for Windows
 # Sean Munkel; 2012-12-29
-"""
+"""Notification implementation for Windows.
+
 Current state (2018/07/29 ELL):
  - I can't get pywin32 to work in msys2 (the platform used for this python3/gtk3 installer)
    so existing code using COM doesn't work.

share/gpodder/extensions/podverse.py

@@ -61,7 +61,8 @@ def on_search(self, query):
 
 
 class gPodderExtension:
-    """ (un)register a podverse search provider """
+    """Register and unregister a podverse search provider."""
+
     def __init__(self, container):
         pass
 

share/gpodder/extensions/rockbox_convert2mp4.py

@@ -100,8 +100,7 @@ def _calc_resolution(self, video_width, video_height, device_width, device_heigh
         return (int(round(dest_width)), round(int(dest_height)))
 
     def _convert_mp4(self, episode, from_file):
-        """Convert MP4 file to rockbox mpg file"""
-
+        """Convert MP4 file to rockbox mpg file."""
         # generate new filename and check if the file already exists
         to_file = self._get_rockbox_filename(from_file)
         if to_file is None:

share/gpodder/extensions/sonos.py

@@ -50,8 +50,7 @@ def __init__(self, container):
                 self.speakers[uid] = speaker
 
     def _stream_to_speaker(self, speaker_uid, episodes):
-        """ Play or enqueue selected episodes """
-
+        """Play or enqueue selected episodes."""
         urls = [episode.url for episode in episodes if SONOS_CAN_PLAY(episode)]
         logger.info('Streaming to Sonos %s: %s' % (self.speakers[speaker_uid].ip_address, ', '.join(urls)))
 
@@ -65,8 +64,7 @@ def _stream_to_speaker(self, speaker_uid, episodes):
         controller.play()
 
     def on_episodes_context_menu(self, episodes):
-        """ Adds a context menu for each Sonos speaker group """
-
+        """Add a context menu for each Sonos speaker group."""
         # Only show context menu if we can play at least one file
         if not any(SONOS_CAN_PLAY(e) for e in episodes):
             return []

share/gpodder/extensions/tagging.py

@@ -125,12 +125,12 @@ def write_basic_tags(self, remove_before_modify, modify_tags, set_artist_to_albu
             audio.save()
 
     def insert_coverart(self):
-        """ implement the cover art logic in the subclass
-        """
+        """Implement the cover art logic in the subclass."""
         None
 
     def get_cover_picture(self, cover):
-        """ Returns mutagen Picture class for the cover image
+        """Return mutagen Picture class for the cover image.
+
         Useful for OGG and FLAC format
 
         Picture type = cover image

share/gpodder/extensions/taskbar_progress.py

@@ -151,7 +151,7 @@ class ITaskbarList3(ITaskbarList2):
 
 
 def consume_events():
-    """ consume pending events """
+    """Consume pending events."""
     while Gtk.events_pending():
         Gtk.main_iteration()
 

share/gpodder/extensions/ted_subtitles.py

@@ -22,15 +22,16 @@
 
 
 class gPodderExtension(object):
+    """TED Subtitle Download Extension.
+
+    Downloads ted subtitles.
     """
-    TED Subtitle Download Extension
-    Downloads ted subtitles
-    """
+
     def __init__(self, container):
         self.container = container
 
     def milli_to_srt(self, time):
-        """Converts milliseconds to srt time format"""
+        """Convert milliseconds to srt time format."""
         srt_time = timedelta(milliseconds=time)
         srt_time = str(srt_time)
         if '.' in srt_time:
@@ -42,7 +43,7 @@ def milli_to_srt(self, time):
         return srt_time
 
     def ted_to_srt(self, jsonstring, introduration):
-        """Converts the json object to srt format"""
+        """Convert the json object to srt format."""
         jsonobject = json.loads(jsonstring)
 
         srtContent = ''

share/gpodder/extensions/youtube-dl.py

@@ -60,7 +60,7 @@
 
 
 def youtube_parsedate(s):
-    """Parse a string into a unix timestamp
+    """Parse a string into a unix timestamp.
 
     Only strings provided by youtube-dl API are
     parsed with this function (20170920).
@@ -71,18 +71,16 @@ def youtube_parsedate(s):
 
 
 def video_guid(video_id):
-    """
-    generate same guid as youtube
-    """
+    """Generate same guid as youtube."""
     return 'yt:video:{}'.format(video_id)
 
 
 class YoutubeCustomDownload(download.CustomDownload):
-    """
-    Represents the download of a single episode using youtube-dl.
+    """Represents the download of a single episode using youtube-dl.
 
     Actual youtube-dl interaction via gPodderYoutubeDL.
     """
+
     def __init__(self, ytdl, url, episode):
         self._ytdl = ytdl
         self._url = url
@@ -100,9 +98,7 @@ def partial_filename(self, val):
         self._partial_filename = val
 
     def retrieve_resume(self, tempname, reporthook=None):
-        """
-        called by download.DownloadTask to perform the download.
-        """
+        """Called by download.DownloadTask to perform the download."""  # noqa: D401
         self._reporthook = reporthook
         # outtmpl: use given tempname by DownloadTask
         # (escape % because outtmpl used as a string template by youtube-dl)
@@ -177,9 +173,8 @@ def _my_hook(self, d):
 
 
 class YoutubeFeed(model.Feed):
-    """
-    Represents the youtube feed for model.PodcastChannel
-    """
+    """Represents the youtube feed for model.PodcastChannel."""
+
     def __init__(self, url, cover_url, description, max_episodes, ie_result, downloader):
         self._url = url
         self._cover_url = cover_url
@@ -222,12 +217,18 @@ def get_cover_url(self):
         return self._cover_url
 
     def get_http_etag(self):
-        """ :return str: optional -- last HTTP etag header, for conditional request next time """
+        """Return the last HTTP etag header, for conditional request next time.
+
+        :return str: optional.
+        """
         # youtube-dl doesn't provide it!
         return None
 
     def get_http_last_modified(self):
-        """ :return str: optional -- last HTTP Last-Modified header, for conditional request next time """
+        """Return the last HTTP Last-Modified header, for conditional request next time.
+
+        :return str: optional
+        """
         # youtube-dl doesn't provide it!
         return None
 
@@ -274,8 +275,8 @@ def get_new_episodes(self, channel, existing_guids):
         return episodes, all_seen_guids
 
     def get_next_page(self, channel, max_episodes):
-        """
-        Paginated feed support (RFC 5005).
+        """Paginated feed support (RFC 5005).
+
         If the feed is paged, return the next feed page.
         Returned page will in turn be asked for the next page, until None is returned.
         :return feedcore.Result: the next feed's page,
@@ -322,7 +323,7 @@ def __init__(self, gpodder_config, my_config, force=False):
             self._ydl_opts['logger'] = logger
 
     def add_format(self, gpodder_config, opts, fallback=None):
-        """ construct youtube-dl -f argument from configured format. """
+        """Construct youtube-dl -f argument from configured format."""
         # You can set a custom format or custom formats by editing the config for key
         # `youtube.preferred_fmt_ids`
         #
@@ -447,9 +448,10 @@ def extract_type(ie_result):
             YoutubeFeed(url, cover_url, description, max_episodes, ie_result, self))
 
     def fetch_channel(self, channel, max_episodes=0):
-        """
-        called by model.gPodderFetcher to get a custom feed.
-        :returns feedcore.Result: a YoutubeFeed or None if channel is not a youtube channel or playlist
+        """Return a custom feed. Called by model.gPodderFetcher.
+
+        :returns feedcore.Result: A YoutubeFeed or None if channel is not
+                                  a youtube channel or playlist
         """
         if not self.my_config.manage_channel:
             return None
@@ -493,9 +495,7 @@ def is_supported_url(self, url):
         return False
 
     def custom_downloader(self, unused_config, episode):
-        """
-        called from registry.custom_downloader.resolve
-        """
+        """Called from registry.custom_downloader.resolve."""  # noqa: D401
         if not self.force and not self.my_config.manage_downloads:
             return None
 

src/gpodder/__init__.py

@@ -233,11 +233,12 @@ def fixup_home(old_home):
 
 
 def load_plugins():
-    """Load (non-essential) plugin modules
+    """Load (non-essential) plugin modules.
 
     This loads a default set of plugins, but you can use
     the environment variable "GPODDER_PLUGINS" to modify
-    the list of plugins."""
+    the list of plugins.
+    """
     PLUGINS = os.environ.get('GPODDER_PLUGINS', None)
     if PLUGINS is None:
         PLUGINS = DEFAULT_PLUGINS

src/gpodder/build_info.py

@@ -6,7 +6,7 @@
 # the Free Software Foundation; either version 3 of the License, or
 # (at your option) any later version.
 
-"""This file gets edited at build time to add build specific data"""
+"""This file gets edited at build time to add build specific data."""
 
 BUILD_TYPE = u"default"
 """Either 'windows', 'windows-portable', 'osx' or 'default'"""

src/gpodder/common.py

@@ -32,7 +32,7 @@
 
 
 def clean_up_downloads(delete_partial=False):
-    """Clean up temporary files left behind by old gPodder versions
+    """Clean up temporary files left behind by old gPodder versions.
 
     delete_partial - If True, also delete in-progress downloads
     """
@@ -48,7 +48,7 @@ def clean_up_downloads(delete_partial=False):
 
 
 def find_partial_downloads(channels, start_progress_callback, progress_callback, final_progress_callback, finish_progress_callback):
-    """Find partial downloads and match them with episodes
+    """Find partial downloads and match them with episodes.
 
     channels - A list of all model.PodcastChannel objects
     start_progress_callback - A callback(count) when partial files are searched

src/gpodder/config.py

@@ -332,8 +332,7 @@ def __init__(self, filename='gpodder.json'):
             logger.info('Appending alternate PATH: %s' % self.path.alternate)
 
     def register_defaults(self, defaults):
-        """
-        Register default configuration options (e.g. for extensions)
+        """Register default configuration options (e.g. for extensions).
 
         This function takes a dictionary that will be merged into the
         current configuration if the keys don't yet exist. This can
@@ -342,9 +341,9 @@ def register_defaults(self, defaults):
         self.__json_config._merge_keys(defaults)
 
     def add_observer(self, callback):
-        """
-        Add a callback function as observer. This callback
-        will be called when a setting changes. It should
+        """Add a callback function as observer.
+
+        This callback will be called when a setting changes. It should
         have this signature:
 
             observer(name, old_value, new_value)
@@ -358,9 +357,7 @@ def add_observer(self, callback):
             logger.warning('Observer already added: %s', repr(callback))
 
     def remove_observer(self, callback):
-        """
-        Remove an observer previously added to this object.
-        """
+        """Remove an observer previously added to this object."""
         if callback in self.__observers:
             self.__observers.remove(callback)
         else:
@@ -425,7 +422,7 @@ def toggle_flag(self, name):
         setattr(self, name, not getattr(self, name))
 
     def update_field(self, name, new_value):
-        """Update a config field, converting strings to the right types"""
+        """Update a config field, converting strings to the right types."""
         old_value = self._lookup(name)
         new_value = string_to_config_value(new_value, old_value)
         setattr(self, name, new_value)
@@ -455,7 +452,7 @@ def __setattr__(self, name, value):
         setattr(self.__json_config, name, value)
 
     def migrate_defaults(self):
-        """ change default values in config """
+        """Change default values in config."""
         if self.device_sync.max_filename_length == 999:
             logger.debug("setting config.device_sync.max_filename_length=120"
                          " (999 is bad for NTFS and ext{2-4})")