Add docstrings; Remove verbose comments; Fix errors introduced with cleanup

This comment will:
- Transform docstrings above functions into docstrings
- Remove some way too verbose comments
- Apply some more recommendations from PEP8 forgotten last time
- Fix some errors introduced with the first code cleanup

Work left to do:
- Add params to docstrings
- Rename file variables

core/convert.py

@@ -4,11 +4,13 @@ import sys
 
 
 def song(input_song, output_song, avconv=False, verbose=False):
+    """Do the audio format conversion."""
     if not input_song == output_song:
         if sys.version_info < (3, 0):
             input_song = input_song.encode('utf-8')
             output_song = output_song.encode('utf-8')
-        print('Converting ' + input_song + ' to ' + output_song.split('.')[-1])
+        print('Converting {0} to {1}'.format(
+            input_song, output_song.split('.')[-1]))
         if avconv:
             exit_code = convert_with_avconv(input_song, output_song, verbose)
         else:
@@ -18,7 +20,7 @@ def song(input_song, output_song, avconv=False, verbose=False):
 
 
 def convert_with_avconv(input_song, output_song, verbose):
-    # different path for windows
+    """Convert the audio file using avconv."""
     if os.name == 'nt':
         avconv_path = 'Scripts\\avconv.exe'
     else:
@@ -39,13 +41,16 @@ def convert_with_avconv(input_song, output_song, verbose):
 
 
 def convert_with_ffmpeg(input_song, output_song, verbose):
-    # What are the differences and similarities between ffmpeg, libav, and avconv?
+    """Convert the audio file using FFMpeg.
-    # https://stackoverflow.com/questions/9477115
+
-    # ffmeg encoders high to lower quality
+    What are the differences and similarities between ffmpeg, libav, and avconv?
-    # libopus > libvorbis >= libfdk_aac > aac > libmp3lame
+    https://stackoverflow.com/questions/9477115
-    # libfdk_aac due to copyrights needs to be compiled by end user
+    ffmeg encoders high to lower quality
-    # on MacOS brew install ffmpeg --with-fdk-aac will do just that. Other OS?
+    libopus > libvorbis >= libfdk_aac > aac > libmp3lame
-    # https://trac.ffmpeg.org/wiki/Encode/AAC
+    libfdk_aac due to copyrights needs to be compiled by end user
+    on MacOS brew install ffmpeg --with-fdk-aac will do just that. Other OS?
+    https://trac.ffmpeg.org/wiki/Encode/AAC
+    """
 
     if os.name == "nt":
         ffmpeg_pre = 'Scripts\\ffmpeg.exe '

core/metadata.py

@@ -10,8 +10,8 @@ except ImportError:
     import urllib.request as urllib2
 
 
-# check if input file title matches with expected title
 def compare(file, metadata):
+    """Check if the input file title matches the expected title."""
     already_tagged = False
     try:
         if file.endswith('.mp3'):
@@ -29,6 +29,7 @@ def compare(file, metadata):
 
 
 def embed(music_file, meta_tags):
+    """Embed metadata."""
     if sys.version_info < (3, 0):
         music_file = music_file.encode('utf-8')
     if meta_tags is None:
@@ -46,6 +47,7 @@ def embed(music_file, meta_tags):
 
 
 def embed_mp3(music_file, meta_tags):
+    """Embed metadata to MP3 files."""
     # EasyID3 is fun to use ;)
     audiofile = EasyID3('Music/' + music_file)
     audiofile['artist'] = meta_tags['artists'][0]['name']
@@ -81,6 +83,7 @@ def embed_mp3(music_file, meta_tags):
 
 
 def embed_m4a(music_file, meta_tags):
