fab31 avatar fab31 committed a1f974d

doc update

Comments (0)

Files changed (1)

zicbee/core/httpdb.py

 
 # DB part
 
-#: available formats in search form
+#: available formats in search form (html, txt, json, m3u, zip)
 available_formats = [
         ('html', 'WWW Browser'),
         ('txt', 'Text'),
         ('zip', 'ZIP archive'),
         ]
 
-#: Search form
 DbSimpleSearchForm = web.form.Form(
         web.form.Hidden('id'),
         web.form.Textbox('pattern', description="Play pattern"),
         pass
 
 def allow_admin_mode():
+    """ Tells if the admin operations are authorized
+    See ``alow_remote_admin`` in :obj:`~zicbee_lib.config.config`
+
+    :rtype: bool
+    """
     addr = web.ctx.env['REMOTE_ADDR']
 
     admins = config.allow_remote_admin
     zshell.songs.cleanup()
 
 class web_db_index:
+    """ Root of database web """
 
     _db_lock = RLock()
 
         """ Tags a song
         tag/<song id>/<tag>
 
-        Args:
-            - song (int): song
-            - tag (str): the tag you want to add to that song
-        Returns:
-            None
+        :arg int song: The song id
+        :arg str tag: The tag you want to add to that song
         """
 
         song_id = uncompact_int(song)
         try:
             tag = unicode(tag)
             with self._db_lock:
-                SEP=u','
+                sep = u','
                 _t = zshell.songs[song_id].tags
-                tag_set = set( _t.strip(SEP).split(SEP) ) if _t else set()
+                tag_set = set( _t.strip(sep).split(sep) ) if _t else set()
                 for single_tag in tag.split(','):
                     tag_set.add(single_tag.strip())
-                new_tag = ''.join((SEP,SEP.join(tag_set),SEP))
+                new_tag = ''.join((sep, sep.join(tag_set), sep))
                 zshell.songs[song_id].update(tags=new_tag)
         except Exception, e:
             web.debug('E!%s'%e)
         """ Rate a song
         rate/<song id>/<rating>
 
-        Args:
-            - song (int): song
-            - rating (int): the rate you want to give to that song
-        Returns:
-            None
+        :arg int song: song id
+        :arg int rating: the rate you want to give to that song
         """
         web.debug('rate: song=%s rating=%s'%(song,rating))
         try:
         """ Rate a list of songs
         multirate/[song id=rating]<,song id2=rating2><,song id3=rating3>...
 
-        Args:
-            - ratings_list: a list of tuples of the form::
-                song=rating,song2=rating2,...
-        Returns:
-            None
+        :arg ratings_list: list of (songid, ratings)
+        :type ratings_list: list of tuples
         """
         web.debug('rate: ratings_list=%s'%ratings_list)
         try:
     def REQ_version(self):
         """ Returns version of zicbee used on that instance
 
-        Returns:
-            None
+        :returns: version name "major.minor[-special]"
+        :rtype: str
         """
         yield VERSION
 
     def REQ_random(self):
         """ Returns a pattern with a random artist query
-        If "what" parameter is specified, allow to change
-        the random attribute, currently available:
-         - artist
-         - album
+
+         :arg str what: "artist" or "album" (defaults to "artist")
+         :returns: the corresponding query as in ``pattern=(artist|album):random_value``
+         :rtype: str
         """
         inp = web.input()
         what = inp.get('what', 'artist')
     def REQ_artists(self):
         """ List all the artists
 
-        Keywords:
-            fmt (str, optional): output format
+        :arg str fmt: (optionnal) output format, see :func:`~zicbee_lib.formats.dump_data_as_text`
 
-        Returns:
-            A list of artists in desired format
+        :Returns: A list of artists in desired format
         """
         inp = web.input()
         for d in dump_data_as_text(zshell.songs.artists, inp.get('fmt', 'txt')):
     def REQ_albums(self):
         """ List all the albums
 
-        Keywords:
-            fmt (str, optional): output format
+        :arg str fmt: (optionnal) output format, see :func:`~zicbee_lib.formats.dump_data_as_text`
 
-        Returns:
-            A list of albums in desired format
+        :Returns: A list of albums in desired format
         """
         inp = web.input()
         for d in dump_data_as_text(zshell.songs.albums, inp.get('fmt', 'txt')):
     def REQ_genres(self):
         """ List all the genres
 
-        Keywords:
-            fmt (str, optional): output format
+        :arg str fmt: (optionnal) output format, see :func:`~zicbee_lib.formats.dump_data_as_text`
 
-        Returns:
-            A list of genres in desired format
+        :returns: A list of genres in desired format
         """
         inp = web.input()
         for d in dump_data_as_text(zshell.songs.genres, inp.get('fmt', 'txt')):
             yield d
 
     def REQ_set(self):
+        """ if :func:`allow_admin_mode` allows it, sets a configuration value
+
+        :arg str k: key (config entry name) to set
+        :arg str v: value to set
+
+        :returns: key = new_value
+        :rtype: str
+        """
         if not allow_admin_mode():
             return "Not allowed"
         i = web.input()
     def REQ_kill(self):
         """ Kills the application
 
-        Returns:
-            "Aaaah!"
+        :Returns: "Aaaah!"
         """
         if allow_admin_mode():
             kill_server()
         """ Show infos about a song
         Either positional parameter or ``id`` keyword has to be given
 
-        Keywords:
-            fmt (str): output format
-            id (str): id of the song
-        Args:
-            song_id (int): index of the song
-        Returns:
-            all the metadatas in desired format
+        :arg str fmt: (optionnal) output format, see :func:`~zicbee_lib.formats.dump_data_as_text`
+        :arg str id: id of the song
+        :arg int song_id: id of the song
+
+        :Returns: all the metadatas in desired format
         """
 
 
         return dump_data_as_text(d, fmt)
 
     def REQ_get(self, *args):
+        """ Gets content of some entry, is the result of :obj:`DbSimpleSearchForm`
+        """
         af = DbSimpleSearchForm()
         if af.validates():
             af.fill()
         return
 
     def GET(self, name):
+        """ Main http dispatcher
+        if :obj:`DbSimpleSearchForm` is satisfied, will return search content
+
+        Redirects to ``REQ_<name>`` for subcommands
+
+        :arg str fmt: (optionnal) output format, see :func:`~zicbee_lib.formats.dump_data_as_text`
+            Added feature: supports m3u, html and zip too.
+
+        """
         hd = web.webapi.ctx.homedomain
 
         # try to replace "localhost" addresses with an external one
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.