Package elisa :: Package base_components :: Module media_provider :: Class MediaProvider
[hide private]
[frames] | no frames]

Class MediaProvider

source code


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:

Nested Classes [hide private]

Inherited from core.component.Component: __metaclass__

Instance Methods [hide private]
 
scannable_uri_schemes__get(self)
Retrieve the URI schemes that can be scanned by the media_scanner.
source code
 
supported_uri_schemes__get(self)
Retrieve the URI schemes supported by the provider, for each scheme there's a priority.
source code
elisa.core.media_uri.MediaUri
get_real_uri(self, uri)
Returns the original uri (acesable) from a virtual uri representation.
source code
twisted.internet.defer.Deferred
get_media_type(self, uri)
Same as blocking_get_media_type but without blocking (in theory).
source code
dict
_blocking_get_media_type(self, uri)
Try to guess the maximum information from the media located at given uri by looking at eventual file extension.
source code
twisted.internet.defer.Deferred
is_directory(self, uri)
Same as _blocking_is_directory but without blocking (in theory).
source code
bool
_blocking_is_directory(self, uri)
return True if a directory
source code
twisted.internet.defer.Deferred
has_children_with_types(self, uri, media_types)
Same as _blocking_has_children_with_types but without blocking (in theory).
source code
bool
_blocking_has_children_with_types(self, uri, media_types)
Detect whether the given uri has children for given media types which can be one of media_provider.media_types.
source code
twisted.internet.defer.Deferred
get_direct_children(self, uri, children_with_info)
Same as _blocking_get_direct_children but without blocking (in theory).
source code
list
_blocking_get_direct_children(self, uri, children_with_info)
Scan the data located at given uri and return informations about its children.
source code
twisted.internet.defer.Deferred
open(self, uri, mode='frontend')
Same as _blocking_open but without blocking (in theory).
source code
elisa.core.media_file.MediaFile
_blocking_open(self, uri, mode='frontend')
Open an uri and return MediaFile.
source code
twisted.internet.defer.Deferred
close(self, media_file)
Same as _blocking_close but without blocking (in theory).
source code
 
_blocking_close(self, media_file)
Close a MediaFile
source code
twisted.internet.defer.Deferred
seek(self, media_file, offset, whence=0)
Same as _blocking_seek but without blocking (in theory).
source code
 
_blocking_seek(self, media_file, offset, whence=0)
Seek data in a MediaFile
source code
twisted.internet.defer.Deferred
read(self, media_file, size=-1)
Same as _blocking_seek but without blocking (in theory).
source code
string
_blocking_read(self, media_file, size=-1)
Read data from a MediaFile
source code
twisted.internet.defer.Deferred
next_location(self, uri, root='frontend')
Same as _blocking_next_location but without blocking (in theory).
source code
elisa.core.media_uri.MediaUri
_blocking_next_location(self, uri, root='frontend')
Return the uri just next to given uri.
source code
twisted.internet.defer.Deferred
previous_location(self, uri)
Same as _blocking_previous_location but without blocking (in theory).
source code
elisa.core.media_uri.MediaUri
_blocking_previous_location(self, uri)
Return the uri found before given uri
source code
 
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
source code
 
unmonitor_uri(self, uri)
Stop monitoring given uri.
source code
bool
uri_is_monitorable(self, uri)
Check if the uri is monitorable for modification
source code
bool
uri_is_monitored(self, uri)
Check if the uri is currently monitored for modification
source code
twisted.internet.defer.Deferred
copy(self, orig_uri, dest_uri, recursive=True)
Copy one location to another.
source code
twisted.internet.defer.Deferred
move(self, orig_uri, dest_uri)
Move data located at given URI to another URI.
source code
twisted.internet.defer.Deferred
delete(self, uri, recursive=True)
Delete a resource located at given URI.
source code

Inherited from core.component.Component: __init__, clean, initialize, load_config, save_config

Inherited from extern.log.log.Loggable: debug, doLog, error, info, log, logFunction, logObjectName, warning, warningFailure

Inherited from object: __delattr__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __str__

Static Methods [hide private]

Inherited from core.component.Component: __classinit__

Class Variables [hide private]
string name = 'media_provider'
Component's name

Inherited from core.component.Component: checked, config_doc, default_config, id, plugin

Inherited from extern.log.log.Loggable: logCategory

Instance Variables [hide private]

Inherited from core.component.Component: config, path

Properties [hide private]
list scannable_uri_schemes
DOCME
dict mapping string to int supported_uri_schemes
DOCME

Inherited from object: __class__

Method Details [hide private]

scannable_uri_schemes__get(self)

source code 

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

supported_uri_schemes__get(self)

source code 

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

get_real_uri(self, uri)

source code 
Returns the original uri (acesable) from a virtual uri representation.
Parameters:
Returns: elisa.core.media_uri.MediaUri

get_media_type(self, uri)

source code 
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:
Returns: twisted.internet.defer.Deferred

_blocking_get_media_type(self, uri)

source code 
Try to guess the maximum information from the media located at given uri by looking at eventual file extension. Will return something like:
 {'file_type': string (values: one of media_provider.media_types)
  'mime_type': string (example: 'audio/mpeg' for .mp3 uris. can be
                      empty string if unguessable)
  }
'file_type' and 'mime_type' can be empty strings if it failed recognizing them.
Parameters:
Returns: dict

is_directory(self, uri)

source code 
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:
Returns: twisted.internet.defer.Deferred

_blocking_is_directory(self, uri)

source code 
return True if a directory
Parameters:
Returns: bool

has_children_with_types(self, uri, media_types)

source code 
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:
Returns: twisted.internet.defer.Deferred

_blocking_has_children_with_types(self, uri, media_types)

source code 
Detect whether the given uri has children for given media types which can be one of media_provider.media_types. Implies the URI is a directory as well.
Parameters:
Returns: bool

get_direct_children(self, uri, children_with_info)

source code 
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:
Returns: twisted.internet.defer.Deferred

_blocking_get_direct_children(self, uri, children_with_info)

source code 

Scan the data located at given uri and return informations about its children. Fills children_with_info.

Typemap of filled result:
 [
    (uri : media_uri.MediaUri,
     additional info: dict),
   ...
 ]
If you supply additional info, they should be stored in a elisa.core.observers.dict.DictObservable instead of a normal dictionnary. Valid keys:
 ['default_image', 'artist', 'album', 'song', 'song_artist',
  'song_album']
Parameters:
Returns: list

open(self, uri, mode='frontend')

source code 
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:
Returns: 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.

_blocking_open(self, uri, mode='frontend')

source code 
Open an uri and return MediaFile.
Parameters:
Returns: elisa.core.media_file.MediaFile

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.

close(self, media_file)

source code 
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:
Returns: twisted.internet.defer.Deferred

_blocking_close(self, media_file)

source code 
Close a MediaFile
Parameters:

seek(self, media_file, offset, whence=0)

source code 
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:
Returns: twisted.internet.defer.Deferred

_blocking_seek(self, media_file, offset, whence=0)

source code 
Seek data in a MediaFile
Parameters:

read(self, media_file, size=-1)

source code 
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:
Returns: twisted.internet.defer.Deferred

_blocking_read(self, media_file, size=-1)

source code 
Read data from a MediaFile
Parameters:
Returns: string

next_location(self, uri, root='frontend')

source code 
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:
Returns: twisted.internet.defer.Deferred

_blocking_next_location(self, uri, root='frontend')

source code 
Return the uri just next to given uri.
Parameters:
Returns: elisa.core.media_uri.MediaUri

previous_location(self, uri)

source code 
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:
Returns: twisted.internet.defer.Deferred

_blocking_previous_location(self, uri)

source code 
Return the uri found before given uri
Parameters:
Returns: elisa.core.media_uri.MediaUri

monitor_uri(self, uri, callback)

source code 
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:
Raises:

unmonitor_uri(self, uri)

source code 
Stop monitoring given uri.
Parameters:

uri_is_monitorable(self, uri)

source code 
Check if the uri is monitorable for modification
Parameters:
Returns: bool

uri_is_monitored(self, uri)

source code 
Check if the uri is currently monitored for modification
Parameters:
  • uri (elisa.core.media_uri.MediaUri) - the URI representing the file or directory for which we would like to know if it is currently monitored or not
Returns: bool

copy(self, orig_uri, dest_uri, recursive=True)

source code 
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 (elisa.core.media_uri.MediaUri) - the URI to copy, can represent either a directory or a file
  • dest_uri (elisa.core.media_uri.MediaUri) - the destination URI, can represent either a directory or a file
  • recursive (bool) - if orig_uri represents a directory, should I copy it recursively to dest_uri?
Returns: twisted.internet.defer.Deferred

move(self, orig_uri, dest_uri)

source code 
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:
Returns: twisted.internet.defer.Deferred

delete(self, uri, recursive=True)

source code 
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 (elisa.core.media_uri.MediaUri) - the URI representing the file or directory for which we would like to know if it is currently monitored or not
  • recursive (bool) - if orig_uri represents a directory, should I copy it recursively to dest_uri?
Returns: twisted.internet.defer.Deferred

Property Details [hide private]

scannable_uri_schemes

DOCME
Get Method:
elisa.base_components.media_provider.MediaProvider.scannable_uri_schemes__get(self) - Retrieve the URI schemes that can be scanned by the media_scanner.
Set Method:
'frontend'
Delete Method:
'frontend'

supported_uri_schemes

DOCME
Get Method:
elisa.base_components.media_provider.MediaProvider.supported_uri_schemes__get(self) - Retrieve the URI schemes supported by the provider, for each scheme there's a priority.
Set Method:
'frontend'
Delete Method:
'frontend'