# Class e.c.c.m.MediaProvider(Component):

Part of elisa.core.components.media_provider View In Hierarchy

Known subclasses: elisa.core.tests.test_media_manager.AnotherFooMediaProvider, elisa.core.tests.test_media_manager.FooMediaProvider, elisa.plugins.aggregator.podcatcher_media.PodcatcherMedia, elisa.plugins.audiocd.audiocd_media.AudiocdMedia, elisa.plugins.coherence.upnp_media.UPnPMedia, elisa.plugins.dailymotion.dailymotion_media.DailymotionMedia, elisa.plugins.fspot.fspot_media.FspotMedia, elisa.plugins.gvfs.gnomevfs_media.GnomevfsMedia, elisa.plugins.media_db.elisa_media.ElisaMedia, elisa.plugins.picasa.picasa_media.PicasaMedia, elisa.plugins.rhythmbox.rb_media.RbMedia, elisa.plugins.webtv.mmslist_media.MmslistMedia

Medias are all accessible using URIs. MediaProvider components are responsible to support one or many URI schemes.

MediaProviders are able to parse media trees of supported URI(s) scheme(s), they can also provide limited information about parsed files and directories.

MediaProviders can optionnally monitor media locations and notify registered components of data updates (new/updated/deleted files/directories).

TODO:

- blocking_{copy,move,delete} ?

Class Variables | scannable_uri_schemes | DOCME (type: list )
| supported_uri_schemes | DOCME (type: dict mapping string to int )

Line # | Kind | Name | Docs
--- | --- | --- | ---
69 | Method | scannable_uri_schemes__get | Retrieve the URI schemes that can be scanned by the
85 | Method | supported_uri_schemes__get | Retrieve the URI schemes supported by the provider, for each
112 | Method | get_real_uri | Returns the original uri (acesable) from a virtual
124 | Method | get_media_type | Same as `blocking_get_media_type` but without blocking (in
156 | Method | is_directory | Same as `_blocking_is_directory` but without blocking (in
178 | Method | has_children_with_types | Same as `_blocking_has_children_with_types` but without blocking (in
207 | Method | get_direct_children | Same as `_blocking_get_direct_children` but without blocking (in
251 | Method | open | Same as `_blocking_open` but without blocking (in
286 | Method | close | Same as `_blocking_close` but without blocking (in
308 | Method | seek | Same as `_blocking_seek` but without blocking (in
339 | Method | read | Same as `_blocking_seek` but without blocking (in
371 | Method | next_location | Same as `_blocking_next_location` but without blocking (in
399 | Method | previous_location | Same as `_blocking_previous_location` but without blocking (in
422 | Method | monitor_uri | Start monitoring given uri for modification and call a
441 | Method | unmonitor_uri | Stop monitoring given uri.
450 | Method | uri_is_monitorable | Check if the uri is monitorable for modification
461 | Method | uri_is_monitored | Check if the uri is currently monitored for modification
473 | Method | copy | Copy one location to another. If both URIs represent a
492 | Method | move | Move data located at given URI to another URI. If orig_uri
509 | Method | delete | Delete a resource located at given URI. If that URI represents

Inherited from Component:

Line # | Kind | Name | Docs
--- | --- | --- | ---
85 | Class | PathDescriptor | Undocumented
97 | Class Method | create | Create and initialize the component.
130 | Method | initialize | Initialize the component.
142 | Method | clean | Clean the component.

Inherited from Loggable (via Component):

Line # | Kind | Name | Docs
--- | --- | --- | ---
81 | Method | __init__ | Undocumented

def scannable_uri_schemes__get(self):
overridden in elisa.plugins.aggregator.podcatcher_media.PodcatcherMedia, elisa.plugins.audiocd.audiocd_media.AudiocdMedia, elisa.plugins.coherence.upnp_media.UPnPMedia, elisa.plugins.dailymotion.dailymotion_media.DailymotionMedia, elisa.plugins.fspot.fspot_media.FspotMedia, elisa.plugins.gvfs.gnomevfs_media.GnomevfsMedia, elisa.plugins.media_db.elisa_media.ElisaMedia, elisa.plugins.picasa.picasa_media.PicasaMedia, elisa.plugins.webtv.mmslist_media.MmslistMedia

Retrieve the URI schemes that can be scanned by the media_scanner. Since media scanning can be an heavy and long task the MediaProvider developer can choose to make the media_scanner skip URIs with scheme not appearing in returned list.

By default the return value of this method corresponds to the keys of `supported_uri_schemes__get` return value.

# FIXME: this should be documented in the class docstring as a class # variable

def supported_uri_schemes__get(self):
overridden in elisa.core.tests.test_media_manager.AnotherFooMediaProvider, elisa.core.tests.test_media_manager.FooMediaProvider, elisa.plugins.aggregator.podcatcher_media.PodcatcherMedia, elisa.plugins.audiocd.audiocd_media.AudiocdMedia, elisa.plugins.coherence.upnp_media.UPnPMedia, elisa.plugins.dailymotion.dailymotion_media.DailymotionMedia, elisa.plugins.fspot.fspot_media.FspotMedia, elisa.plugins.gvfs.gnomevfs_media.GnomevfsMedia, elisa.plugins.media_db.elisa_media.ElisaMedia, elisa.plugins.picasa.picasa_media.PicasaMedia, elisa.plugins.rhythmbox.rb_media.RbMedia, elisa.plugins.webtv.mmslist_media.MmslistMedia

Retrieve the URI schemes supported by the provider, for each scheme there's a priority. Higher priority == 0 means the provider will always be used to read data from a given scheme.

This function is called by the MediaManager to know which media provider it has to use to access a specified URI. You should return a dict containing the uri scheme (such as 'file', 'cdda', ...) and its priority between 0 to 255 (0 being the topmost priority). The prority is used by the MediaManager to know which media provider it should use in case there are more than one who support the desired uri scheme. You might have for example a component which supports more than one scheme, but the support of one of them is not very efficient compared to what it could be. In this case you could modify its priority to tell the MediaManager that another component should be used instead of it to access this scheme.

example: { 'file': 0, 'smb': 10 }

# FIXME: this should be documented in the class docstring as a class # variable

def get_real_uri(self, uri):
overridden in elisa.plugins.aggregator.podcatcher_media.PodcatcherMedia, elisa.plugins.coherence.upnp_media.UPnPMedia, elisa.plugins.dailymotion.dailymotion_media.DailymotionMedia, elisa.plugins.fspot.fspot_media.FspotMedia, elisa.plugins.picasa.picasa_media.PicasaMedia, elisa.plugins.rhythmbox.rb_media.RbMedia, elisa.plugins.webtv.mmslist_media.MmslistMedia
Returns the original uri (acesable) from a virtual uri representation.

Parameters | uri | the URI to validate (type: `elisa.core.media_uri.MediaUri` )
Returns | (type: `elisa.core.media_uri.MediaUri` )

def get_media_type(self, uri):
overridden in elisa.plugins.dailymotion.dailymotion_media.DailymotionMedia, elisa.plugins.gvfs.gnomevfs_media.GnomevfsMedia, elisa.plugins.media_db.elisa_media.ElisaMedia, elisa.plugins.picasa.picasa_media.PicasaMedia, elisa.plugins.webtv.mmslist_media.MmslistMedia
Same as `blocking_get_media_type` but without blocking (in theory). This method by default triggers a succeeded callback on a Twisted deferred, using `blocking_get_media_type` result.

Parameters | uri | the URI to analyze (type: `elisa.core.media_uri.MediaUri` )
Returns | (type: `twisted.internet.defer.Deferred` )

def is_directory(self, uri):
overridden in elisa.plugins.dailymotion.dailymotion_media.DailymotionMedia, elisa.plugins.gvfs.gnomevfs_media.GnomevfsMedia, elisa.plugins.media_db.elisa_media.ElisaMedia, elisa.plugins.picasa.picasa_media.PicasaMedia
Same as `_blocking_is_directory` but without blocking (in theory). This method by default triggers a succeeded callback on a Twisted deferred, using `_blocking_is_directory` result.

Parameters | uri | the URI to analyze (type: `elisa.core.media_uri.MediaUri` )
Returns | (type: `twisted.internet.defer.Deferred` )

def has_children_with_types(self, uri, media_types):
overridden in elisa.plugins.coherence.upnp_media.UPnPMedia, elisa.plugins.dailymotion.dailymotion_media.DailymotionMedia, elisa.plugins.fspot.fspot_media.FspotMedia, elisa.plugins.gvfs.gnomevfs_media.GnomevfsMedia, elisa.plugins.media_db.elisa_media.ElisaMedia, elisa.plugins.picasa.picasa_media.PicasaMedia, elisa.plugins.rhythmbox.rb_media.RbMedia, elisa.plugins.webtv.mmslist_media.MmslistMedia
Same as `_blocking_has_children_with_types` but without blocking (in theory). This method by default triggers a succeeded callback on a Twisted deferred, using `_blocking_has_children_with_types` result.

Parameters | uri | the URI to scan (type: `elisa.core.media_uri.MediaUri` )
| media_types | the media_types to look for on the directory (type: list of strings )
Returns | (type: `twisted.internet.defer.Deferred` )

def get_direct_children(self, uri, children_with_info):
overridden in elisa.plugins.audiocd.audiocd_media.AudiocdMedia, elisa.plugins.coherence.upnp_media.UPnPMedia, elisa.plugins.dailymotion.dailymotion_media.DailymotionMedia, elisa.plugins.fspot.fspot_media.FspotMedia, elisa.plugins.gvfs.gnomevfs_media.GnomevfsMedia, elisa.plugins.media_db.elisa_media.ElisaMedia, elisa.plugins.picasa.picasa_media.PicasaMedia, elisa.plugins.rhythmbox.rb_media.RbMedia, elisa.plugins.webtv.mmslist_media.MmslistMedia
Same as `_blocking_get_direct_children` but without blocking (in theory). This method by default triggers a succeeded callback on a Twisted deferred, using `_blocking_get_direct_children` result.

Parameters | uri | the URI to analyze (type: `elisa.core.media_uri.MediaUri` )
| children_with_info | List where the children will be appended (type: list )
Returns | (type: `twisted.internet.defer.Deferred` )

def open(self, uri, mode=None):
overridden in elisa.plugins.coherence.upnp_media.UPnPMedia, elisa.plugins.gvfs.gnomevfs_media.GnomevfsMedia
Same as `_blocking_open` but without blocking (in theory). This method by default triggers a succeeded callback on a Twisted deferred, using `_blocking_open` result.

Parameters | uri | the URI to open (type: `elisa.core.media_uri.MediaUri` )
| mode | how to open the file -- see manual of builtin open() (type: string or None )
Returns | (type: `twisted.internet.defer.Deferred` )
Note | It's not allowed to open directories, it's up to the developer to check that the URI to open doesn't represent a directory.

def close(self, media_file):
Same as `_blocking_close` but without blocking (in theory). This method by default triggers a succeeded callback on a Twisted deferred, using `_blocking_close` result.

Parameters | media_file | the file to close (type: `elisa.core.media_file.MediaFile` )
Returns | (type: `twisted.internet.defer.Deferred` )

def seek(self, media_file, offset, whence=0):
Same as `_blocking_seek` but without blocking (in theory). This method by default triggers a succeeded callback on a Twisted deferred, using `_blocking_seek` result.

Parameters | media_file | the file to seek in (type: `elisa.core.media_file.MediaFile` )
| offset | how many bytes to seek (type: int )
| whence | from where to seek (type: int (default=0) )
Returns | (type: `twisted.internet.defer.Deferred` )

def read(self, media_file, size=-1):
overridden in elisa.plugins.gvfs.gnomevfs_media.GnomevfsMedia
Same as `_blocking_seek` but without blocking (in theory). This method by default triggers a succeeded callback on a Twisted deferred, using `_blocking_seek` result.

Parameters | media_file | the file to read data from (type: `elisa.core.media_file.MediaFile` )
| size | how many data we should try to read (type: int (default: -1 == all) )
Returns | (type: `twisted.internet.defer.Deferred` )

def next_location(self, uri, root=None):
overridden in elisa.plugins.audiocd.audiocd_media.AudiocdMedia, elisa.plugins.gvfs.gnomevfs_media.GnomevfsMedia
Same as `_blocking_next_location` but without blocking (in theory). This method by default triggers a succeeded callback on a Twisted deferred, using `_blocking_next_location` result.

Parameters | uri | the URI representing the file or directory from where to move on (type: `elisa.core.media_uri.MediaUri` )
| root | root URI (type: `elisa.core.media_uri.MediaUri` )
Returns | (type: `twisted.internet.defer.Deferred` )

def previous_location(self, uri):
overridden in elisa.plugins.audiocd.audiocd_media.AudiocdMedia
Same as `_blocking_previous_location` but without blocking (in theory). This method by default triggers a succeeded callback on a Twisted deferred, using `_blocking_previous_location` result.

Parameters | uri | the URI representing the file or directory prior to uri (type: `elisa.core.media_uri.MediaUri` )
Returns | (type: `twisted.internet.defer.Deferred` )

def monitor_uri(self, uri, callback):
Start monitoring given uri for modification and call a function in case of any change happening on `uri` Raises UriNotMonitorable(uri) if uri can't be monitored

Parameters | uri | URI representing the file or directory to monitor (type: `elisa.core.media_uri.MediaUri` )
| callback | a callable taking the event that occured and the uri of the file on which the event applies to prototype: callable(uri, metadata, event) type uri: `elisa.core.media_uri.MediaUri` type metadata: dict type event: `elisa.core.components.media_provider.NotifyEvent`
Raises | UriNotMonitorable | if the uri cannot be monitored

def unmonitor_uri(self, uri):
Stop monitoring given uri.

Parameters | uri | the URI representing the file or directory to monitor (type: `elisa.core.media_uri.MediaUri` )

def uri_is_monitorable(self, uri):
overridden in elisa.plugins.audiocd.audiocd_media.AudiocdMedia, elisa.plugins.dailymotion.dailymotion_media.DailymotionMedia, elisa.plugins.media_db.elisa_media.ElisaMedia, elisa.plugins.picasa.picasa_media.PicasaMedia
Check if the uri is monitorable for modification

Parameters | uri | the URI representing the file or directory for which we would like to know if it is monitorable or not (type: `elisa.core.media_uri.MediaUri` )
Returns | (type: bool )

def uri_is_monitored(self, uri):
overridden in elisa.plugins.audiocd.audiocd_media.AudiocdMedia
Check if the uri is currently monitored for modification

Parameters | uri | the URI representing the file or directory for which we would like to know if it is currently monitored or not (type: `elisa.core.media_uri.MediaUri` )
Returns | (type: bool )

def copy(self, orig_uri, dest_uri, recursive=False):
Copy one location to another. If both URIs represent a directory and recursive flag is set to True I will recursively copy the directory to the destination URI.

Parameters | orig_uri | the URI to copy, can represent either a directory or a file (type: `elisa.core.media_uri.MediaUri` )
| dest_uri | the destination URI, can represent either a directory or a file (type: `elisa.core.media_uri.MediaUri` )
| recursive | if orig_uri represents a directory, should I copy it recursively to dest_uri? (type: bool )
Returns | (type: `twisted.internet.defer.Deferred` )

def move(self, orig_uri, dest_uri):
Move data located at given URI to another URI. If orig_uri represents a directory it will recusively be moved to dest_uri. In the case where orig_uri is a directory, dest_uri can't be a file.

Parameters | orig_uri | the URI to move, can represent either a directory or a file (type: `elisa.core.media_uri.MediaUri` )
| dest_uri | the destination URI, can represent either a directory or a file (type: `elisa.core.media_uri.MediaUri` )
Returns | (type: `twisted.internet.defer.Deferred` )

def delete(self, uri, recursive=False):
Delete a resource located at given URI. If that URI represents a directory and recursive flag is set to True I will recursively remove the directory.

Parameters | uri | the URI representing the file or directory for which we would like to know if it is currently monitored or not (type: `elisa.core.media_uri.MediaUri` )
| recursive | if orig_uri represents a directory, should I copy it recursively to dest_uri? (type: bool )
Returns | (type: `twisted.internet.defer.Deferred` )