api.py

# ##############################################################################
#  Author: echel0n <[email protected]>
#  URL: https://sickrage.ca/
#  Git: https://git.sickrage.ca/SiCKRAGE/sickrage.git
#  -
#  This file is part of SiCKRAGE.
#  -
#  SiCKRAGE 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.
#  -
#  SiCKRAGE 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 SiCKRAGE.  If not, see <http://www.gnu.org/licenses/>.
# ##############################################################################


import collections
import datetime
import os
import re
import threading
import time
import traceback
from urllib.parse import unquote_plus

from sqlalchemy import orm
from tornado.escape import json_encode, recursive_unicode
from tornado.web import RequestHandler

import sickrage
from sickrage.core.caches import image_cache
from sickrage.core.common import ARCHIVED, DOWNLOADED, IGNORED, \
    Overview, Quality, SKIPPED, SNATCHED, SNATCHED_PROPER, UNAIRED, UNKNOWN, \
    WANTED, dateFormat, dateTimeFormat, get_quality_string, statusStrings, \
    timeFormat
from sickrage.core.databases.cache import CacheDB
from sickrage.core.databases.main import MainDB
from sickrage.core.exceptions import CantUpdateShowException, CantRemoveShowException, CantRefreshShowException, \
    EpisodeNotFoundException
from sickrage.core.helpers import chmod_as_parent, make_dir, \
    pretty_file_size, sanitize_file_name, srdatetime, try_int, read_file_buffered, backup_app_data
from sickrage.core.media.banner import Banner
from sickrage.core.media.fanart import FanArt
from sickrage.core.media.network import Network
from sickrage.core.media.poster import Poster
from sickrage.core.queues.search import BacklogQueueItem, ManualSearchQueueItem
from sickrage.core.tv.show.coming_episodes import ComingEpisodes
from sickrage.core.tv.show.helpers import find_show, get_show_list
from sickrage.core.tv.show.history import History
from sickrage.indexers import IndexerApi
from sickrage.indexers.exceptions import indexer_error, \
    indexer_showincomplete, indexer_shownotfound
from sickrage.indexers.helpers import map_indexers
from sickrage.indexers.ui import AllShowsUI
from sickrage.subtitles import Subtitles

indexer_ids = ["indexerid", "tvdbid"]

RESULT_SUCCESS = 10  # only use inside the run methods
RESULT_FAILURE = 20  # only use inside the run methods
RESULT_TIMEOUT = 30  # not used yet :(
RESULT_ERROR = 40  # only use outside of the run methods !
RESULT_FATAL = 50  # only use in Api.default() ! this is the "we encountered an internal error" error
RESULT_DENIED = 60  # only use in Api.default() ! this is the access denied error

result_type_map = {
    RESULT_SUCCESS: "success",
    RESULT_FAILURE: "failure",
    RESULT_TIMEOUT: "timeout",
    RESULT_ERROR: "error",
    RESULT_FATAL: "fatal",
    RESULT_DENIED: "denied",
}

best_quality_list = [
    "sdtv", "sddvd", "hdtv", "rawhdtv", "fullhdtv", "hdwebdl", "fullhdwebdl", "hdbluray", "fullhdbluray",
    "udh4ktv", "uhd4kbluray", "udh4kwebdl", "udh8ktv", "uhd8kbluray", "udh8kwebdl"
]

any_quality_list = best_quality_list + ["unknown"]


# basically everything except RESULT_SUCCESS / success is bad
class ApiHandler(RequestHandler):
    """ api class that returns json results """
    version = 5  # use an int since float-point is unpredictable

    async def prepare(self, *args, **kwargs):
        threading.currentThread().setName("API")

        # set the output callback
        # default json
        output_callback_dict = {
            'default': self._out_as_json,
            'image': self._out_as_image,
        }

        if sickrage.app.config.api_key == self.path_args[0]:
            access_msg = "IP:{} - ACCESS GRANTED".format(self.request.remote_ip)
            sickrage.app.log.debug(access_msg)

            # set the original call_dispatcher as the local _call_dispatcher
            _call_dispatcher = self.call_dispatcher

            # if profile was set wrap "_call_dispatcher" in the profile function
            if 'profile' in self.request.arguments:
                from profilehooks import profile

                _call_dispatcher = profile(_call_dispatcher, immediate=True)
                del self.request.arguments["profile"]

            try:
                out_dict = await self.route(_call_dispatcher, **self.request.arguments)
            except Exception as e:
                sickrage.app.log.error(str(e))
                error_data = {"error_msg": e, "request arguments": self.request.arguments}
                out_dict = _responds(RESULT_FATAL, error_data, "SiCKRAGE encountered an internal error! Please report to the Devs")
        else:
            access_msg = "IP:{} - ACCESS DENIED".format(self.request.remote_ip)
            sickrage.app.log.debug(access_msg)

            error_data = {"error_msg": access_msg, "request arguments": self.request.arguments}
            out_dict = _responds(RESULT_DENIED, error_data, access_msg)

        output_callback = output_callback_dict['default']
        if 'outputType' in out_dict:
            output_callback = output_callback_dict[out_dict['outputType']]

        await self.finish(output_callback(out_dict))

    async def route(self, function, **kwargs):
        kwargs = recursive_unicode(kwargs)
        for arg, value in kwargs.items():
            if len(value) == 1:
                kwargs[arg] = value[0]

        return await function(**kwargs)

    def _out_as_image(self, _dict):
        self.set_header('Content-Type', _dict['image'].type)
        return _dict['image'].content

    def _out_as_json(self, _dict):
        self.set_header("Content-Type", "application/json;charset=UTF-8")
        try:
            out = json_encode(_dict)
            callback = self.get_argument('callback', None) or self.get_argument('jsonp', None)
            if callback is not None:
                out = callback + '(' + out + ');'  # wrap with JSONP call if requested
        except Exception as e:  # if we fail to generate the output fake an error
            sickrage.app.log.debug(traceback.format_exc())
            out = '{"result": "%s", "message": "error while composing output: %s"}' % (result_type_map[RESULT_ERROR], e)
        return out

    @property
    def api_calls(self):
        """
        :return: api calls
        :rtype: Union[dict, object]
        """
        return dict((cls._cmd, cls) for cls in ApiCall.__subclasses__() if '_cmd' in cls.__dict__)

    async def call_dispatcher(self, *args, **kwargs):
        """ calls the appropriate CMD class
            looks for a cmd in args and kwargs
            or calls the TVDBShorthandWrapper when the first args element is a number
            or returns an error that there is no such cmd
        """
        sickrage.app.log.debug("all params: '" + str(kwargs) + "'")

        cmds = []
        if args:
            cmds, args = args[0], args[1:]
        cmds = kwargs.pop("cmd", cmds)

        outDict = {}
        if not len(cmds):
            outDict = await CMD_SiCKRAGE(self.application, self.request, *args, **kwargs).run()
        else:
            cmds = cmds.split('|')

        multiCmds = bool(len(cmds) > 1)

        for cmd in cmds:
            curArgs, curKwargs = self.filter_params(cmd, *args, **kwargs)
            cmdIndex = None
            if len(cmd.split("_")) > 1:  # was a index used for this cmd ?
                cmd, cmdIndex = cmd.split("_")  # this gives us the clear cmd and the index

            sickrage.app.log.debug(cmd + ": current params " + str(curKwargs))
            if not (multiCmds and cmd in ('show.getbanner', 'show.getfanart', 'show.getnetworklogo',
                                          'show.getposter')):  # skip these cmd while chaining
                try:
                    # backport old sb calls
                    cmd = (cmd, 'sr' + cmd[2:])[cmd[:2] == 'sb']

                    if cmd in self.api_calls:
                        # call function and get response back
                        curOutDict = await self.api_calls[cmd](self.application, self.request, *curArgs, **curKwargs).run()
                    elif _is_int(cmd):
                        curOutDict = await TVDBShorthandWrapper(cmd, self.application, self.request, *curArgs, **curKwargs).run()
                    else:
                        curOutDict = _responds(RESULT_ERROR, "No such cmd: '" + cmd + "'")
                except InternalApiError as e:  # Api errors that we raised, they are harmless
                    curOutDict = _responds(RESULT_ERROR, msg=str(e))
            else:  # if someone chained one of the forbiden cmds they will get an error for this one cmd
                curOutDict = _responds(RESULT_ERROR, msg="The cmd '" + cmd + "' is not supported while chaining")

            if multiCmds:
                # note: if multiple same cmds are issued but one has not an index defined it will override all others
                # or the other way around, this depends on the order of the cmds
                # this is not a bug
                if cmdIndex:  # do we need a index dict for this cmd ?
                    if cmd not in outDict:
                        outDict[cmd] = {}
                    outDict[cmd][cmdIndex] = curOutDict
                else:
                    outDict[cmd] = curOutDict
            else:
                outDict = curOutDict

        if multiCmds:
            outDict = _responds(RESULT_SUCCESS, outDict)

        return outDict

    def filter_params(self, cmd, *args, **kwargs):
        """ return only params kwargs that are for cmd
            and rename them to a clean version (remove "<cmd>_")
            args are shared across all cmds

            all args and kwarks are lowerd

            cmd are separated by "|" e.g. &cmd=shows|future
            kwargs are namespaced with "." e.g. show.indexer_id=101501
            if a karg has no namespace asing it anyways (global)

            full e.g.
            /api?apikey=1234&cmd=show.seasonlist_asd|show.seasonlist_2&show.seasonlist_asd.indexer_id=101501&show.seasonlist_2.indexer_id=79488&sort=asc

            two calls of show.seasonlist
            one has the index "asd" the other one "2"
            the "indexerid" kwargs / params have the indexed cmd as a namspace
            and the kwarg / param "sort" is a used as a global
        """
        curArgs = []
        for arg in args[1:] or []:
            try:
                curArgs += [arg.lower()]
            except:
                continue

        curKwargs = {}
        for kwarg in kwargs or []:
            try:
                if kwarg.find(cmd + ".") == 0:
                    cleanKey = kwarg.rpartition(".")[2]
                    curKwargs[cleanKey] = kwargs[kwarg].lower()
                elif not "." in kwarg:
                    curKwargs[kwarg] = kwargs[kwarg]
            except:
                continue

        return curArgs, curKwargs


class ApiCall(ApiHandler):
    _help = {"desc": "This command is not documented. Please report this to the developers."}

    def __init__(self, application, request, *args, **kwargs):
        super(ApiCall, self).__init__(application, request)
        self.indexer = 1
        self._missing = []
        self._requiredParams = {}
        self._optionalParams = {}
        self.check_params(*args, **kwargs)

    async def run(self):
        # override with real output function in subclass
        return {}

    async def return_help(self):
        for paramDict, paramType in [(self._requiredParams, "requiredParameters"),
                                     (self._optionalParams, "optionalParameters")]:

            if paramType in self._help:
                for paramName in paramDict:
                    if paramName not in self._help[paramType]:
                        self._help[paramType][paramName] = {}
                    if paramDict[paramName]["allowedValues"]:
                        self._help[paramType][paramName]["allowedValues"] = paramDict[paramName]["allowedValues"]
                    else:
                        self._help[paramType][paramName]["allowedValues"] = "see desc"

                    self._help[paramType][paramName]["defaultValue"] = paramDict[paramName]["defaultValue"]
                    self._help[paramType][paramName]["type"] = paramDict[paramName]["type"]

            elif paramDict:
                for paramName in paramDict:
                    self._help[paramType] = {}
                    self._help[paramType][paramName] = paramDict[paramName]
            else:
                self._help[paramType] = {}

        msg = "No description available"
        if "desc" in self._help:
            msg = self._help["desc"]

        return await _responds(RESULT_SUCCESS, self._help, msg)

    async def return_missing(self):
        if len(self._missing) == 1:
            msg = "The required parameter: '" + self._missing[0] + "' was not set"
        else:
            msg = "The required parameters: '" + "','".join(self._missing) + "' where not set"
        return await _responds(RESULT_ERROR, msg=msg)

    def check_params(self, key=None, default=None, required=None, arg_type=None, allowed_values=None, *args, **kwargs):

        """ function to check passed params for the shorthand wrapper
            and to detect missing/required params
        """

        # auto-select indexer
        if key in indexer_ids:
            if "tvdbid" in kwargs:
                key = "tvdbid"

            self.indexer = indexer_ids.index(key)

        if key:
            missing = True
            org_default = default

            if arg_type == "bool":
                allowed_values = [0, 1]

            if args:
                default = args[0]
                missing = False
                args = args[1:]
            if kwargs.get(key):
                default = kwargs.get(key)
                missing = False

            key_value = {
                "allowedValues": allowed_values,
                "defaultValue": org_default,
                "type": arg_type
            }

            if required:
                self._requiredParams[key] = key_value
                if missing and key not in self._missing:
                    self._missing.append(key)
            else:
                self._optionalParams[key] = key_value

            if default:
                default = self._check_param_type(default, key, arg_type)
                self._check_param_value(default, key, allowed_values)

        if self._missing:
            setattr(self, "run", self.return_missing)

        if 'help' in kwargs:
            setattr(self, "run", self.return_help)

        return default, args

    @staticmethod
    def _check_param_type(value, name, arg_type):
        """ checks if value can be converted / parsed to arg_type
            will raise an error on failure
            or will convert it to arg_type and return new converted value
            can check for:
            - int: will be converted into int
            - bool: will be converted to False / True
            - list: will always return a list
            - string: will do nothing for now
            - ignore: will ignore it, just like "string"
        """
        error = False
        if arg_type == "int":
            if _is_int(value):
                value = int(value)
            else:
                error = True
        elif arg_type == "bool":
            if value in ("0", "1"):
                value = bool(int(value))
            elif value in ("true", "True", "TRUE"):
                value = True
            elif value in ("false", "False", "FALSE"):
                value = False
            elif value not in (True, False):
                error = True
        elif arg_type == "list":
            value = value.split("|")
        elif arg_type == "string":
            pass
        elif arg_type == "ignore":
            pass
        else:
            sickrage.app.log.error('Invalid param type: "{}" can not be checked. Ignoring it.'.format(str(arg_type)))

        if error:
            raise InternalApiError(
                'param "{}" with given value "{}" could not be parsed into "{}"'.format(str(name), str(value),
                                                                                        str(arg_type)))

        return value

    @staticmethod
    def _check_param_value(value, name, allowed_values):
        """ will check if value (or all values in it ) are in allowed values
            will raise an exception if value is "out of range"
            if bool(allowed_value) is False a check is not performed and all values are excepted
        """
        if allowed_values:
            error = False
            if isinstance(value, list):
                for item in value:
                    if item not in allowed_values:
                        error = True
            else:
                if value not in allowed_values:
                    error = True

            if error:
                # this is kinda a InternalApiError but raising an error is the only way of quitting here
                raise InternalApiError("param: '" + str(name) + "' with given value: '" + str(
                    value) + "' is out of allowed range '" + str(allowed_values) + "'")


class TVDBShorthandWrapper(ApiCall):
    _help = {"desc": "This is an internal function wrapper. Call the help command directly for more information."}

    def __init__(self, sid, application, request, *args, **kwargs):
        super(TVDBShorthandWrapper, self).__init__(application, request, *args, **kwargs)

        self.origArgs = args
        self.kwargs = kwargs
        self.sid = sid

        self.s, args = self.check_params("s", None, False, "ignore", [], *args, **kwargs)
        self.e, args = self.check_params("e", None, False, "ignore", [], *args, **kwargs)
        self.args = args

    async def run(self):
        """ internal function wrapper """
        args = (self.sid,) + self.origArgs
        if self.e:
            return await CMD_Episode(self.application, self.request, *args, **self.kwargs).run()
        elif self.s:
            return await CMD_ShowSeasons(self.application, self.request, *args, **self.kwargs).run()
        else:
            return await CMD_Show(self.application, self.request, *args, **self.kwargs).run()


# ###############################
#       helper functions        #
# ###############################

def _is_int(data):
    try:
        int(data)
    except (TypeError, ValueError, OverflowError):
        return False
    else:
        return True


async def _responds(result_type, data=None, msg=""):
    """
    result is a string of given "type" (success/failure/timeout/error)
    message is a human readable string, can be empty
    data is either a dict or a array, can be a empty dict or empty array
    """

    return {"result": result_type_map[result_type], "message": msg, "data": data or {}}


def _get_status_strings(s):
    return statusStrings[s]


def _map_quality(showObj):
    anyQualities = []
    bestQualities = []

    iqualityID, aqualityID = Quality.split_quality(int(showObj))
    for quality in iqualityID:
        anyQualities.append(_get_quality_map()[quality])
    for quality in aqualityID:
        bestQualities.append(_get_quality_map()[quality])
    return anyQualities, bestQualities


def _get_quality_map():
    return {
        Quality.SDTV: 'sdtv',
        'sdtv': Quality.SDTV,

        Quality.SDDVD: 'sddvd',
        'sddvd': Quality.SDDVD,

        Quality.HDTV: 'hdtv',
        'hdtv': Quality.HDTV,

        Quality.RAWHDTV: 'rawhdtv',
        'rawhdtv': Quality.RAWHDTV,

        Quality.FULLHDTV: 'fullhdtv',
        'fullhdtv': Quality.FULLHDTV,

        Quality.HDWEBDL: 'hdwebdl',
        'hdwebdl': Quality.HDWEBDL,

        Quality.FULLHDWEBDL: 'fullhdwebdl',
        'fullhdwebdl': Quality.FULLHDWEBDL,

        Quality.HDBLURAY: 'hdbluray',
        'hdbluray': Quality.HDBLURAY,

        Quality.FULLHDBLURAY: 'fullhdbluray',
        'fullhdbluray': Quality.FULLHDBLURAY,

        Quality.UHD_4K_TV: 'uhd4ktv',
        'udh4ktv': Quality.UHD_4K_TV,

        Quality.UHD_4K_BLURAY: '4kbluray',
        'uhd4kbluray': Quality.UHD_4K_BLURAY,

        Quality.UHD_4K_WEBDL: '4kwebdl',
        'udh4kwebdl': Quality.UHD_4K_WEBDL,

        Quality.UHD_8K_TV: 'uhd8ktv',
        'udh8ktv': Quality.UHD_8K_TV,

        Quality.UHD_8K_BLURAY: 'uhd8kbluray',
        'uhd8kbluray': Quality.UHD_8K_BLURAY,

        Quality.UHD_8K_WEBDL: 'udh8kwebdl',
        "udh8kwebdl": Quality.UHD_8K_WEBDL,

        Quality.UNKNOWN: 'unknown',
        'unknown': Quality.UNKNOWN
    }


def _get_root_dirs():
    if sickrage.app.config.root_dirs == "":
        return {}

    rootDir = {}
    root_dirs = sickrage.app.config.root_dirs.split('|')
    default_index = int(sickrage.app.config.root_dirs.split('|')[0])

    rootDir["default_index"] = int(sickrage.app.config.root_dirs.split('|')[0])
    # remove default_index value from list (this fixes the offset)
    root_dirs.pop(0)

    if len(root_dirs) < default_index:
        return {}

    # clean up the list - replace %xx escapes by their single-character equivalent
    root_dirs = [unquote_plus(x) for x in root_dirs]

    default_dir = root_dirs[default_index]

    dir_list = []
    for root_dir in root_dirs:
        valid = 1
        try:
            os.listdir(root_dir)
        except Exception:
            valid = 0
        default = 0
        if root_dir is default_dir:
            default = 1

        curDir = {'valid': valid, 'location': root_dir, 'default': default}
        dir_list.append(curDir)

    return dir_list


class InternalApiError(Exception):
    """
    Generic API error
    """


class IntParseError(Exception):
    """
    A value could not be parsed into an int, but should be parsable to an int
    """


# -------------------------------------------------------------------------------------#


class CMD_Help(ApiCall):
    _cmd = "help"
    _help = {
        "desc": "Get help about a given command",
        "optionalParameters": {
            "subject": {"desc": "The name of the command to get the help of"},
        }
    }

    def __init__(self, application, request, *args, **kwargs):
        super(CMD_Help, self).__init__(application, request, *args, **kwargs)
        self.subject, args = self.check_params("subject", "help", False, "string", self.api_calls.keys(), *args,
                                               **kwargs)

    async def run(self):
        """ Get help about a given command """
        if self.subject in self.api_calls:
            api_func = self.api_calls.get(self.subject)
            out = api_func(self.application, self.request, **{"help": 1}).run()
        else:
            out = _responds(RESULT_FAILURE, msg="No such cmd")
        return out


class CMD_Backup(ApiCall):
    _cmd = "backup"
    _help = {
        "desc": "Backup application data files",
        "requiredParameters": {
            "backup_dir": {"desc": "Directory to store backup files"},
        }
    }

    def __init__(self, application, request, *args, **kwargs):
        super(CMD_Backup, self).__init__(application, request, *args, **kwargs)
        self.backup_dir, args = self.check_params("backup_dir", sickrage.app.data_dir, True, "string", [], *args,
                                                  **kwargs)

    async def run(self):
        """ Performs application backup """
        if backup_app_data(self.backup_dir):
            response = _responds(RESULT_SUCCESS, msg='Backup successful')
        else:
            response = _responds(RESULT_FAILURE, msg='Backup failed')

        return response


class CMD_ComingEpisodes(ApiCall):
    _cmd = "future"
    _help = {
        "desc": "Get the coming episodes",
        "optionalParameters": {
            "sort": {"desc": "Change the sort order"},
            "type": {"desc": "One or more categories of coming episodes, separated by |"},
            "paused": {
                "desc": "0 to exclude paused shows, 1 to include them, or omitted to use SiCKRAGE default value"
            },
        }
    }

    def __init__(self, application, request, *args, **kwargs):
        super(CMD_ComingEpisodes, self).__init__(application, request, *args, **kwargs)
        self.sort, args = self.check_params("sort", "date", False, "string", ComingEpisodes.sorts.keys(), *args,
                                            **kwargs)
        self.type, args = self.check_params("type", '|'.join(ComingEpisodes.categories), False, "list",
                                            ComingEpisodes.categories, *args, **kwargs)
        self.paused, args = self.check_params("paused", bool(sickrage.app.config.coming_eps_display_paused), False,
                                              "bool", [],
                                              *args, **kwargs)

    async def run(self):
        """ Get the coming episodes """
        grouped_coming_episodes = ComingEpisodes.get_coming_episodes(self.type, self.sort, True, self.paused)
        data = dict([(section, []) for section in grouped_coming_episodes.keys()])

        for section, coming_episodes in grouped_coming_episodes.items():
            for coming_episode in coming_episodes:
                data[section].append({
                    'airdate': coming_episode['airdate'],
                    'airs': coming_episode['airs'],
                    'ep_name': coming_episode['name'],
                    'ep_plot': coming_episode['description'],
                    'episode': coming_episode['episode'],
                    'indexer_id': coming_episode['indexer_id'],
                    'network': coming_episode['network'],
                    'paused': coming_episode['paused'],
                    'quality': coming_episode['quality'],
                    'season': coming_episode['season'],
                    'show_name': coming_episode['show_name'],
                    'show_status': coming_episode['status'],
                    'tvdbid': coming_episode['tvdbid'],
                    'weekday': coming_episode['weekday']
                })

        return await _responds(RESULT_SUCCESS, data)


class CMD_Episode(ApiCall):
    _cmd = "episode"
    _help = {
        "desc": "Get detailed information about an episode",
        "requiredParameters": {
            "indexerid": {"desc": "Unique ID of a show"},
            "season": {"desc": "The season number"},
            "episode": {"desc": "The episode number"},
        },
        "optionalParameters": {
            "tvdbid": {"desc": "thetvdb.com unique ID of a show"},
            "full_path": {
                "desc": "Return the full absolute show location (if valid, and True), or the relative show location"
            },
        }
    }

    def __init__(self, application, request, *args, **kwargs):
        super(CMD_Episode, self).__init__(application, request, *args, **kwargs)
        self.indexerid, args = self.check_params("indexerid", None, True, "int", [], *args, **kwargs)
        self.s, args = self.check_params("season", None, True, "int", [], *args, **kwargs)
        self.e, args = self.check_params("episode", None, True, "int", [], *args, **kwargs)
        self.fullPath, args = self.check_params("full_path", False, False, "bool", [], *args, **kwargs)

    async def run(self):
        """ Get detailed information about an episode """
        session = sickrage.app.main_db.session()

        show_obj = find_show(int(self.indexerid))
        if not show_obj:
            return await _responds(RESULT_FAILURE, msg="Show not found")

        try:
            episode = session.query(MainDB.TVEpisode).filter_by(showid=self.indexerid, season=self.s, episode=self.e).one()

            show_path = show_obj.location

            # handle path options
            # absolute vs relative vs broken
            if bool(self.fullPath) is True and os.path.isdir(show_path):
                pass
            elif bool(self.fullPath) is False and os.path.isdir(show_path):
                # using the length because lstrip removes to much
                show_path_length = len(show_path) + 1  # the / or \ yeah not that nice i know
                episode.location = episode.location[show_path_length:]
            elif not os.path.isdir(show_path):  # show dir is broken ... episode path will be empty
                episode.location = ""

            # convert stuff to human form
            if episode.airdate > datetime.date.min:  # 1900
                episode.airdate = srdatetime.SRDateTime(srdatetime.SRDateTime(
                    sickrage.app.tz_updater.parse_date_time(episode.airdate, show_obj.airs, show_obj.network),
                    convert=True).dt).srfdate(d_preset=dateFormat)
            else:
                episode.airdate = 'Never'

            status, quality = Quality.split_composite_status(int(episode.status))
            episode.status = _get_status_strings(status)
            episode.quality = get_quality_string(quality)
            episode.file_size_human = pretty_file_size(episode.file_size)

            return await _responds(RESULT_SUCCESS, episode.as_dict())
        except orm.exc.NoResultFound:
            raise InternalApiError("Episode not found")


class CMD_EpisodeSearch(ApiCall):
    _cmd = "episode.search"
    _help = {
        "desc": "Search for an episode. The response might take some time.",
        "requiredParameters": {
            "indexerid": {"desc": "Unique ID of a show"},
            "season": {"desc": "The season number"},
            "episode": {"desc": "The episode number"},
        },
        "optionalParameters": {
            "tvdbid": {"desc": "thetvdb.com unique ID of a show"},
        }
    }

    def __init__(self, application, request, *args, **kwargs):
        super(CMD_EpisodeSearch, self).__init__(application, request, *args, **kwargs)
        self.indexerid, args = self.check_params("indexerid", None, True, "int", [], *args, **kwargs)
        self.s, args = self.check_params("season", None, True, "int", [], *args, **kwargs)
        self.e, args = self.check_params("episode", None, True, "int", [], *args, **kwargs)

    async def run(self):
        """ Search for an episode """
        showObj = find_show(int(self.indexerid))
        if not showObj:
            return await _responds(RESULT_FAILURE, msg="Show not found")

        # retrieve the episode object and fail if we can't get one
        try:
            epObj = showObj.get_episode(int(self.s), int(self.e))
        except EpisodeNotFoundException:
            return await _responds(RESULT_FAILURE, msg="Episode not found")

        # make a queue item for it and put it on the queue
        ep_queue_item = ManualSearchQueueItem(showObj, epObj.season, epObj.episode)
        sickrage.app.io_loop.add_callback(sickrage.app.search_queue.put, ep_queue_item)

        # wait until the queue item tells us whether it worked or not
        while not ep_queue_item.success:
            time.sleep(1)

        # return the correct json value
        if ep_queue_item.success:
            status, quality = Quality.split_composite_status(epObj.status)
            # TODO: split quality and status?
            return await _responds(RESULT_SUCCESS, {"quality": get_quality_string(quality)},
                                   "Snatched (" + get_quality_string(quality) + ")")

        return await _responds(RESULT_FAILURE, msg='Unable to find episode')


class CMD_EpisodeSetStatus(ApiCall):
    _cmd = "episode.setstatus"
    _help = {
        "desc": "Set the status of an episode or a season (when no episode is provided)",
        "requiredParameters": {
            "indexerid": {"desc": "Unique ID of a show"},
            "season": {"desc": "The season number"},
            "status": {"desc": "The status of the episode or season"}
        },
        "optionalParameters": {
            "episode": {"desc": "The episode number"},
            "force": {"desc": "True to replace existing downloaded episode or season, False otherwise"},
            "tvdbid": {"desc": "thetvdb.com unique ID of a show"},
        }
    }

    def __init__(self, application, request, *args, **kwargs):
        super(CMD_EpisodeSetStatus, self).__init__(application, request, *args, **kwargs)
        self.indexerid, args = self.check_params("indexerid", None, True, "int", [], *args, **kwargs)
        self.s, args = self.check_params("season", None, True, "int", [], *args, **kwargs)
        self.status, args = self.check_params("status", None, True, "string",
                                              ["wanted", "skipped", "ignored", "failed"], *args, **kwargs)
        self.e, args = self.check_params("episode", None, False, "int", [], *args, **kwargs)
        self.force, args = self.check_params("force", False, False, "bool", [], *args, **kwargs)

    async def run(self):
        """ Set the status of an episode or a season (when no episode is provided) """
        show_obj = find_show(int(self.indexerid))
        if not show_obj:
            return await _responds(RESULT_FAILURE, msg="Show not found")

        # convert the string status to a int
        for status in statusStrings.status_strings:
            if str(statusStrings[status]).lower() == str(self.status).lower():
                self.status = status
                break
        else:  # if we dont break out of the for loop we got here.
            # the allowed values has at least one item that could not be matched against the internal status strings
            raise InternalApiError("The status string could not be matched to a status. Report to Devs!")