Usage: episode-filer.py [options] FILE/DIR
     
     episode-filer organizes your tv shows!
     
     Options:
       --version             show program's version number and exit
       -h, --help            show this help message and exit
       -p, --pretend         do not actually move any files, just show what would
                             have happened
       -b DIR, --base=DIR    use DIR as sorting base
       -r, --recursive       if passing in a directory, recursively look for files.
       -v, --verbose         be more verbose.
       -e EXTENSIONS, --extensions=EXTENSIONS
                             filter by this set of extensions, comma delimited.
                             Default is .avi,.mkv.  If "*", all files will be
                             examined.
       --interactive     Ask before moving each file.  Default is False.

episode-filer assumes a heirarchy of base/TV Show Name/Season N/filename.avi.
It assumes the input files will have the show name in the beginning of the name and then the episode and season information.

Instructions
============
To sort a file, you'll need to do a little preparation on your directory tree.

First, you'll need some sort of base directory.
	ex: /vault/public/tv
Then, you'll need subdirectories in base to be named after TV shows, like Fringe or The Big Bang Theory.
	ex: /vault/public/tv/Fringe
	ex: /vault/public/tv/Big\ Bang\ Theory
episode-filer will use the beginning of the to-be-sorted file as a clue to which TV show it is.  You can give episode-filer guidance on this by adding a .names file inside the TV show directory.
	ex: /vault/public/tv/Sarah\ Jane\ Adventures/.names

You can then run episode-filer on some files, and if you point them to a base, it will try to move them to the right space.

Here's some samples to show off how nifty the filename parsing is:
     episode-filer.py --pretend --base /vault/public/tv /vault/public/unsorted/
    
     Filename: /vault/public/unsorted/heroes.308.hdtv-lol.avi
     Show: heroes, Season: 3, Episode: 8
     Would move /vault/public/unsorted/heroes.308.hdtv-lol.avi to /vault/public/tv/Heroes/Season 3
     
     Filename: /vault/public/unsorted/The.Office.S05E02.HDTV.XviD-LOL.[VTV].avi
     Show: the office, Season: 5, Episode: 2
     Would move /vault/public/unsorted/The.Office.S05E02.HDTV.XviD-LOL.[VTV].avi to /vault/public/tv/The Office (US)/Season 5
     
     Filename: /vault/public/unsorted/the_big_bang_theory.2x09.the_white_asparagus_triangulation.hdtv_xvid-fov.avi
     Show: the big bang theory, Season: 2, Episode: 9
     Would move /vault/public/unsorted/the_big_bang_theory.2x09.the_white_asparagus_triangulation.hdtv_xvid-fov.avi to /vault/public/tv/Big Bang Theory/Season 2

However, the current version of episode-filer cannot perform magic.  This is what it looks like when episode-filer cannot parse a filename.

    Unable to parse /vault/public/unsorted/The Best Of Christopher Walken.avi

Parsing Filenames
=================
episode-filer uses the XBMC regexes to get the season and episode information from a filename.  It then takes the part of the filename that comes before the season and episode information as the name.  To account for minor changes in the name, it cleans the name up into a "clean TV show name".

Clean TV Show Names
===================
The rules for what make up a clean TV show name is inside of tvorg's clean_tv_show() function.

The rules are as follows:
* Turn all _'s and .'s into spaces.
* Make the name lowercase, and then remove any whitespace from the beginning or end.
* If the name ends with " -", remove it.

Some examples:

    >>> clean_show_name('The.IT.Crowd.')
    'the it crowd'

    >>> clean_show_name('Doctor Who - ')
    'doctor who'

    >>> clean_show_name('Coupling ')
    'coupling'

    >>> clean_show_name('heroes_')
    'heroes'

    >>> clean_show_name('the_big_bang_theory.')
    'the big bang theory'

.names Files
============
Without a .names file, only files that have the same "clean TV show name" as the directory's "clean TV show name" will be placed in that diretory.

If you put a file called .names inside a TV show directory, it will use each line's contents as a possible "clean TV show name" for that directory.  It will no longer use the "clean TV show name" of the directory, so if you want that name as an optoin, include it in the .names file.

If you have a top-level directory inside of base that you do not want anything sorted into, you can place an empty .names file into the directory, or a .names file where every line begins with a #.

Some examples:

I have a directory in my base called Doctor Who.  That's for *old* Doctor Who, and it has DVD images in it.  Nothing ever should get automatically sorted into this directory.  I also have a directory in my base called Doctor Who (2005).  That is for the new series.  However, some files that should get autofiled in Doctor Who (2005) have a "clean tv show name" of doctor who.  If I don't tell episode-filer to ignore Doctor Who, I will get new episodes autofiled into the old directory.  I fix this with the following .names files.

"/vault/public/tv/Doctor Who/.names":
    #ignore

"/vault/public/tv/Doctor Who (2005)/.names":
    doctor who
    doctor who 2005
    doctor who 2006
    doctor who 2007
    dr who
    drwho2007

Some more examples:

"/vault/public/tv/Avatar/.names":
    avatar
    avatar - the last airbender
    avatar the last airbender

"/vault/public/tv/Battlestar Galactica/.names":
    battlestar galactica
    bsg

Using names-detector to create .names files
===========================================
There's also a helper program names-detector.

    Usage: names-detector.py [options]
         
    names-detector.py scans the specified directory for tv show files.  It will print out a
    summary of the "clean tv show names" of the files it can parse.
   
    Options:
       --version             show program's version number and exit
       -h, --help            show this help message and exit
       -d DIRECTORY, --directory=DIRECTORY
                             scan DIRECTORY (defaults to current directory)

Example usage:

    wolf@danny:/vault/public/tv/Battlestar Galactica$ ~/project/episode-filer/names-detector.py 

    battlestar galactica
    bsg

Todo
====
I'd like to add more tests, and move some more logic into tvorg.py instead of the episode-filer.  Whenever deluge finally gets an RSS plugin that can run headless, I'll make the effort to make a deluge plugin for this.  Then you can subscribe to an RSS feed of tv shows, and deluge will automatically move them into your tv directories when they're completed, and continue to share from there.

Changelog
=========
For more change information than this, look at the git commit logs at http://github.com/adamwolf/episode-filer/.

v0.2: first real public release. It hasn't been unstable or misbehaving when I've used it, but I am the author.

Licensing
=======
This software is copyright 2009 Adam Wolf, and is distributed under the terms of the GNU General Public License.

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.

Troubleshooting, Questions, or Comments:
========================================
episode-filer is located at http://feelslikeburning.com/projects/episode-filer

The code is currently maintained at http://github.com/adamwolf/episode-filer

Feel free to contact me at http://feelslikeburning.com/contact