#!/usr/bin/env python
# Podcast repository manager
# Copyright (C) 2012-2015 Daniel Beer <dlbeer@gmail.com>
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are
# met:
#
#   * Redistributions of source code must retain the above copyright
#     notice, this list of conditions and the following disclaimer.
#   * Redistributions in binary form must reproduce the above copyright
#     notice, this list of conditions and the following disclaimer in the
#     documentation and/or other materials provided with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
# HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

"""Podcast repository manager

This script is a simple tool for managing podcast subscriptions. It
doesn't use any global configuration or database. Instead, each
subscribed podcast is kept in its own directory, which contains the
downloaded media files. This is referred to as a podcast repository.

Each repository also contains a .getcast/ subdirectory, which may contain:

  * a configuration file, called "config"
  * a copy of the latest RSS feed, called "rss.xml"
  * a list of blocked episodes, called "done.list"

The config file contains a series of "<option> <value>" lines.
Currently, there are only two recognised options:

  rss:
    The URL of the podcast's RSS feed (required).
  rss-poll:
    The maximum age, in seconds, of a previously downloaded RSS feed
    before it is considered obsolete (optional). The default value is
    7200 (2 hours).

You shouldn't need to edit the config file by hand though. To create a
new podcast subscription, just do:

    getcast init /home/me/My_Podcast http://www.example.com/rss-feed.rss

This will create the directory "My_Podcast" with the necessary metadata
directory and configuration. Then, every time you want to fetch the
latest media files, do this:

    getcast fetch /home/me/My_Podcast

That's all there is to it -- the latest RSS will be downloaded, along
with any new media files. If you want to mark the podcast repository as
being up-to-date without actually fetching any media files, use the
--catch-up option:

    getcast fetch --catch-up /home/me/My_Podcast

There's also a simple channel guide, which uses ID3 tags to show you
descriptions of the latest media files:

    getcast guide /home/me/My_Podcast | less -r

Note that all commands, with the exception of "init", allow multiple
podcast repositories to be specified on the command-line. So, if you
keep all your podcast repositories together in one large directory,
you can easily update them all at once:

    getcast fetch /home/me/podcasts/*
"""

import os
import time
import sys
import posixpath
import textwrap
import re
from optparse import OptionParser
from mutagen.easyid3 import ID3
from os import path
from subprocess import Popen
from xml.dom import minidom

def init_dirs(castdir, rss_url):
    """Initialize a podcast repository.

    We create, if they don't already exist:
	- the podcast directory
	- the .getcast/ subdirectory
	- .getcast/config, containing a reference to the given RSS URL
    """
    if not os.access(castdir, os.F_OK):
	os.mkdir(castdir, 0755)

    pd = path.join(castdir, '.getcast')
    if not os.access(pd, os.F_OK):
	os.mkdir(pd, 0755)

    cfg = path.join(pd, 'config')
    if os.access(cfg, os.F_OK):
	print ('Config file %s already exists' % cfg)
	return

    f = file(cfg, 'w')
    f.write('rss %s\n' % rss_url)
    f.close()

    print ('Initialized podcast config in %s' % cfg)

def read_config(castdir):
    """Read the .getcast/config file from a podcast repository.

    If the file exists, a map is returned giving the key/value pairs
    specified in the config file. If the file doesn't exist, we return
    an empty map.
    """
    try: f = file(path.join(castdir, '.getcast', 'config'))
    except: return None

    cfg = {}
    for line in f.readlines():
	line = line.rstrip()
	sp = line.find(' ')
	if sp >= 0:
	    key = line[0:sp].lower()
	    value = line[sp + 1:]
	    cfg[key] = value

    f.close()
    return cfg

def download_file(castdir, url, outname):
    """Download a file using.

    A podcast repository must be specified, which will be used for temporary
    storage as the file is transferred. It will be atomically renamed into
    place once successfully downloaded. Returns True on success or False on
    failure.
    """
    tmp = path.join(castdir, '.getcast', 'download.tmp')
    result = Popen(['curl', '-L', '-#', url, '-o', tmp]).wait()
    if result == 0:
	os.rename(tmp, outname)
	return True

    try: os.unlink(tmp)
    except: pass
    return False

def fetch_rss(castdir, dryrun = False):
    """Update the podcast repository's RSS.

    The local copy of the RSS file is checked, and if not present or too old, 
    a new version is fetched from the configured RSS URL.
    """
    cfg = read_config(castdir)
    rss_url = cfg['rss']
    rss_poll = int(cfg.get('rss-poll', '7200'))
    rss_file = path.join(castdir, '.getcast', 'rss.xml')

    if not os.access(rss_file, os.F_OK):
	rss_age = 0
    else:
	rss_age = os.stat(rss_file).st_mtime

    if rss_age + rss_poll >= time.time():
	print ('RSS for %s is up to date' % castdir)
	return

    print ('Downloading RSS: %s' % rss_url)
    if not dryrun:
	download_file(castdir, rss_url, rss_file)

def read_rss_urls(castdir):
    """Return a list of enclosure URLs from the local RSS.

    If no RSS has yet been fetched, None is returned.
    """
    rss_file = path.join(castdir, '.getcast', 'rss.xml')
    if not os.access(rss_file, os.F_OK): return None
    doc = minidom.parse(rss_file)
    chan = doc.getElementsByTagName('channel')[0]
    items = chan.getElementsByTagName('item')
    lst = []
    for it in items:
	try:
	    lst.append(it.getElementsByTagName('enclosure')[0].
				getAttribute('url'))
	except:
	    pass
    return lst

def read_done_map(castdir):
    """Parse a done.list file.

    We return a map with a key for each line in the file. The values are
    all True.
    """
    try: f = file(path.join(castdir, '.getcast', 'done.list'))
    except: return {}

    m = {}
    for line in f.readlines():
	line = line.rstrip()
	m[line] = True

    f.close()
    return m

def write_done_list(castdir, lst):
    """Write a done.list file.

    We write each key in the map to the file, one per line.
    """
    lst.sort()
    f = file(path.join(castdir, '.getcast', 'done.list'), 'w')
    for i in lst:
	f.write('%s\n' % i)
    f.close()

def catch_up(castdir, dryrun = False):
    """Mark new media files as downloaded.

    Rather than downloading non-present media files, just mark them in the
    done.list file.
    """
    urls = read_rss_urls(castdir)
    if not urls:
	print 'No RSS file fetched yet'
	return

    print ('Writing %d items to done list' % len(urls))
    if not dryrun:
	write_done_list(castdir, urls)

def sanitize(name):
    """Remove any unsafe characters from the given filename."""
    name = re.sub('[^-A-Za-z_.0-9 ]', '_', name)
    name = re.sub('^[-.]', '_', name)
    return name

def fetch_files(castdir, dryrun = False):
    """Fetch missing media files for a podcast repository.

    The list of URLs is extracted from the podcast's RSS. Under normal
    operation, any URLs naming files which aren't present in the directory
    and not present in the done.list are fetched.

    The dryrun argument causes the function to print its output as normal,
    but prevents actual downloading or writing of any files.
    """

    # Load RSS and done map
    urls_raw = read_rss_urls(castdir)
    if not urls_raw:
	print 'No RSS file fetched yet'
	return

    dm = read_done_map(castdir)

    # Figure out which files we should download
    urls = []
    for u in urls_raw:
	base = posixpath.basename(u)
	outname = path.join(castdir, sanitize(base))
	if not (dm.has_key(u) or os.access(outname, os.F_OK)):
	    urls.append(u)

    # Download each file, or just mark it in the done map
    for i in xrange(0, len(urls)):
	u = urls[i]
	base = posixpath.basename(u)
	outname = path.join(castdir, sanitize(base))
	print ('[%3d/%3d] Downloading %s' % (i + 1, len(urls), base))
	if not dryrun:
	    download_file(castdir, u, outname)

def get_tag(tag, key, default = ''):
    """Fetch a tag value from an ID3.

    A default can be specified if the given tag doesn't exist or is in
    an unexpected format.
    """
    try: return tag.getall(key)[0].text[0]
    except: return default

def list_single_ep(fname, nocolor = False):
    """Print a colourized guide for an MP3 file.

    Given a filename, extract the title and comments. Display a block
    containing these and the filename. The output is colourized with
    ANSI codes, unless nocolor is specified.
    """
    epname = path.basename(fname)
    tag = ID3(fname)
    for v in textwrap.wrap(get_tag(tag, 'TIT2', 'Untitled'), 79):
	if nocolor:
	    print v.encode('utf-8')
	else:
	    print ('\x1b[1m%s\x1b[0m' % v.encode('utf-8'))
    if nocolor:
	print epname
    else:
	print ('\x1b[1;36m%s\x1b[0m' % epname)
    for v in textwrap.wrap(get_tag(tag, 'COMM:'), 79):
	print v.encode('utf-8')
    print

def banner(castname, nocolor = False):
    """Print a colourized title banner."""
    if nocolor:
	print ('*' * 79)
	print ('** %s' % castname)
	print ('*' * 79)
    else:
	print ('\x1b[1;31m%s\x1b[0m' % ('*' * 79))
	print ('\x1b[1;31m** \x1b[0;1m%s\x1b[0m' % castname)
	print ('\x1b[1;31m%s\x1b[0m' % ('*' * 79))
    print

def list_eps(cast, limit = None, nocolor = False):
    """Print a colourized channel guide for a podcast repository.

    After printing a title banner, episodes are listed in reverse
    alphabetical order (which is assumed to match chronological order),
    up to the limit specified.
    """
    banner(path.basename(cast), nocolor = nocolor)
    lst = os.listdir(cast)
    lst.sort()
    lst.reverse()
    if limit is not None and limit <= 0: limit = None
    i = 0
    while i < len(lst) and (limit is None or limit > 0):
	fname = path.join(cast, lst[i])
	if not path.isdir(fname):
	    try:
		list_single_ep(fname, nocolor = nocolor)
		limit = limit - 1
	    except:
		pass
	i = i + 1

def cmd_init(options, args):
    """'init' command.

    Arguments are a podcast repository directory and an RSS URL.
    """
    if len(args) < 2:
	sys.stderr.write(
	   'You need to specify a directory and an RSS URL\n')
	sys.exit(-1)

    init_dirs(args[0], args[1])

def cmd_fetch(options, args):
    """'fetch' command.

    Arguments are a list of podcast repositories.
    """
    for p in args:
	print ('--- %s' % posixpath.basename(p))
	fetch_rss(p, dryrun = options.dryrun)
	fetch_files(p, dryrun = options.dryrun)

def cmd_fetch_rss(options, args):
    """'fetch-rss' command.

    Arguments are a list of podcast repositories.
    """
    for p in args:
	print ('--- %s' % posixpath.basename(p))
	fetch_rss(p, dryrun = options.dryrun)

def cmd_fetch_media(options, args):
    """'fetch-media' command.

    Arguments are a list of podcast repositories.
    """
    for p in args:
	print ('--- %s' % posixpath.basename(p))
	fetch_files(p, dryrun = options.dryrun)

def cmd_catch_up(options, args):
    """'catch-up' command.

    Arguments are a list of podcast repositories.
    """
    for p in args:
	print ('--- %s' % posixpath.basename(p))
	catch_up(p, dryrun = options.dryrun)

def cmd_guide(options, args):
    """'guide' command.

    Arguments are a list of podcast repositories.
    """
    for p in args:
	list_eps(p, options.limit, nocolor = options.nocolor)

def main():
    """Program main.

    Parse options and then run the specified command.
    """
    parser = OptionParser(usage =
    """Usage: %prog [options] <command> [args ...]

Use --help to get a full list of options. Command may be any of the following:

  init <repository> <URL>
    Set up a podcast repository to track the given RSS feed.
  fetch [repository ...]
    Update RSS and fetch media files for the given repositories.
  fetch-rss [repository ...]
    Update RSS for the given repositories.
  fetch-media [repository ...]
    Fetch media files for the given repositories.
  catch-up [repository ...]
    Mark new media files as blocked without fetching them.
  guide [repository ...]
    Print a summary of the most recently fetch episodes fromt he given
    repositories.""",
    version = 'getcast, 22 Jan 2012 -- Copyright (C) 2012 Daniel Beer')

    parser.add_option('-n', '--dryrun', dest = 'dryrun',
	  action = 'store_true', default = False,
	  help = 'Don\'t actually fetch or modify anything.')
    parser.add_option('', '--no-color', dest = 'nocolor',
	  action = 'store_true', default = False,
	  help = 'Don\'t print ANSI colour codes.')
    parser.add_option('-l', '--limit', dest = 'limit',
	  action = 'store', default = 2, type = 'int',
	  help = 'Limit on the number of episodes to show in the guide.')

    (options, args) = parser.parse_args()
    if len(args) < 1:
	parser.error('No command has been given')

    commands = {
	'init': cmd_init,
	'fetch': cmd_fetch,
	'fetch-rss': cmd_fetch_rss,
	'fetch-media': cmd_fetch_media,
	'catch-up': cmd_catch_up,
	'guide': cmd_guide
    }

    func = commands.get(args[0])
    if not func:
	parser.error('Unknown command: %s' % args[0])

    func(options, args[1:])

if __name__ == '__main__':
    main()