Changeset 3614

Timestamp:

11/10/08 12:12:01 (3 months ago)

Author:

dmeyer

Message:

doc update

Location:

trunk/beacon

Files:

• doc/epydoc (modified) (1 diff)
• src/__init__.py (modified) (8 diffs)
• src/client.py (modified) (1 diff)
• src/file.py (modified) (1 diff)
• src/item.py (modified) (1 diff)
• src/media.py (modified) (1 diff)
• src/query.py (modified) (6 diffs)
• src/server/server.py (modified) (1 diff)
• src/thumbnail.py (modified) (10 diffs)

trunk/beacon/doc/epydoc

@@ -37 +37 @@
 # Don't examine in any way the modules whose dotted name match this
 # regular expression pattern.
-exclude: server, query, media, db, file, item, _libthumb, client, utils
+exclude: server, query, media, db, file, item, _libthumb, client, utils, thumbnail
 
 # Don't perform introspection on the modules whose dotted name match this

trunk/beacon/src/__init__.py

@@ -32 +32 @@
 """
 kaa.beacon
-
+==========
+
+@group Internal Classes: Thumbnail, Item, File, Query, Media
 @group Server: connect, launch
 @group Query: query, get, monitor, register_filter, wrap
 @group Media Handling: list_media, delete_media
-@group Database Manipulation: add_item, register_file_type_attrs, register_track_type_attrs, get_db_info
+@group Database Manipulation: add_item, register_inverted_index,
+    register_file_type_attrs, register_track_type_attrs, get_db_info
+@group Thumbnailing: THUMBNAIL_NORMAL, THUMBNAIL_LARGE
+@group kaa.db Variables: ATTR_SIMPLE, ATTR_SEARCHABLE, ATTR_IGNORE_CASE, ATTR_INDEXED,
+    ATTR_INDEXED_IGNORE_CASE, ATTR_INVERTED_INDEX
 """
 
 __all__ = [ 'connect', 'launch', 'get', 'query', 'monitor', 'add_item', 'wrap',
-            'register_file_type_attrs', 'register_track_type_attrs', 'get_db_info',
-            'list_media', 'delete_media', 'register_filter', 'Item', 'Query', 'Media',
-            'File', 'VERSION', 'THUMBNAIL_NORMAL', 'THUMBNAIL_LARGE' ]
+            'register_file_type_attrs', 'register_track_type_attrs',
+            'register_inverted_index', 'get_db_info', 'list_media', 'delete_media',
+            'register_filter', 'Item', 'Query', 'Media', 'File', 'Thumbnail',
+            'VERSION', 'THUMBNAIL_NORMAL', 'THUMBNAIL_LARGE', 'QExpr', 'ATTR_SIMPLE',
+            'ATTR_SEARCHABLE', 'ATTR_IGNORE_CASE', 'ATTR_INDEXED',
+            'ATTR_INDEXED_IGNORE_CASE', 'ATTR_INVERTED_INDEX' ]
 
 # python imports
@@ -61 +70 @@
 from thumbnail import LARGE as THUMBNAIL_LARGE
 from thumbnail import Thumbnail
-from query import register_filter, wrap, Query
 from item import Item
 from file import File
@@ -109 +117 @@
     return _client
 
-
 def launch(autoshutdown=False, verbose='none'):
     """
@@ -132 +139 @@
     return connect()
 
+def query(**args):
+    """
+    Query the database. This function will raise an exception if the
+    client is not connected and the server is not running for a connect.
+
+    @returns: InProgress
+    @rtype: L{Query}
+    """
+    if not _client:
+        connect()
+    return _client.query(**args)
 
 def get(filename):
@@ -145 +163 @@
     return _client.get(filename)
 
-
-def query(**args):
-    """
-    Query the database. This function will raise an exception if the
-    client is not connected and the server is not running for a connect.
-
-    @returns: InProgress
-    @rtype: L{Query}
-    """
-    if not _client:
-        connect()
-    return _client.query(**args)
-
-
 def monitor(directory):
     """
@@ -169 +173 @@
         connect()
     return _client.monitor(directory)
-
-
-def add_item(url, type, parent, **kwargs):
-    """
-    Add an item to the database (not to be used for files).
-    """
-    if not _client:
-        connect()
-    return _client.add_item(url, type, parent, **kwargs)
-
-
-def register_file_type_attrs(name, **kwargs):
-    """
-    Register new attrs and types for files.
-    """
-    if not _client:
-        connect()
-    return _client.register_file_type_attrs(name, **kwargs)
-
-
-def register_track_type_attrs(name, **kwargs):
-    """
-    Register new attrs and types for files.
-    """
-    if not _client:
-        connect()
-    return _client.register_track_type_attrs(name, **kwargs)
-
-
-def get_db_info():
-    """
-    Gets statistics about the database.
-
-    @return: basic database information
-    """
-    if not _client:
-        connect()
-    return _client.get_db_info()
-
 
 def list_media():
@@ -222 +187 @@
     return _client._db.medialist
 
-
 def delete_media(id):
     """
@@ -234 +198 @@
         kaa.main.step()
     return _client.delete_media(id)
+
+def add_item(url, type, parent, **kwargs):
+    """
+    Add an item to the database. This function can be used to add an Item
+    as subitem to another. You can not add files that do not exist to a
+    directory, but it is possible to add an Item with a http url to a directory
+    or a meta item with http items as children.
+
+    @param url: url of the Item, can not be file:
+    @param type: item type
+    @param parent: parent item
+    @param kwargs: addition keyword/value arguments for the db
+    @returns: new created item
+    @rtype: L{Item}
+    """
+    if not _client:
+        connect()
+    return _client.add_item(url, type, parent, **kwargs)
+
+def register_inverted_index(name, min=None, max=None, split=None, ignore=None):
+    """
+    Registers a new inverted index with the database.  An inverted index
+    maps arbitrary terms to objects and allows you to query based on one
+    or more terms.  If the inverted index already exists with the given
+    parameters, no action is performed.  See kaa.db for details.
+    """
+    if not _client:
+        connect()
+    return _client.register_inverted_index(name, min, max, split, ignore)
+
+def register_file_type_attrs(type_name, indexes=[], **attrs):
+    """
+    Registers one or more object attributes and/or multi-column
+    indexes for the given type name.  This function modifies the
+    database as needed to accommodate new indexes and attributes,
+    either by creating the object's tables (in the case of a new
+    object type) or by altering the object's tables to add new columns
+    or indexes.
+
+    Previously registered attributes may be updated in limited ways
+    (e.g.  by adding an index to the attribute).  If the attributes
+    and indexes specified have not changed from previous invocations,
+    no changes will be made to the database. Therefore an application
+    should always call this function on startup if it needs attributes
+    not defined by beacon already.
+
+    @param type_name: is the name of the type the attributes and
+        indexes apply to (e.g. 'dir' or 'image').
+    @param indexes: a list of tuples, where each tuple contains 2 or
+        more strings, where each string references a registered
+        attribute.  This is used for creating a multi-column index on
+        these attributes, which is useful for speeding up queries
+        involving these attributes.
+    @param attrs: where each keyword value is a tuple of 2 to 4 items
+        in length and in the form (name, flags, ivtidx, split):
+         - name: The name of the attribute; cannot conflict with any of the
+             values in RESERVED_ATTRIBUTES.
+         - flags: A bitmask of ATTR_* flags.
+         - ivtidx: Name of the previously registered inverted index used for
+             this attribute, only if flags contains ATTR_INVERTED_INDEX.
+         - split: Function or regular expression used to split string-based
+             values for this attributes into separate terms for indexing.
+    @note: currently indexes and attributes can only be added, not
+        removed. That is, once an attribute or indexes is added, it
+        lives forever.
+    """
+    if not _client:
+        connect()
+    return _client.register_file_type_attrs(type_name, indexes, **attrs)
+
+def register_track_type_attrs(type_name, indexes=[], **attrs):
+    """
+    Register new attrs and types for tracks. See L{register_file_type_attrs}
+    for details. The only difference between this two functions is that this
+    adds C{track_} to the type name.
+    """
+    if not _client:
+        connect()
+    return _client.register_track_type_attrs(type_name, indexes, **attrs)
+
+def get_db_info():
+    """
+    Gets statistics about the database.
+
+    @return: basic database information
+    """
+    if not _client:
+        connect()
+    return _client.get_db_info()
+
+# import some more functions and classes we expose to the API
+# It is done at the end of this file to force a better order of the
+# functions for epydoc
+from query import register_filter, wrap, Query

trunk/beacon/src/client.py

@@ -171 +171 @@
 
 
-    def register_inverted_index(self, name, *args, **kwargs):
+    def register_inverted_index(self, name, min=None, max=None, split=None, ignore=None):
         """
         Register new inverted index.
         """
         if self.status != DISCONNECTED:
-            self.rpc('db.register_inverted_index', name, *args, **kwargs)
-
-
-    def register_file_type_attrs(self, name, **kwargs):
+            self.rpc('db.register_inverted_index', name, min, max, split, ignore)
+
+
+    def register_file_type_attrs(self, type_name, indexes=[], **attrs):
         """
         Register new attrs and types for files.
         """
         if self.status != DISCONNECTED:
-            self.rpc('db.register_file_type_attrs', name, **kwargs)
-
-
-    def register_track_type_attrs(self, name, **kwargs):
-        """
-        Register new attrs and types for files.
-        """
-        if self.status != DISCONNECTED:
-            self.rpc('db.register_track_type_attrs', name, **kwargs)
+            self.rpc('db.register_file_type_attrs', type_name, indexes, **attrs)
+
+
+    def register_track_type_attrs(self, type_name, indexes=[], **attrs):
+        """
+        Register new attrs and types for tracks.
+        """
+        if self.status != DISCONNECTED:
+            self.rpc('db.register_track_type_attrs', type_name, indexes, **attrs)
 
 

trunk/beacon/src/file.py

@@ -47 +47 @@
 class File(Item):
     """
-    A file based database item.
+    A File-based Database Item.
+
+    see L{Item} for a list of available attributes.
 
     @ivar url:         unique url of the item

trunk/beacon/src/item.py

@@ -45 +45 @@
 class Item(object):
     """
-    A database item.
+    A Database Item
+    ===============
+
+    The following attributes are available. If more are needed please call
+    L{register_file_type_attrs} or L{register_track_type_attrs}.
+
+    Directories (type = C{dir})
+     - C{name} (str, searchable, inverted_index: 'keywords')
+     - C{overlay} (bool, simple)
+     - C{media} (int, searchable, indexed)
+     - C{image} (int, simple)
+     - C{mtime} (int, simple)
+     - C{title} (unicode, simple)
+     - C{artist} (unicode, simple)
+     - C{album} (unicode, simple)
+     - C{length} (float, simple), length in seconds of all items in that directory
+
+    Items and Files (type = C{file} and all media types)
+     - C{name} (str, searchable, inverted_index: 'keywords')
+     - C{overlay} (bool, simple)
+     - C{media} (int, searchable, indexed)
+     - C{image} (int, simple)
+     - C{mtime} (int, simple)
+
+    Video Items (type = C{video})
+     - C{title} (unicode, searchable, ignore_case, inverted_index: 'keywords'),
+     - C{width} (int, simple)
+     - C{height} (int, simple)
+     - C{length} (float, simple)
+     - C{scheme} (str, simple)
+     - C{description} (unicode, simple)
+     - C{timestamp} (int, searchable)
+
+    Audio Items (type = C{audio})
+     - C{title} (unicode, searchable, ignore_case, inverted_index: 'keywords')
+     - C{artist} (unicode, searchable, indexed, ignore_case, inverted_index: 'keywords')
+     - C{album} (unicode, searchable, ignore_case, inverted_index: 'keywords')
+     - C{genre} (unicode, searchable, indexed, ignore_case)
+     - C{samplerate} (int, simple)
+     - C{length} (float, simple)
+     - C{bitrate} (int, simple)
+     - C{trackno} (int, simple)
+     - C{userdate} (unicode, simple)
+     - C{description} (unicode, simple)
+     - C{timestamp} (int, searchable)
+
+    Image Items (type = C{image})
+     - C{width} (int, searchable)
+     - C{height} (int, searchable)
+     - C{comment} (unicode, searchable, ignore_case, inverted_index: 'keywords')
+     - C{rotation} (int, simple)
+     - C{author} (unicode, simple)
+     - C{timestamp} (int, searchable)
+
+    DVD Track Items (type = C{dvd})
+     - C{length} (float, simple)
+     - C{audio} (list, simple)
+     - C{chapters} (int, simple)
+     - C{subtitles} (list, simple)
+
+    VCD Track Items (type = C{vcd})
+     - C{audio} (list, simple)
+
+    Audio CD Track Items (type = C{cdda})
+     - C{title} (unicode, searchable, inverted_index: 'keywords')
+     - C{artist} (unicode, searchable, indexed, inverted_index: 'keywords')
 
     @ivar url:         unique url of the item

trunk/beacon/src/media.py

@@ -49 +49 @@
     """
     Media object for a specific mount point.
+
+    The following attributes are available.
+
+     - C{name} (str, searchable | inverted_index: 'keywords')
+     - C{content} (str, simple)
+
+    @note: Objects are created by the hardware monitor subsystem, do not create
+        Media objects from outside beacon.
     """
     def __init__(self, id, controller):
         """
         Create a media object
-
-        @note: Objects are created by the hardware monitor subsystem, do not create
-            Media objects from outside beacon.
         """
         log.info('new media %s', id)

trunk/beacon/src/query.py

@@ -47 +47 @@
 
 def register_filter(name, function):
+    """
+    Register a filter for L{Query} or L{wrap} to process a list of items.
+
+    @param name: unique name for the filter
+    @param function: filter function
+    """
     _query_filter[name] = function
 
 
 def wrap(items, filter):
+    """
+    Wrap the given list of items with the given filter function
+
+    @param items: list of items
+    @param filter: name of the filter, see L{register_filter}
+    """
     if not filter in _query_filter:
         raise AttributeError('unknown filter')
@@ -59 +71 @@
     """
     Query object for the client. Created by Client.query()
+
+    This object feels like a list, you can iterate over the results,
+    access items based on position and get the length of the
+    results.
+
+    @group Internal API: __init__, __del__, __repr__, __inprogress__
+    @note: A Query is created by Client.query(), do not create Query objects
+        from outside beacon.
     """
     NEXT_ID = 1
 
     def __init__(self, client, **query):
-
-        # FIXME: add a complete signal on first scan
+        """
+        Create a Query object and start the query on the client
+        """
         # FIXME: progress and up-to-date seems not used
-        self.signals = {
-            'changed'   : kaa.Signal(),
-            'progress'  : kaa.Signal(),
-            'up-to-date': kaa.Signal(),
-        }
+        self.signals = kaa.Signals('changed', 'progress', 'up-to-date')
         self.id = Query.NEXT_ID
         Query.NEXT_ID += 1
-
         # public variables
         self.monitoring = False
@@ -103 +119 @@
         """
         Turn on/off query monitoring
+
+        @param status: True to turn on monitoring, False to turn it off.
         """
         if self.monitoring == status:
@@ -132 +150 @@
         """
         Iterate through the results.
+
+        @returns: Iterator
+        @rtype: L{Item} or L{File}
         """
         return self.result.__iter__()
 
 
-    def __getitem__(self, key):
-        """
-        Get a specific item in the results.
-        list.
-        """
-        return self.result[key]
+    def __getitem__(self, pos):
+        """
+        Get a specific item in the results list.
+
+        @returns: Item on that position in the list
+        @rtype: L{Item} or L{File}
+        @raises IndexError: result list is shorten than pos
+        """
+        return self.result[pos]
 
 
@@ -147 +171 @@
         """
         Get index of an item in the results. This function will raise an
-        exception if the item is not in the results or if the query object is
-        still invalid.
+        exception if the item is not in the results.
         """
         return self.result.index(item)
@@ -163 +186 @@
         """
         Get the result.
+
+        @param filter: filter function set by L{register_filter} to use on the
+            result. If a filter is used the result type may be different.
+        @returns: (filtered) query result
+        @rtype: list of L{Item} or L{File}
         """
         if filter == None:

trunk/beacon/src/server/server.py

@@ -237 +237 @@
 
     @kaa.rpc.expose('db.register_inverted_index')
-    def register_inverted_index(self, name, *args, **kwargs):
+    def register_inverted_index(self, name, min=None, max=None, split=None, ignore=None):
         """
         Register new inverted index. The basics are already in the db by the
         __init__ function of this class.
         """
-        return self._db.register_inverted_index(name, *args, **kwargs)
+        return self._db.register_inverted_index(name, min, max, split, ignore)
 
 
     @kaa.rpc.expose('db.register_file_type_attrs')
-    def register_file_type_attrs(self, name, **kwargs):
+    def register_file_type_attrs(self, type_name, indexes=[], **attrs):
         """
         Register new attrs and types for files. The basics are already
         in the db by the __init__ function of this class.
         """
-        return self._db.register_object_type_attrs(name, **kwargs)
+        return self._db.register_object_type_attrs(type_name, indexes, **attrs)
 
 
     @kaa.rpc.expose('db.register_track_type_attrs')
-    def register_track_type_attrs(self, name, **kwargs):
-        """
-        Register new attrs and types for files. The basics are already
+    def register_track_type_attrs(self, type_name, indexes=[], **attrs):
+        """
+        Register new attrs and types for tracks. The basics are already
         in the db by the __init__ function of this class.
         """
-        return self._db.register_object_type_attrs('track_%s' % name, **kwargs)
+        type_name = 'track_%s' % type_name
+        return self._db.register_object_type_attrs(type_name, indexes, **attrs)
 
 

trunk/beacon/src/thumbnail.py

@@ -7 +7 @@
 # -----------------------------------------------------------------------------
 # kaa.beacon - A virtual filesystem with metadata
-# Copyright (C) 2006 Dirk Meyer
+# Copyright (C) 2006-2008 Dirk Meyer
 #
 # First Edition: Dirk Meyer <dischi@freevo.org>
@@ -77 +77 @@
 
 class Thumbnail(object):
-
+    """
+    Thumbnail handling. This objects is a wrapper for full size image path names.
+
+    @note: A Thumbnail object is created by an L{Item}, do not create Thumbnail objects
+        from outside beacon.
+    """
     # priority for creating
     PRIORITY_HIGH   = 0
@@ -87 +92 @@
     NORMAL = 'normal'
 
-    next_id = 0
+    _next_id = 0
 
     def __init__(self, name, media, url=None):
+        """
+        Create Thumbnail handler
+
+        @param name: full, absolute path name of the image file
+        @param media: beacon Media object to determine the thumbnailing directory
+        @param url: url to store in the thumbnail
+        """
         if not name.startswith('/'):
             # FIXME: realpath should not be needed here because
@@ -105 +117 @@
         self._thumbnail = media.thumbnails + '/%s/' + md5.md5(self.url).hexdigest()
 
-
     def get(self, type='any', check_mtime=False):
+        """
+        Get the filename to the thumbnail.
+
+        @param type: THUMBNAIL_NORMAL, THUMBNAIL_LARGE or 'any'
+        @param check_mtime: Check the file modification time against the information
+            stored in the thumbnail. If the file has changed, the thumbnail will not be
+            returned.
+        @returns: full path to thumbnail file or None
+        """
         if check_mtime:
             image = self.get(type)
@@ -117 +137 @@
             # mtime check failed, return no image
             return None
-
         if type == 'any':
             image = self.get(LARGE, check_mtime)
@@ -131 +150 @@
         return None
 
-
     def set(self, image, type='both'):
+        """
+        Set the thumbnail
+
+        @param image: Image containing the thumbnail
+        @type image: kaa.Imlib2 image object
+        @param type: THUMBNAIL_NORMAL, THUMBNAIL_LARGE or 'both'
+        """
         if type == 'both':
             self.set(image, NORMAL)
-            self.set(image, LARGE)
-            return
-
+            return self.set(image, LARGE)
         dest = '%s/%s' % (self.destdir, type)
-
         i = self._thumbnail % type + '.png'
         png(self.name, i, SIZE[type], image._image)
         log.info('store %s', i)
 
-
     def exists(self, check_mtime=False):
+        """
+        Check if a thumbnail exists. This function checks normal and large sized
+        thumbnails as well as the fail directory for previous attempts to create
+        a thumbnail for this file.
+
+        @param check_mtime: check the file and thumbnail modification time if a
+            thumbnail is valid.
+        """
         return self.get(NORMAL, check_mtime) or self.get(LARGE, check_mtime) \
                or self.get('fail/beacon', check_mtime)
 
-
     def is_failed(self):
+        """
+        Check if thumbnailing failed before. Failed attempts are stored in the
+        fail/beacon subdirectory.
+        """
         return self.get('fail/beacon')
 
-
     def create(self, type=NORMAL, priority=None):
+        """
+        Create a thumbnail.
+
+        @param type: one of THUMBNAIL_NORMAL and THUMBNAIL_LARGE
+        @param priority: priority how important the thumbnail is. The thumbnail
+            process will handle the thumbnail generation based on this priority.
+            If you loose all references to this thumbnail object, the priority will
+            automatically set to the lowest value (2).
+
+            Maximum value is 0, default 1.
+        """
         if priority is None: