TotemPlParser.Parser¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`can_parse_from_data` (data, len, debug)
class	`can_parse_from_filename` (filename, debug)
class	`can_parse_from_uri` (uri, debug)
class	`new` ()
class	`parse_date` (date_str, debug)
class	`parse_duration` (duration, debug)
	`add_ignored_glob` (glob)
	`add_ignored_mimetype` (mimetype)
	`add_ignored_scheme` (scheme)
	`parse` (uri, fallback)
	`parse_async` (uri, fallback, cancellable, callback, *user_data)
	`parse_finish` (async_result)
	`parse_with_base` (uri, base, fallback)
	`parse_with_base_async` (uri, base, fallback, cancellable, callback, *user_data)
	`save` (playlist, dest, title, type)
	`save_async` (playlist, dest, title, type, cancellable, callback, *user_data)
	`save_finish` (async_result)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_entry_parsed` (uri, metadata)
	`do_playlist_ended` (uri)
	`do_playlist_started` (uri, metadata)

Properties¶

Name	Type	Flags	Short Description
`debug`	`bool`	r/w	Whether or not to enable debugging output
`disable-unsafe`	`bool`	r/w	Whether or not to disable parsing of unsafe locations
`force`	`bool`	r/w	Whether or not to force parsing the file if the playlist looks unsupported
`recurse`	`bool`	r/w/c	Whether or not to process URIs further

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`entry-parsed`	The `::entry-parsed` signal is emitted when a new entry is parsed.
`playlist-ended`	The `::playlist-ended` signal is emitted when a playlist is finished parsing.
`playlist-started`	The `::playlist-started` signal is emitted when a playlist parsing has started.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class TotemPlParser.Parser(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: TotemPlParser.ParserClass

All the fields in the TotemPlParser.Parser structure are private and should never be accessed directly.

classmethod can_parse_from_data(data, len, debug)¶

Parameters:

data (str) – the data to check for parsability
len (int) – the length of data to check
debug (bool) – True if debug statements should be printed

Returns:

True if data can be parsed

Return type:

bool

Checks if the first len bytes of data can be parsed.

classmethod can_parse_from_filename(filename, debug)¶

Parameters:

filename (str) – the file to check for parsability
debug (bool) – True if debug statements should be printed

Returns:

True if filename can be parsed

Return type:

bool

Checks if the file can be parsed. Files can be parsed if:

they have a special mimetype, or
they have a mimetype which could be a video or a playlist.

classmethod can_parse_from_uri(uri, debug)¶

Parameters:

uri (str) – the remote URI to check for parsability
debug (bool) – True if debug statements should be printed

Returns:

True if uri could be parsed

Return type:

bool

Checks if the remote URI can be parsed. Note that this does not actually try to open the remote URI, or deduce its mime-type from filename, as this would bring too many false positives.

classmethod new()¶

Returns:: a new TotemPlParser.Parser
Return type:: TotemPlParser.Parser

Creates a TotemPlParser.Parser object.

classmethod parse_date(date_str, debug)¶

Parameters:

date_str (str) – the date string to parse
debug (bool) – True if debug statements should be printed

Returns:

the date in seconds, or -1 on error

Return type:

int

Parses the given date string and returns it as a gint64 denoting the date in seconds since the UNIX Epoch.

classmethod parse_duration(duration, debug)¶

Parameters:

duration (str) – the duration string to parse
debug (bool) – True if debug statements should be printed

Returns:

the duration in seconds, or -1 on error

Return type:

int

Parses the given duration string and returns it as a gint64 denoting the duration in seconds.

add_ignored_glob(glob)¶

Parameters:: glob (str) – a glob to ignore

Adds a glob to the list of mimetypes to ignore, so that any URI of that glob is ignored during playlist parsing.

New in version 3.26.4.

add_ignored_mimetype(mimetype)¶

Parameters:: mimetype (str) – the mimetype to ignore

Adds a mimetype to the list of mimetypes to ignore, so that any URI of that mimetype is ignored during playlist parsing.

add_ignored_scheme(scheme)¶

Parameters:: scheme (str) – the scheme to ignore

Adds a scheme to the list of schemes to ignore, so that any URI using that scheme is ignored during playlist parsing.

parse(uri, fallback)¶

Parameters:

uri (str) – the URI of the playlist to parse
fallback (bool) – True if the parser should add the playlist URI to the end of the playlist on parse failure

Returns:

a TotemPlParser.ParserResult

Return type:

TotemPlParser.ParserResult

Parses a playlist given by the absolute URI uri. This method is synchronous, and will block on (e.g.) network requests to slow servers. TotemPlParser.Parser.parse_async() is recommended instead.

Return values are as TotemPlParser.Parser.parse_with_base().

parse_async(uri, fallback, cancellable, callback, *user_data)¶

Parameters:

uri (str) – the URI of the playlist to parse
fallback (bool) – True if the parser should add the playlist URI to the end of the playlist on parse failure
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when parsing is finished
user_data (object or None) – data to pass to the callback function

Starts asynchronous parsing of a playlist given by the absolute URI uri. self and uri are both reffed/copied when this function is called, so can safely be freed after this function returns.

For more details, see TotemPlParser.Parser.parse(), which is the synchronous version of this function.

When the operation is finished, callback will be called. You can then call TotemPlParser.Parser.parse_finish() to get the results of the operation.

parse_finish(async_result)¶

Parameters:: async_result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: a TotemPlParser.ParserResult
Return type:: TotemPlParser.ParserResult

Finishes an asynchronous playlist parsing operation started with TotemPlParser.Parser.parse_async() or TotemPlParser.Parser.parse_with_base_async().

If parsing of the playlist is cancelled part-way through, TotemPlParser.ParserResult.CANCELLED is returned when this function is called.

parse_with_base(uri, base, fallback)¶

Parameters:

uri (str) – the URI of the playlist to parse
base (str or None) – the base path for relative filenames, or None
fallback (bool) – True if the parser should add the playlist URI to the end of the playlist on parse failure

Returns:

a TotemPlParser.ParserResult

Return type:

TotemPlParser.ParserResult

Parses a playlist given by the absolute URI uri, using base to resolve relative paths where appropriate.

parse_with_base_async(uri, base, fallback, cancellable, callback, *user_data)¶

Parameters:

uri (str) – the URI of the playlist to parse
base (str or None) – the base path for relative filenames, or None
fallback (bool) – True if the parser should add the playlist URI to the end of the playlist on parse failure
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when parsing is finished
user_data (object or None) – data to pass to the callback function

Starts asynchronous parsing of a playlist given by the absolute URI uri, using base to resolve relative paths where appropriate. self and uri are both reffed/copied when this function is called, so can safely be freed after this function returns.

For more details, see TotemPlParser.Parser.parse_with_base(), which is the synchronous version of this function.

When the operation is finished, callback will be called. You can then call TotemPlParser.Parser.parse_finish() to get the results of the operation.

save(playlist, dest, title, type)¶

Parameters:

playlist (TotemPlParser.Playlist) – a TotemPlParser.Playlist
dest (Gio.File) – output Gio.File
title (str) – the playlist title
type (TotemPlParser.ParserType) – a TotemPlParser.ParserType for the outputted playlist

Raises:

GLib.Error

Returns:

True on success

Return type:

bool

Writes the playlist held by self and playlist out to the path pointed by dest. The playlist is written in the format type and is given the title title.

If the output file is a directory the Gio.IOErrorEnum.IS_DIRECTORY error will be returned, and if the file is some other form of non-regular file then a Gio.IOErrorEnum.NOT_REGULAR_FILE error will be returned. Some file systems don’t allow all file names, and may return a Gio.IOErrorEnum.INVALID_FILENAME error, and if the name is too long, Gio.IOErrorEnum.FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

In extreme cases, a Gio.IOErrorEnum.INVALID_ARGUMENT error can be returned, if parts of the playlist to be written are too long.

If writing a PLA playlist and there is an error converting a URI’s encoding, a code from GLib.ConvertError will be returned.

save_async(playlist, dest, title, type, cancellable, callback, *user_data)¶

Parameters:

playlist (TotemPlParser.Playlist) – a TotemPlParser.Playlist
dest (Gio.File) – output Gio.File
title (str) – the playlist title
type (TotemPlParser.ParserType) – a TotemPlParser.ParserType for the outputted playlist
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when saving has finished
user_data (object or None) – data to pass to the callback function

Starts asynchronous version of TotemPlParser.Parser.save(). For more details see TotemPlParser.Parser.save().

When the operation is finished, callback will be called. You can then call TotemPlParser.Parser.save_finish() to get the results of the operation.

save_finish(async_result)¶

Parameters:: async_result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True on success, False on failure.
Return type:: bool

Finishes an asynchronous playlist saving operation started with TotemPlParser.Parser.save_async().

If saving of the playlist is cancelled part-way through, Gio.IOErrorEnum.CANCELLED will be returned when this function is called.

do_entry_parsed(uri, metadata) virtual¶

Parameters:

uri (str) –
metadata ({object: object}) –

the generic signal handler for the TotemPlParser.Parser ::entry-parsed signal, which can be overridden by inheriting classes

do_playlist_ended(uri) virtual¶

Parameters:: uri (str) –

the generic signal handler for the TotemPlParser.Parser ::playlist-ended signal, which can be overridden by inheriting classes

do_playlist_started(uri, metadata) virtual¶

Parameters:

uri (str) –
metadata ({object: object}) –

the generic signal handler for the TotemPlParser.Parser ::playlist-started signal, which can be overridden by inheriting classes

Signal Details¶

TotemPlParser.Parser.signals.entry_parsed(parser, uri, metadata)¶

Signal Name:

entry-parsed

Flags:

RUN_LAST

Parameters:

parser (TotemPlParser.Parser) – The object which received the signal
uri (str) – the URI of the entry parsed
metadata ({str: str}) – a GLib.HashTable of metadata relating to the entry added

The ::entry-parsed signal is emitted when a new entry is parsed.

TotemPlParser.Parser.signals.playlist_ended(parser, uri)¶

Signal Name:

playlist-ended

Flags:

RUN_LAST

Parameters:

parser (TotemPlParser.Parser) – The object which received the signal
uri (str) – the URI of the playlist that finished parsing.

The ::playlist-ended signal is emitted when a playlist is finished parsing. It is only called when TotemPlParser.Parser ::playlist-started has been called for that playlist.

TotemPlParser.Parser.signals.playlist_started(parser, uri, metadata)¶

Signal Name:

playlist-started

Flags:

RUN_LAST

Parameters:

parser (TotemPlParser.Parser) – The object which received the signal
uri (str) – the URI of the new playlist started
metadata ({str: str}) – a GLib.HashTable of metadata relating to the playlist that started.

The ::playlist-started signal is emitted when a playlist parsing has started. This signal isn’t emitted for all types of playlists, but can be relied on to be called for playlists which support playlist metadata, such as title.

Property Details¶

TotemPlParser.Parser.props.debug¶

Name:: debug
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

If True, the parser will output debug information.

TotemPlParser.Parser.props.disable_unsafe¶

Name:: disable-unsafe
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

If True, the parser will not parse unsafe locations, such as local devices and local files if the playlist isn’t local. This is useful if the library is parsing a playlist from a remote location such as a website.

TotemPlParser.Parser.props.force¶

Name:: force
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

If True, the parser will attempt to parse a playlist, even if it appears to be unsupported (usually because of its filename extension).

TotemPlParser.Parser.props.recurse¶

Name:: recurse
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, CONSTRUCT

If True, the parser will recursively fetch playlists linked to by the current one.