+    """Embed metadata to M4A files."""
     # Apple has specific tags - see mutagen docs -
     # http://mutagen.readthedocs.io/en/latest/api/mp4.html
     tags = {'album': '\xa9alb',

core/misc.py

@@ -10,8 +10,8 @@ except ImportError:
     from urllib.request import quote
 
 
-# method to input (user playlists) and (track when using manual mode)
 def input_link(links):
+    """Let the user input a number."""
     while True:
         try:
             the_chosen_one = int(user_input('>> Choose your number: '))
@@ -25,16 +25,16 @@ def input_link(links):
             print('Choose a valid number!')
 
 
-# take input correctly for both python2 & 3
 def user_input(string=''):
+    """Take input correctly for both Python 2 & 3."""
     if sys.version_info > (3, 0):
         return input(string)
     else:
         return raw_input(string)
 
 
-# remove first song from .txt
 def trim_song(file):
+    """Remove the first song from file."""
     with open(file, 'r') as file_in:
         data = file_in.read().splitlines(True)
     with open(file, 'w') as file_out:
@@ -77,27 +77,29 @@ def get_arguments():
     return parser.parse_args()
 
 
-# check if input song is spotify link
 def is_spotify(raw_song):
-    if (len(raw_song) == 22 and raw_song.replace(" ", "%20") == raw_song) or (raw_song.find('spotify') > -1):
+    """Check if the input song is a Spotify link."""
+    if (len(raw_song) == 22 and raw_song.replace(" ", "%20") == raw_song) or \
+            (raw_song.find('spotify') > -1):
         return True
     else:
         return False
 
 
-# generate filename of the song to be downloaded
 def generate_filename(title):
+    """Generate filename of the song to be downloaded."""
     # IMO python2 sucks dealing with unicode
     title = fix_encoding(title)
     title = fix_decoding(title)
     title = title.replace(' ', '_')
+
     # slugify removes any special characters
     filename = slugify(title, ok='-_()[]{}', lower=False)
     return fix_encoding(filename)
 
 
-# please respect these credentials :)
 def generate_token():
+    """Generate the token. Please respect these credentials :)"""
     credentials = oauth2.SpotifyClientCredentials(
         client_id='4fe3fecfe5334023a1472516cc99d805',
         client_secret='0f02b7c483c04257984695007a4a8d5c')
@@ -106,20 +108,22 @@ def generate_token():
 
 
 def generate_search_url(song):
+    """Generate YouTube search URL for the given song."""
     # urllib2.quote() encodes URL with special characters
     url = "https://www.youtube.com/results?sp=EgIQAQ%253D%253D&q={0}".format(
         quote(song))
     return url
 
 
-# fix encoding issues in python2
 def fix_encoding(query):
+    """Fix encoding issues in Python 2."""
     if sys.version_info < (3, 0):
         query = query.encode('utf-8')
     return query
 
 
 def fix_decoding(query):
+    """Fix decoding issues in Python 2."""
     if sys.version_info < (3, 0):
         query = query.decode('utf-8')
     return query

spotdl.py

@@ -19,16 +19,16 @@ except ImportError:
     import urllib.request as urllib2
 
 
-# "[artist] - [song]"
 def generate_songname(raw_song):
+    """Generate a string of the format '[artist] - [song]' for the given song."""
     if misc.is_spotify(raw_song):
         tags = generate_metadata(raw_song)
         raw_song = '{0} - {1}'.format(tags['artists'][0]['name'], tags['name'])
     return misc.fix_encoding(raw_song)
 
 
-# fetch song's metadata from spotify
 def generate_metadata(raw_song):
+    """Fetch a song's metadata from Spotify."""
     if misc.is_spotify(raw_song):
         # fetch track information directly if it is spotify link
         meta_tags = spotify.track(raw_song)
@@ -60,9 +60,8 @@ def generate_metadata(raw_song):
 
 
 def generate_youtube_url(raw_song):
-    # decode spotify http link to "[artist] - [song]"
+    """Search for the song on YouTube and generate an URL to its video."""
     song = generate_songname(raw_song)
-    # generate direct search YouTube URL
     search_url = misc.generate_search_url(song)
     item = urllib2.urlopen(search_url).read()
     # item = unicode(item, 'utf-8')
@@ -97,23 +96,21 @@ def generate_youtube_url(raw_song):
                 attrs={'class': 'yt-uix-tile-link'})[check]['href']
             check += 1
 
-    full_link = "youtube.com{0}'.format(result)
+    full_link = 'youtube.com{0}'.format(result)
     return full_link
 
 
-# parse track from YouTube
 def go_pafy(raw_song):
-    # video link of the video to extract audio from
+    """Parse track from YouTube."""
     track_url = generate_youtube_url(raw_song)
     if track_url is None:
         return None
     else:
-        # parse the YouTube video
         return pafy.new(track_url)
 
 
-# title of the YouTube video
 def get_youtube_title(content, number=None):
+    """Get the YouTube video's title."""
     title = misc.fix_encoding(content.title)
     if number is None:
         return title
@@ -121,14 +118,12 @@ def get_youtube_title(content, number=None):
         return '{0}. {1}'.format(number, title)
 
 
-# fetch user playlists when using -u option
 def feed_playlist(username):
-    # fetch all user playlists
+    """Fetch user playlists when using the -u option."""
     playlists = spotify.user_playlists(username)
     links = []
     check = 1
 
-    # iterate over user playlists
     while True:
         for playlist in playlists['items']:
             # in rare cases, playlists may not be found, so playlists['next']
@@ -145,13 +140,10 @@ def feed_playlist(username):
             break
 
     print('')
-    # let user select playlist
     playlist = misc.input_link(links)
-    # fetch detailed information for playlist
     results = spotify.user_playlist(
         playlist['owner']['id'], playlist['id'], fields='tracks,next')
     print('')
-    # slugify removes any special characters
     file = '{0}.txt'.format(slugify(playlist['name'], ok='-_()[]{}'))
     print('Feeding {0} tracks to {1}'.format(playlist['tracks']['total'], file))
 
@@ -174,11 +166,10 @@ def feed_playlist(username):
 
 
 def download_song(content):
+    """Download the audio file from YouTube."""
     if args.input_ext == '.webm':
-        # best available audio in .webm
         link = content.getbestaudio(preftype='webm')
     elif args.input_ext == '.m4a':
-        # best available audio in .webm
         link = content.getbestaudio(preftype='m4a')
     else:
         return False
@@ -187,14 +178,13 @@ def download_song(content):
         return False
     else:
         music_file = misc.generate_filename(content.title)
-        # download link
         link.download(
             filepath='Music/{0}{1}'.format(music_file, args.input_ext))
         return True
 
 
-# check if input song already exists in Music folder
 def check_exists(music_file, raw_song, islist=True):
+    """Check if the input song already exists in the 'Music' folder."""
     files = os.listdir('Music')
     for file in files:
         if file.endswith('.temp'):
@@ -229,8 +219,8 @@ def check_exists(music_file, raw_song, islist=True):
     return False
 
 
-# download songs from list
 def grab_list(file):
+    """Download all songs from the list."""
     with open(file, 'r') as listed:
         lines = (listed.read()).splitlines()
     # ignore blank lines in file (if any)
@@ -270,9 +260,8 @@ def grab_list(file):
         number += 1
 
 
-# logic behind downloading some song
 def grab_single(raw_song, number=None):
-    # check if song is being downloaded from list
+    """Logic behind downloading a song."""
     if number:
         islist = True
     else:
@@ -283,6 +272,7 @@ def grab_single(raw_song, number=None):
     # print '[number]. [artist] - [song]' if downloading from list
     # otherwise print '[artist] - [song]'
     print(get_youtube_title(content, number))
+
     # generate file name of the song to download
     music_file = misc.generate_filename(content.title)
     music_file = misc.fix_decoding(music_file)
@@ -291,9 +281,7 @@ def grab_single(raw_song, number=None):
             print('')
             input_song = music_file + args.input_ext
             output_song = music_file + args.output_ext
-            convert.song(input_song,
+            convert.song(input_song, output_song, avconv=args.avconv,
-                         output_song,
-                         avconv=args.avconv,
                          verbose=args.verbose)
             os.remove('Music/{0}'.format(file))
             meta_tags = generate_metadata(raw_song)

test/test_username.py

@@ -22,7 +22,8 @@ def test_playlist():
 def test_tracks():
     playlist = spotdl.spotify.user_playlists(username)['items'][0]
     expect_lines = playlist['tracks']['total']
-    result = spotdl.spotify.user_playlist(playlist['owner']['id'], playlist['id'], fields='tracks,next')
+    result = spotdl.spotify.user_playlist(
+        playlist['owner']['id'], playlist['id'], fields='tracks,next')
     tracks = result['tracks']
 
     with open('list.txt', 'a') as fout: