From 5d33ca7c6f0edcb848a2c8b0bca16400ec92ba3c Mon Sep 17 00:00:00 2001 From: Rudi Grinberg Date: Mon, 13 Aug 2012 15:24:45 -0400 Subject: [PATCH] cc-4105: a whole bunch of docstrings were added --- .../media-monitor2/media/monitor/airtime.py | 5 ++--- .../media-monitor2/media/monitor/events.py | 9 +++++++-- .../media-monitor2/media/monitor/handler.py | 8 ++++++++ .../media-monitor2/media/monitor/listeners.py | 3 ++- .../media-monitor2/media/monitor/log.py | 6 ++++++ .../media-monitor2/media/monitor/metadata.py | 18 +++++++++++++++++- .../media-monitor2/media/monitor/syncdb.py | 9 +++++++++ .../media-monitor2/media/monitor/toucher.py | 6 ++++++ 8 files changed, 57 insertions(+), 7 deletions(-) diff --git a/python_apps/media-monitor2/media/monitor/airtime.py b/python_apps/media-monitor2/media/monitor/airtime.py index d3f629402..9381bfdc9 100644 --- a/python_apps/media-monitor2/media/monitor/airtime.py +++ b/python_apps/media-monitor2/media/monitor/airtime.py @@ -168,14 +168,13 @@ class AirtimeMessageReceiver(Loggable): def change_storage(self, msg): new_storage_directory = msg['directory'] self.manager.change_storage_root(new_storage_directory) - for to_bootstrap in [ self.manager.get_recorded_path(), self.manager.get_imported_path() ]: self.__request_now_bootstrap( directory=to_bootstrap ) def file_delete(self, msg): - # deletes should be requested only from imported folder but we - # don't verify that. + # Deletes should be requested only from imported folder but we + # don't verify that. Security risk perhaps? self.logger.info("Attempting to delete(maybe) '%s'" % msg['filepath']) if msg['delete']: if os.path.exists(msg['filepath']): diff --git a/python_apps/media-monitor2/media/monitor/events.py b/python_apps/media-monitor2/media/monitor/events.py index d6d320d77..84809b19f 100644 --- a/python_apps/media-monitor2/media/monitor/events.py +++ b/python_apps/media-monitor2/media/monitor/events.py @@ -33,7 +33,7 @@ class EventRegistry(object): return event def __init__(self,*args,**kwargs): raise Exception("You can instantiate this class. Must only use class \ - methods") + methods") class HasMetaData(object): """ @@ -70,7 +70,12 @@ class BaseEvent(Loggable): return "Event(%s). Path(%s)" % ( self.path, self.__class__.__name__) def is_dir_event(self): return self._raw_event.dir - def add_safe_pack_hook(self,k): self._pack_hook = k + def add_safe_pack_hook(self,k): + """ + adds a callable object (function) that will be called after the event + has been "safe_packed" + """ + self._pack_hook = k # As opposed to unsafe_pack... def safe_pack(self): diff --git a/python_apps/media-monitor2/media/monitor/handler.py b/python_apps/media-monitor2/media/monitor/handler.py index 2dc4c0a47..dd1d3843a 100644 --- a/python_apps/media-monitor2/media/monitor/handler.py +++ b/python_apps/media-monitor2/media/monitor/handler.py @@ -15,6 +15,10 @@ class Handles(object): # cause a memory leak class ReportHandler(Handles): + """ + A handler that can also report problem files when things go wrong + through the report_problem_file routine + """ __metaclass__ = abc.ABCMeta def __init__(self, signal, weak=False): self.signal = signal @@ -28,6 +32,10 @@ class ReportHandler(Handles): exception=exception) class ProblemFileHandler(Handles, Loggable): + """ + Responsible for answering to events passed through the 'badfile' + signal. Moves the problem file passed to the designated directory. + """ def __init__(self, channel, **kwargs): self.channel = channel self.signal = self.channel.signal diff --git a/python_apps/media-monitor2/media/monitor/listeners.py b/python_apps/media-monitor2/media/monitor/listeners.py index fd490afba..67d06faa6 100644 --- a/python_apps/media-monitor2/media/monitor/listeners.py +++ b/python_apps/media-monitor2/media/monitor/listeners.py @@ -36,7 +36,8 @@ from media.monitor.log import Loggable, get_logger # OrganizeListener('watch_signal') <= wrong # OrganizeListener(signal='watch_signal') <= right -# This could easily be a module +# TODO : remove this FileMediator stuff it's not used anywhere and it's too +# complicated class FileMediator(object): ignored_set = set([]) # for paths only # TODO : unify ignored and skipped. diff --git a/python_apps/media-monitor2/media/monitor/log.py b/python_apps/media-monitor2/media/monitor/log.py index ec1debab0..62413b954 100644 --- a/python_apps/media-monitor2/media/monitor/log.py +++ b/python_apps/media-monitor2/media/monitor/log.py @@ -15,9 +15,15 @@ class Loggable(object): def logger(self): return logging.getLogger(appname) def unexpected_exception(self,e): + """ + Default message for 'unexpected' exceptions + """ self.fatal_exception("'Unexpected' exception has occured:", e) def fatal_exception(self, message, e): + """ + Prints an exception 'e' with 'message'. Also outputs the traceback. + """ self.logger.error( message ) self.logger.error( str(e) ) self.logger.error( traceback.format_exc() ) diff --git a/python_apps/media-monitor2/media/monitor/metadata.py b/python_apps/media-monitor2/media/monitor/metadata.py index 9433443d4..7a4bc697b 100644 --- a/python_apps/media-monitor2/media/monitor/metadata.py +++ b/python_apps/media-monitor2/media/monitor/metadata.py @@ -77,7 +77,9 @@ truncate_table = { } def format_length(mutagen_length): - """Convert mutagen length to airtime length""" + """ + Convert mutagen length to airtime length + """ t = float(mutagen_length) h = int(math.floor(t / 3600)) t = t % 3600 @@ -105,6 +107,9 @@ class Metadata(Loggable): @staticmethod def write_unsafe(path,md): + """ + Writes 'md' metadata into 'path' through mutagen + """ if not os.path.exists(path): raise BadSongFile(path) song_file = mutagen.File(path, easy=True) @@ -162,10 +167,21 @@ class Metadata(Loggable): self.__metadata['MDATA_KEY_MD5'] = mmp.file_md5(fpath,max_length=100) def is_recorded(self): + """ + returns true if the file has been created by airtime through recording + """ return mmp.is_airtime_recorded( self.__metadata ) def extract(self): + """ + returns a copy of the metadata that was loaded when object was + constructed + """ return copy.deepcopy(self.__metadata) def utf8(self): + """ + Returns a unicode aware representation of the data that is compatible + with what is spent to airtime + """ return mmp.convert_dict_value_to_utf8(self.extract()) diff --git a/python_apps/media-monitor2/media/monitor/syncdb.py b/python_apps/media-monitor2/media/monitor/syncdb.py index 097f06bf7..8206daeed 100644 --- a/python_apps/media-monitor2/media/monitor/syncdb.py +++ b/python_apps/media-monitor2/media/monitor/syncdb.py @@ -42,9 +42,15 @@ class AirtimeDB(Loggable): dirs_setup[u'watched_dirs'] ]) def to_id(self, directory): + """ + directory path -> id + """ return self.dir_to_id[ directory ] def to_directory(self, dir_id): + """ + id -> directory path + """ return self.id_to_dir[ dir_id ] def storage_path(self): return self.base_storage @@ -70,6 +76,9 @@ class AirtimeDB(Loggable): return l def dir_id_get_files(self, dir_id): + """ + Get all files in a directory with id dir_id + """ base_dir = self.id_to_dir[ dir_id ] return set(( os.path.join(base_dir,p) for p in self.apc.list_all_db_files( dir_id ) )) diff --git a/python_apps/media-monitor2/media/monitor/toucher.py b/python_apps/media-monitor2/media/monitor/toucher.py index 307aaf7c6..4e0a365ff 100644 --- a/python_apps/media-monitor2/media/monitor/toucher.py +++ b/python_apps/media-monitor2/media/monitor/toucher.py @@ -5,6 +5,9 @@ from media.monitor.log import Loggable from media.monitor.exceptions import CouldNotCreateIndexFile class Toucher(Loggable): + """ + Class responsible for touching a file at a certain path when called + """ def __init__(self,path): self.path = path def __call__(self): @@ -61,6 +64,9 @@ class RepeatTimer(threading.Thread): class ToucherThread(Loggable): + """ + Creates a thread that touches a file 'path' every 'interval' seconds + """ def __init__(self, path, interval=5): if not os.path.exists(path): try: