Changeset 3631

Show
Ignore:
Timestamp:
17/10/08 22:19:30 (3 months ago)
Author:
dmeyer
Message:

major doc update

Location:
trunk/beacon
Files:
3 added
3 removed
12 modified

Legend:

Unmodified
Added
Removed

  • trunk/beacon/doc/attributes.rst

    r3616 r3631  
     1.. _attributes: 
     2 
    13Database Attributes 
    24=================== 
    … …  
    57--------------------------- 
    68 
    7 The following attributes are available. If more are needed please call 
    8 `register_file_type_attrs` or `register_track_type_attrs`. 
     9The following attributes are available. An application can define 
     10application specific attributes. See :ref:`define-attributes` for 
     11details. 
    912 
    1013Directories (type = `dir`:) 
    … …  
    7477 
    7578Besides the keys in the database an item has the following attributes 
    76 accessable with this function: 
     79accessible with this function: 
    7780 
    78  - parent: parent or Item 
    79  - media: Media object the item is on 
    80  - thumbnail: Thumbnail object for the item or parent 
    81  - image: image path for the item or parent 
    82  - read_only: True if the item is on a read only media 
     81 - parent: parent or Item media: Media object the item is on 
     82 - thumbnail: Thumbnail object for the item or parent. See 
     83   :ref:`thumbnail` for details about thumbnailing works in beacon. 
     84 - image: image path for the item or parent read_only: True if the 
     85 - item is on a read only media 
    8386 
    8487If you access or store an attribute that starts with 'tmp:', the data 
    … …  
    8689for the same file in the database will not have that attribute and it 
    8790will be lost when the application shuts down. 
    88  
    89  
    90 Thumbnails 
    91 ---------- 
    92  
    93 .. autoclass:: beacon.Thumbnail 
    94  
    95  
    96 Adding Application specific Attributes 
    97 -------------------------------------- 
    98  
    99 Describe the basic usage how the db works here. 
    100  
    101 .. autofunction:: beacon.register_inverted_index 
    102 .. autofunction:: beacon.register_file_type_attrs 
    103 .. autofunction:: beacon.register_track_type_attrs 
    104  
    105  

  • trunk/beacon/doc/index.rst

    r3616 r3631  
    66====================================== 
    77 
     8Note: This documentation is far for being complete. If you need more 
     9information about a specific topic please send a mail to the Freevo 
     10devel mailing list. Patches to this doc are welcome. 
     11 
    812Contents: 
    913 
    1014.. toctree:: 
    11    :maxdepth: 2 
     15   :maxdepth: 1 
    1216 
    1317   vision 
    … …  
    1822   item 
    1923   media 
     24   thumbnail 
     25   manipulation 
     26   internals 
     27 
     28.. FIXME: missing: 
     29.. get_db_info 
    2030 
    2131Indices and tables 

  • trunk/beacon/doc/item.rst

    r3616 r3631  
    33 
    44.. module:: item 
    5 .. autofunction:: beacon.get 
    65 
    76Items are returned by beacon queries and represent one result 
    8 entry. You should not create an Item yourself. There are currently two 
    9 kinds of Items. The generic Item class and a File class inheriting 
    10 from Item. 
     7entry. You should not create an Item yourself. Beacon provides two 
     8query functions. The first one is `kaa.beacon.query` which returns a 
     9Query object and the second one is `kaa.beacon.get` to get the item 
     10for a specific filename. 
    1111 
    12 .. autoclass:: beacon.Item 
    13 .. autoclass:: beacon.File 
     12There are currently two kinds of Items. The generic Item class and a 
     13File class inheriting from Item. 
     14 
     15.. autofunction:: beacon.get 
    1416 
    1517Methods 
    1618------- 
     19 
     20An Item uses a dict-like interface to get and set values. If the key 
     21starts with `tmp:` the value is stored temporary in the Item and is 
     22not stored in the database. A second Item for the same database entry 
     23does not have this attribute and it is lost when the Item is 
     24destroyed. See :ref:`attributes` for a list of attributes in the 
     25database. 
    1726 
    1827.. automethod:: beacon.Item.get 
    … …  
    2130.. automethod:: beacon.Item.keys 
    2231.. automethod:: beacon.Item.__setitem__ 
     32 
     33An Item also provides an interface to access children like files in a 
     34directory, delete an Item from the database and initiate an Item to be 
     35scanned. 
     36 
    2337.. automethod:: beacon.Item.list 
    2438.. automethod:: beacon.File.list 
    … …  
    2943---------- 
    3044 
     45Besides the attributes in the database an Item also has some Python 
     46attributes. These attributes are always set no matter of the file 
     47behind it is already scanned or not. 
     48 
    3149.. attribute:: beacon.Item.url 
    3250 
    33    URL for the Item. This includes a prefix like file, dvd or http 
     51   URL for the Item. This includes a prefix like file\://, dvd\:// or 
     52   http\:// 
    3453 
    3554.. attribute:: beacon.Item.filename 
    3655 
    37    Full path of the file if the Item represents a file or directory 
     56   Full path of the file if the Item represents a file or 
     57   directory. For Item that are no File this attribute is an empty 
     58   string. 
    3859 
    3960.. autoattribute:: beacon.Item.isdir 
    … …  
    4263.. autoattribute:: beacon.Item.scanned 
    4364.. autoattribute:: beacon.Item.ancestors 
    44  
    45 Signals 
    46 ------- 
    47  
    48 Item has no signals to connect to 
    49  

  • trunk/beacon/doc/media.rst

    r3616 r3631  
    11Media Handling 
    22============== 
     3 
     4FIXME: Describe media handling here including media query and 
     5attributes. 
     6 
     7.. automethod:: beacon.Media.get 
     8.. automethod:: beacon.Media.__getitem__ 
     9.. automethod:: beacon.Media.__setitem__ 
     10.. automethod:: beacon.Media.eject 
     11.. autoattribute:: beacon.Media.isdir 
     12 
     13.. autofunction:: beacon.list_media 
     14.. autofunction:: beacon.delete_media 

  • trunk/beacon/doc/query.rst

    r3616 r3631  
    1 Database Query 
    2 ============== 
     1.. _query: 
     2 
     3Query 
     4===== 
    35 
    46.. module:: query 
    57 
    6 Describe here how searching works in general. 
     8FIXME: Describe here how searching works in general. 
    79 
    810.. autofunction:: beacon.query 
    9 .. autoclass:: beacon.Query 
    1011 
    1112 
    … …  
    2324.. automethod:: beacon.Query.__len__ 
    2425 
    25 Describe monitoring here 
    26  
    27 .. automethod:: beacon.Query.monitor 
    28  
    29 Attributes 
     26Monitoring 
    3027---------- 
    3128 
    32 Query has no public attributes. The monitor method should be a 
    33 property in the future. 
     29FIXME: Describe monitoring here 
    3430 
    35 Signals 
    36 ------- 
     31.. autoattribute:: beacon.Query.monitoring 
     32.. autofunction:: beacon.monitor 
    3733 
    38 .. describe:: changed 
    3934 
    40    Emited when the query result changes. This only works when the 
    41    query has monitoring turned on. 
     35Signal **changed** 
    4236 
    43 .. describe:: process 
     37   Emited when the query result changes. 
    4438 
    45    This signal is emited during initial scanning. Since the Query is 
    46    hidden by an InProgress object, it is not possible to connect to 
    47    this signal anymore. It will be replaced in the future by the 
    48    progress function of InProgress. 
     39Signal **process** 
    4940 
    50    **Arguments**:  
     41   This signal is emited during initial scanning. 
     42 
     43   **Arguments**: 
    5144     - *pos* -- position 
    5245     - *max* -- maximum results 
    5346 
    54    *Deprectated* 
     47Signal **up-to-date** 
    5548 
    56 .. describe:: up-to-date 
     49   This signal is emited after initial scanning. 
    5750 
    58    *Deprectated* 
     51.. _filter: 
     52 
     53Filter 
     54------ 
     55 
     56FIXME: Describe filter here 
     57 
     58.. autofunction:: beacon.register_filter 
     59.. autofunction:: beacon.wrap 

  • trunk/beacon/doc/server.rst

    r3616 r3631  
    1010.. autofunction:: beacon.launch 
    1111.. autofunction:: beacon.connect 
     12.. attribute:: beacon.VERSION 
     13.. exception:: beacon.ConnectError 
    1214 
     15Beacon Clients 
     16-------------- 
     17 
     18* beacon-search 
     19* beacon-mount 

  • trunk/beacon/doc/vision.rst

    r3616 r3631  
    11Vision 
    22====== 
     3 
     4Note: The following text is copied from the beacon vision document 
     5from Jason before beacon was written. The text may require some 
     6updates. 
     7 
     8Beacon's job is to act as an intermediary between the application and 
     9the filesystem. It will offer an interface for applications to perform 
     10queries on files. The result set can include any known data about the 
     11files that match the query. For example, if one of the files in the 
     12result set is an image, it could include the image's dimensions, color 
     13space, thumbnail, EXIF data (in the case of a JPEG), precomputed 
     14histogram, and so on. 
     15 
     16Queries can include evaluations on any indexed field. One common query 
     17would be "get a list of all files in directory X." Another possible 
     18query is "get all music by Queen." Another slightly more complicated 
     19query is "get all music by Moby, and all movies whose soundtrack has 
     20Moby." Beacon is responsible for gathering all data necessary to 
     21compute such queries and providing an appropriate interface to the 
     22application. How Beacon computes such queries internally may vary, but 
     23the API should not make this difference evident. 
     24 
     25Another necessary feature of Beacon is notification of changes to the 
     26query. If an application queries "all files in directory X," it should 
     27be able to request notifications to changes, so that if, for example, 
     28a file is added to directory X, the application is appropriately 
     29notified. The actual behavior or performance may vary based on kernel 
     30support or the nature of the query, but the API Beacon provides to the 
     31application must support this functionality. 
     32 
     33Common Use-Cases 
     34---------------- 
     35 
     36The typical user will have a collection of media files, likely 
     37organized in one or more hierarchies, on either a local filesystem, or 
     38accessible via NFS or SMB. Users will also commonly have files stored 
     39on removable media, such as USB drives, CDs, or DVDs. 
     40 
     41Let's explore some scenarios of how the user will want to interact 
     42with Beacon, and how we expect the interface might behave: 
     43 
     441. The user enters a directory of images on the local harddisk. The 
     45   interface will display a grid of thumbnails in the current 
     46   directory. The directory contents should be displayed in the 
     47   interface as quickly as possible. Files are initially represented 
     48   by a "Thumbnail loading" icon, and the icons are updated with the 
     49   thumbnails as they are loaded. This process does not block the 
     50   interface. 
     51 
     522. While the user is in the directory above, she copies a new image to 
     53   that directory through some external method. The interface should 
     54   quickly update to reflect the addition to the directory with the 
     55   "Thumbnail loading" icon and subsequent thumbnail as described 
     56   above. The user then deletes the image, and the interface quickly 
     57   removes the image from the displayed list. 
     58 
     593. The user does a search for all music by Delerium. The interface 
     60   displays a list of all songs matching this criteria. 
     61 
     624. On another computer, the user copies an MP3 file of a new song by 
     63   Delerium to one of her music directories over her local 
     64   network. The interface quickly updates the list from the above 
     65   query to reflect the new song. (This assumes the MP3 has the proper 
     66   ID3 tags.) 
     67 
     685. The user inserts a Delerium CD into the CD ROM drive. The list from 
     69   the earlier query updates to show the songs from this CD. (This 
     70   assumes the CD is listed in an accessible CDDB directory or that 
     71   the CD has already been indexed.) 
     72 
     736. The user does a search for all images with the keyword 
     74   vacation. The interface presents a list of thumbnails for images 
     75   which the user has previously tagged with the vacation keyword. 
     76 
     777. The user inserts a DVD into the DVD drive which contains a number 
     78   of images from her Hawaii vacation. This DVD was previously viewed 
     79   by the user and she tagged the DVD with the vacation 
     80   keyword. Shortly after the DVD is inserted, the list from the query 
     81   in #6 automatically begins updating to show all images on the DVD. 
     82 
     838. The user does a search for all movies directed by Kevin Smith. The 
     84   interface displays a list of movies on the harddisk matching this 
     85   query, which are represented by images of their DVD covers. The 
     86   list further displays all DVD movies by Kevin Smith that the user 
     87   has played before. The interface will provide some appropriate 
     88   indication that these DVDs are not present and must be inserted 
     89   before they can be played. The user saves this query under the 
     90   title Movies by Kevin Smith. 
     91 
     929. The user inserts a data DVD containing a number of MPEG4 
     93   movies. The interface shows some indication that a DVD has been 
     94   inserted. The user navigates to the DVD and it presents a list of 
     95   video files (acquired through Beacon) on the root of the DVD with 
     96   thumbnails. One of these movies is Dogma, by Kevin Smith. The user 
     97   accesses the necessary interface to perform an online lookup by 
     98   movie title, and selects the appropriate movie title/year for that 
     99   video file. The user then navigates the interface to the saved 
     100   query Movies by Kevin Smith and the interface shows the same list 
     101   as in #8 with the addition of the recently added Dogma, which is 
     102   now represented by an image of the Dogma DVD cover, rather than a 
     103   thumbnail as before. The interface indicates that Dogma is stored 
     104   on a DVD and is currently accessible. 
     105 
     106The above use-cases illustrate some of the functionality the 
     107application will require from Beacon. This list is not comprehensive, 
     108and in many cases it may not be a very good idea for the interface to 
     109behave exactly as described. However, Beacon should make any of the 
     110above possible. 
     111 
     112 
     113Feature Overview 
     114---------------- 
     115 
     116From these use-cases we can derive a number of features we require Beacon to have: 
     117 
     1181. List and index files in a requested directory. When Beacon indexes 
     119   a file, it gathers any data it can about the file (metadata), which 
     120   will depend on media type, and stores that metadata for future 
     121   retrieval. Directories with thousands of files should be handled 
     122   gracefully. 
     123 
     1242. To ensure quick response, Beacon must index files, or load 
     125   previously indexed metadata, asynchronously. When an application 
     126   requests a directory list, Beacon will first obtain minimal data (a 
     127   list of file names, sizes, and modification times). If the time for 
     128   this operation so far is less than 0.1 seconds (the maximum time 
     129   which the user perceives instant response), Beacon will begin 
     130   loading previously indexed data until 0.1 seconds is reached. It 
     131   will then return to the application the complete file list, and all 
     132   metadata it managed to load before the 0.1 second timeout. For 
     133   those files whose metadata was not loaded, it will load 
     134   asynchronously and inform the application using some notification 
     135   mechanism so that the interface may be updated as needed. 
     136 
     1373. Beacon must be able to monitor directories for changes. A changed 
     138   directory is one which contains an added file, a deleted file, or 
     139   modified file that the application is not aware of. There must be 
     140   an API to provide a means for the application to receive change 
     141   notifications. 
     142 
     1434. There must be some method to query all indexed files by certain 
     144   metadata fields. Querying should behave as described in #1 and 
     145   #2. In fact, even though they may be implemented differently within 
     146   Beacon, the API to obtain a list of files in a directory and to 
     147   query by metadata should be the same; they are both queries. 
     148 
     1495. Similar to #2, Beacon should be able to monitor queries for 
     150   changes. This is much more complicated than monitoring a single 
     151   directory as in #2 because it requires monitoring all directories 
     152   in the user's media repository and performing automatic indexing of 
     153   new or changed files. Because this requires support from the kernel 
     154   that may not be present on all systems , this live indexing should 
     155   be optional. This means that Beacon should not rely on this 
     156   functionality internally. 
     157 
     1586. Beacon must be able to monitor removable media devices and 
     159   determine when removable media has been added or removed. It must 
     160   provide an API so that the application can be notified of such 
     161   events. 
     162 
     1637. Beacon must be able to index files on removable media, and 
     164   distinguish between two files with the same name but on different 
     165   media. For example, if the CDROM is mounted under /mnt/cdrom and 
     166   there exists a file foo.jpg on two different CDs, Beacon should 
     167   treat these as separate files, even though they have the same 
     168   pathname /mnt/cdrom/foo.jpg. 
     169 
     1708. Beacon must allow the application to store and retrieve metadata 
     171   for a file. For example, in use-case #9, Beacon will retrieve 
     172   certain metadata about the video such as resolution or length 
     173   transparently to the application, but the application will retrieve 
     174   the DVD image cover. 

  • trunk/beacon/src/__init__.py

    r3624 r3631  
    3030# ----------------------------------------------------------------------------- 
    3131 
    32 """ 
    33 kaa.beacon 
    34 ========== 
    35  
    36 @group Internal Classes: Thumbnail, Item, File, Query, Media 
    37 @group Server: connect, launch 
    38 @group Query: query, get, monitor, register_filter, wrap 
    39 @group Media Handling: list_media, delete_media 
    40 @group Database Manipulation: add_item, register_inverted_index, 
    41     register_file_type_attrs, register_track_type_attrs, get_db_info 
    42 @group Thumbnailing: THUMBNAIL_NORMAL, THUMBNAIL_LARGE 
    43 @group kaa.db Variables: ATTR_SIMPLE, ATTR_SEARCHABLE, ATTR_IGNORE_CASE, ATTR_INDEXED, 
    44     ATTR_INDEXED_IGNORE_CASE, ATTR_INVERTED_INDEX 
    45 """ 
    46  
    4732__all__ = [ 'connect', 'launch', 'get', 'query', 'monitor', 'add_item', 'wrap', 
    48             'register_file_type_attrs', 'register_track_type_attrs', 
     33            'register_file_type_attrs', 'register_track_type_attrs', 'ConnectError', 
    4934            'register_inverted_index', 'get_db_info', 'list_media', 'delete_media', 
    5035            'register_filter', 'Item', 'Query', 'Media', 'File', 'Thumbnail', 
    … …  
    7257from item import Item 
    7358from file import File 
    74 from version import VERSION 
    7559from media import Media 
    7660from kaa.db import * 
    … …  
    165149    the server and will keep the database up to date. 
    166150 
    167     @param directory: directory path name 
     151    :param directory: directory path name 
    168152    """ 
    169153    if not _client: 
    … …  
    175159    List all media objects. 
    176160 
    177     @returns: list of the available media 
    178     @rtype: list of L{Media} 
     161    :returns: list of the available media 
    179162    """ 
    180163    if not _client: 
    … …  
    186169    Delete media with the given id. 
    187170 
    188     @param id: Media object ID 
     171    :param id: Media object ID 
    189172    """ 
    190173    if not _client: 
    … …  
    199182    or a meta item with http items as children. 
    200183 
    201     @param url: url of the Item, can not be file: 
    202     @param type: item type 
    203     @param parent: parent item 
    204     @param kwargs: addition keyword/value arguments for the db 
    205     @returns: new created item 
    206     @rtype: L{Item} 
     184    :param url: url of the Item, can not be file: 
     185    :param type: item type 
     186    :param parent: parent item 
     187    :param kwargs: addition keyword/value arguments for the db 
     188    :returns: new created Item 
    207189    """ 
    208190    if not _client: 
    … …  
    248230    Gets statistics about the database. 
    249231 
    250     @return: basic database information 
     232    :returns: basic database information 
    251233    """ 
    252234    if not _client: 

  • trunk/beacon/src/file.py

    r3616 r3631  
    6868    def list(self, recursive=False): 
    6969        """ 
    70         List all files in a directory or show subitems of a file. 
    71  
    72         @returns: InProgress object of a kaa.beacon.Query 
     70        Return a Query object for a query with all files in the 
     71        directory. If the Item is no directory all subitems will 
     72        returned similar to the Item list function. This can happen 
     73        for DVD iso files on hard-disc. If the client is not connected 
     74        to the server an empty list will be returned instead. 
    7375        """ 
    7476        # Note: this function is not used internally 
    … …  
    7880        """ 
    7981        Request the item to be scanned. 
    80  
    81         @returns: False if not connected or an InProgress object. 
    8282        """ 
    8383        # Note: this function is not used by the server 

  • trunk/beacon/src/item.py

    r3616 r3631  
    6666    def get(self, key, default=None): 
    6767        """ 
    68         Access attributes of the item. 
    69  
    70         :param key: Attribute name 
    71         :param default: Default return when the attribute is not set 
     68        Access attributes of the item. If the attribute is not found 
     69        the default value (None) will be returned. 
    7270        """ 
    7371        if key.startswith('tmp:'): 
    … …  
    113111    def __getitem__(self, key): 
    114112        """ 
    115         Access attributes of the item 
     113        Access attributes of the item. This function will never raise 
     114        an exception. If the attribute is not found, None will be 
     115        returned. 
    116116        """ 
    117117        return self.get(key) 
    … …  
    121121        Set the value of a given attribute. If the key starts with 
    122122        'tmp:', the data will only be valid in this item and not 
    123         stored in the db. Loosing the item object will remove that 
    124         attribute. 
     123        stored in the db. 
    125124        """ 
    126125        if key.startswith('tmp:'): 
    … …  
    140139    def has_key(self, key): 
    141140        """ 
    142         Check if the item has a specific attributes set 
     141        Check if the item has a specific attribute set 
    143142        """ 
    144143        return key in self._beacon_data.keys() or \ 
    … …  
    169168    def thumbnail(self): 
    170169        """ 
    171         Return Thumbnail for the Item 
     170        Return a Thumbnail for the Item. See :ref:`thumbnail` for 
     171        details about thumbnailing works in beacon. 
    172172        """ 
    173173        return self.get('thumbnail') 
    … …  
    175175    def list(self): 
    176176        """ 
    177         Return all subitems to his item. 
    178  
    179         :returns: InProgress object with empty list or :class:`beacon.Query` 
     177        Return a Query object with all subitems of this item. If the 
     178        client is not connected to the server an empty list will be 
     179        returned instead. 
    180180        """ 
    181181        # This function is not used internally 

  • trunk/beacon/src/query.py

    r3630 r3631  
    5151    Register a filter for L{Query} or L{wrap} to process a list of items. 
    5252 
    53     @param name: unique name for the filter 
    54     @param function: filter function 
     53    :param name: unique name for the filter 
     54    :param function: filter function 
    5555    """ 
    5656    _query_filter[name] = function 
    … …  
    6161    Wrap the given list of items with the given filter function 
    6262 
    63     @param items: list of items 
    64     @param filter: name of the filter, see L{register_filter} 
     63    :param items: list of items 
     64    :param filter: name of the filter, see L{register_filter} 
    6565    """ 
    6666    if not filter in _query_filter: 
    … …  
    154154        Iterate through the results. 
    155155 
    156         @returns: Iterator 
    157         @rtype: L{Item} or L{File} 
     156        :returns: Iterator over Items 
    158157        """ 
    159158        return self.result.__iter__() 
    … …  
    164163        Get a specific item in the results list. 
    165164 
    166         @returns: Item on that position in the list 
    167         @rtype: L{Item} or L{File} 
    168         @raises IndexError: result list is shorten than pos 
     16