Changeset 3616

Timestamp:

11/10/08 21:47:51 (3 months ago)

Author:

dmeyer

Message:

Add Sphinx documentation support. It is not done yet but gives an
idea how the doc should look like. Calling 'python setup.py doc'
will trigger html generation. The html files will be located in
doc/.build/html (that has to change in the future to something more
userfriendly).

Location:

trunk/beacon

Files:

• doc/Makefile (added)
• doc/attributes.rst (added)
• doc/conf.py (added)
• doc/index.rst (added)
• doc/install.rst (added)
• doc/item.rst (added)
• doc/media.rst (added)
• doc/query.rst (added)
• doc/server.rst (added)
• doc/vision.rst (added)
• setup.py (modified) (1 diff)
• src/__init__.py (modified) (5 diffs)
• src/file.py (modified) (1 diff)
• src/item.py (modified) (7 diffs)
• src/query.py (modified) (2 diffs)
• src/thumbnail.py (modified) (1 diff)

trunk/beacon/setup.py

@@ -82 +82 @@
        version     = '0.1.0',
        license     = 'LGPL',
-       epydoc      = [ 'doc/epydoc' ],
        summary     = "Media-oriented virtual filesystem",
        scripts     = [ 'bin/kaa-thumb', 'bin/beacon-daemon', 'bin/beacon-search',

trunk/beacon/src/__init__.py

@@ -121 +121 @@
     Lauch a beacon server and connect to it.
 
-    @param autoshutdown: if the server should shut down when no client is
-        connected anymore
-    @param verbose: verbose level for the server log
+    :param autoshutdown: shutdown server when no client is connected anymore
+    :param verbose: verbose level for the server log
     """
     beacon = os.path.dirname(__file__), '../../../../../bin/beacon-daemon'
@@ -142 +141 @@
     """
     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}
+    client is not connected and the server is not running for a
+    connect.  The function returns an InProgress object with a Query
+    object as result.
     """
     if not _client:
@@ -153 +151 @@
 def get(filename):
     """
-    Get object for the given filename. 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{File}
+    Get object for the given filename. This function will raise an
+    exception if the client is not connected and the server is not
+    running for a connect. The function returns an InProgress object
+    with a File object as result.
     """
     if not _client:
@@ -236 +233 @@
     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:
@@ -272 +242 @@
     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.
+    adds track\_ to the type name.
     """
     if not _client:

trunk/beacon/src/file.py

@@ -47 +47 @@
 class File(Item):
     """
-    A File-based Database Item.
-
-    see L{Item} for a list of available attributes.
-
-    @ivar url:         unique url of the item
-    @ivar filename:    complete filename
-    @ivar isdir:       True if it is a directory
-    @ivar isfile:      True if it is a regular file
-    @ivar scanned:     True if the item is scanned
-
-    @note: do not access attributes starting with _beacon outside kaa.beacon
+    A file-based database item
     """
 

trunk/beacon/src/item.py

@@ -45 +45 @@
 class Item(object):
     """
-    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
-    @ivar filename:    complete filename or file items
-    @ivar isdir:       True if it is a directory
-    @ivar isfile:      True if it is a regular file
-    @ivar scanned:     True if the item is scanned
-    @ivar thumbnail:   Thumbnail for the Item
-    @type thumbnail:   L{Thumbnail}
-    @note: do not access attributes starting with _beacon outside kaa.beacon
-    """
-
-    def __init__(self, _beacon_id, url, data, parent, media):
+    A generic database item
+    """
+
+    def __init__(self, beacon_id, url, data, parent, media):
         # url of the item
         self.url = url
         self.filename = ''
         # internal data
-        self._beacon_id = _beacon_id
+        self._beacon_id = beacon_id
         # FIXME: ugly, maybe use the ObjectRow stuff from kaa.db
         # with extra write support. Or copy on write.
@@ -142 +68 @@
         Access attributes of the item.
 
-        Besides the keys in the database an item has the following attributes
-        accessable with this function:
-
-         - parent: parent L{Item} or L{Item}
-         - media: L{Media} object the item is on
-         - thumbnail: L{Thumbnail} object for the item or parent
-         - image: image path for the item or parent
-         - read_only: True if the item is on a read only media
-
-        @returns: the value of a given attribute. If the attribute is not in the db,
-            return None.
-        @note: If the key starts with C{'tmp:'}, the data will be fetched from the
-            temp directory and not from the db.
-            attribute.
+        :param key: Attribute name
+        :param default: Default return when the attribute is not set
         """
         if key.startswith('tmp:'):
@@ -198 +112 @@
 
     def __getitem__(self, key):
+        """
+        Access attributes of the item
+        """
         return self.get(key)
 
@@ -203 +120 @@
         """
         Set the value of a given attribute. If the key starts with
-        C{'tmp:'}, the data will only be valid in this item and not
+        'tmp:', the data will only be valid in this item and not
         stored in the db. Loosing the item object will remove that
         attribute.
@@ -218 +135 @@
         """
         List item attributes
-
-        @returns: all attributes of the item.
         """
         return self._beacon_data.keys() + self._beacon_tmpdata.keys()
@@ -226 +141 @@
         """
         Check if the item has a specific attributes set
-
-        @returns: True if the key is stored in the item.
         """
         return key in self._beacon_data.keys() or \
@@ -264 +177 @@
         Return all subitems to his item.
 
-        @returns: InProgress object with list or kaa.beacon.Query
+        :returns: InProgress object with empty list or :class:`beacon.Query`
         """
         # This function is not used internally

trunk/beacon/src/query.py

@@ -71 +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
@@ -187 +179 @@
         Get the result.
 
-        @param filter: filter function set by L{register_filter} to use on the
+        :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}
+        :returns: (filtered) list of Items
         """
         if filter == None:

trunk/beacon/src/thumbnail.py

@@ -79 +79 @@
     """
     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