fab31 avatar fab31 committed 20ff436

more docs

Comments (0)

Files changed (12)

zicbee_lib/commands/__init__.py

 from itertools import chain
 try:
     from itertools import izip_longest
-
     def unroll(i):
+        """ unrolls a list of iterators, following the longest chain
+        returns an interator """
         return chain(*izip_longest(*i))
 except ImportError:
     # python < 2.6
+
     def unroll(i):
         l = list(i)
         while True:
 
     memory['path'] = path
 
+#: remembers the last search result
 remember_results = partial(memory.__setitem__, 'last_search')
+
+#: forget last search result
 forget_results = lambda uri: memory.__delitem__('last_search')
 
 #: this dict stores all the available commands

zicbee_lib/commands/command_misc.py

 from urllib import quote
 
 def complete_set(cur_var, params):
+    """ "set" command completion """
     if len(params) <= 2 and cur_var:
         # complete variables
         ret = (k for k, a in config if k.startswith(cur_var))
     return ret
 
 def hook_next(output):
+    """ "next" command hook """
     if 'pls_position' in memory:
         del memory['pls_position']
     return '/next'
 
 def hook_prev(output):
+    """ "prev" command hook """
     if 'pls_position' in memory:
         del memory['pls_position']
     return '/prev'
 
 def set_grep_pattern(output, *pat):
+    """ remembers the "grep" pattern """
     memory['grep'] = ' '.join(pat)
     return '/playlist'
 
 def apply_grep_pattern(it):
+    """ apply the "grep" pattern to the given iterator """
     # TODO: optimize
     pat = memory['grep'].lower()
     grep_idx = []
     memory['grepped'] = grep_idx
 
 def inject_playlist(output, symbol):
+    """ Play (inject in current playlist) the last "search" result """
     uri = memory.get('last_search')
     if not uri:
         print "Do a search first !"
     return v
 
 def set_shortcut(output, name=None, *args):
+    """ Sets some shortcut """
     if args:
         value = ' '.join(args)
     else:
         print "invalid option."
 
 def set_alias(output, name=None, value=None):
+    """ Sets some alias """
     try:
         if name is None:
             for varname, varval in aliases.iteritems():
         print "invalid option."
 
 def complete_alias(cur_var, params):
+    """ Completes the "alias" command """
     if len(params) <= 2 and cur_var:
         # complete variables
         ret = (k for k in aliases.iterkeys() if k.startswith(cur_var))
     return ret
 
 def set_variables(output, name=None, value=None, *args):
+    """ Set some variable """
     CST = ' ,='
     if name:
         if '=' in name:
         output(["invalid option."])
 
 def modify_delete(output, songid):
+    """ hook for the "delete" command """
     if songid == 'grep':
         return ('/delete?idx=%s'%(i-idx) for idx, i in enumerate(memory['grepped']))
     else:
         return '/delete?idx=%s'%songid
 
 def modify_move(output, songid, where=None):
-
+    """ Hook for the "move" command """
     if where is None:
         infos = get_infos()
         where = int(infos['pls_position'])+1
         return '/move?s=%s&d=%s'%(songid, where)
 
 def random_command(output, what='artist'):
+    """ executes the "random" command
+    Fills the playlist with a random artist (or album)
+    """
     dbh = config.db_host[0]
     arg = iter_webget('http://%s/db/random?what=%s'%(dbh, what)).next()
     return '/search?%s&host=%s'%(arg, dbh)
 
 def show_random_result(it):
+    """ displays the "random" command result """
     uri = modify_show(None)
     return ('-'.join(r.split('|')[1:4]) for r in iter_webget(uri))
 
 def modify_show(output, answers=10):
+    """ Hook for the "show" command """
     answers = get_index_or_slice(answers)
     if isinstance(answers, slice):
         memory['show_offset'] = answers.start
             return '/playlist?res=%s'%(answers)
 
 def tidy_show(it):
+    """ Improve the "show" output """
     offs = memory['show_offset']
     now = int(memory.get('pls_position', -1))
 

zicbee_lib/config.py

 
 __all__ = ['DB_DIR', 'defaults_dict', 'config', 'aliases', 'shortcuts']
 
+#: database directory
 DB_DIR = os.path.expanduser(os.getenv('ZICDB_PATH') or '~/.zicdb')
+
+#: valid extensions
 VALID_EXTENSIONS = ['mp3', 'ogg', 'mp4', 'aac', 'vqf', 'wmv', 'wma', 'm4a', 'asf', 'oga', 'flac', 'mpc', 'spx']
 
 def get_list_from_str(s):
+    """ Converts a comma-separated string to a list
+    :arg str s: the string with possible commas
+    :returns: a list of string, without commas
+    :rtype: str
+    """
     return [c.strip() for c in s.split(',')]
 
 class _Aliases(dict):
+    """ Alias handling internal class """
     def __init__(self, name):
         dict.__init__(self)
         self._db_dir = os.path.join(DB_DIR, '%s.txt'%name)
             shell.SHGetSpecialFolderLocation(0, (shellcon.CSIDL_DESKTOP, shellcon.CSIDL_COMMON_DESKTOPDIRECTORY)[0])
             )
 except ImportError: # sane environment ;)
+    #: default temporary folder
     TMP_DIR=r"/tmp"
 
 #: Dictionary with default configuration
 #: Config object, supports dots. and brackets[]
 config = _ConfigObj()
 
-# Dictionary-like of alias: expanded_value
+# Dictionary-like of host-alias: expanded_value
 aliases = _Aliases('aliases')
+# Dictionary-like of shortcut-command: full_command
 shortcuts = _Aliases('shortcuts')
 
 class _DefaultDict(dict):

zicbee_lib/core.py

+""" Zicbee-lib core module, includes some basic functions """
 __all__ = ['memory', 'iter_webget', 'get_infos']
 
 from time import time

zicbee_lib/debug.py

 """ Debug facilities """
-__all__ = ['DEBUG', 'debug_enabled', 'log', 'nop', 'set_trace']
+__all__ = ['DEBUG', 'debug_enabled', 'log', 'nop', 'set_trace', 'traced']
 import os
 import logging
 import traceback
     debug_enabled = os.environ['DEBUG'] != '0'
 
 def traced(fn):
-    """ Decorator that calls :ref:DEBUG in case of exception """
+    """ Decorator that calls :func:`DEBUG` in case of exception """
     def _get_decorator(decorated):
         def _decorator(*args, **kw):
             try:

zicbee_lib/downloader.py

+""" Download-worker related objects """
+
 import os
 import sys
 import time

zicbee_lib/formats.py

-__all__ = ['jdump', 'jload', 'clean_path', 'safe_path', 'duration_tidy', 'get_help_from_func', 'dump_data_as_text', 'get_index_or_slice']
+""" It's all about formats, (de)serialisation, filename cleaning, duration display, help-retrieval, etc... """
+__all__ = ['jdump', 'jload', 'clean_path', 'safe_path', 'duration_tidy', 'get_help_from_func', 'dump_data_as_text', 'get_index_or_slice',
+'compact_int', 'uncompact_int']
 
 import inspect
 import itertools

zicbee_lib/parser.py

 # -*- coding: utf-8 -*-
+""" Parser module for tag: <value>-like patterns, you probably just want to use :func:`string2python` """
 from __future__ import absolute_import, with_statement
 __all__ = ['tokens2python', 'parse_string', 'string2python', 'tokens2string']
 

zicbee_lib/remote_apis.py

+""" Remote-services (connected) APIs """
+
 import sys
 import urllib
 import xml.etree.ElementTree as ET

zicbee_lib/resources.py

+""" pkg_resources-like functions, may use pkg_resources directly """
+
 __all__ = ['get_players', 'resource_filename', 'set_proc_title']
 
 from pkg_resources import iter_entry_points, resource_filename

zicbee_lib/wasp/__init__.py

+""" Wasp module root, used to fire-up the wasp shell """
+
 def startup():
     """ Startup function, used to start wasp"""
     import sys

zicbee_lib/wasp/core.py

+""" main function used in Wasp """
 import os
 import readline
 from cmd import Cmd
         set_proc_title('wasp')
 
     def onecmd(self, line):
-        """ Executes one line """
+        """ Executes one line
+        :arg str line: the line to execute
+        """
         try:
             cmd, arg, line = self.parseline(line)
             if not line:
             return ret
 
     def get_names(self):
+        """ Returns the list of commands """
         return self.names
 
     def do_EOF(self, line):
+        """ Handles EOF user-event """
         try:
             readline.set_history_length(int(config['history_size']))
         except:
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.