openlyricsxml

The xml module provides the XML functionality.

The basic XML for storing the lyrics in the song database looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<song version="1.0">
    <lyrics>
        <verse type="c" label="1" lang="en">
            <![CDATA[Chorus optional split 1[---]Chorus optional split 2]]>
        </verse>
    </lyrics>
</song>

The XML of an OpenLyrics song looks like this:

<song xmlns="http://openlyrics.info/namespace/2009/song"
    version="0.7"
    createdIn="OpenLP 1.9.0"
    modifiedIn="ChangingSong 0.0.1"
    modifiedDate="2010-01-28T13:15:30+01:00">
<properties>
    <titles>
        <title>Amazing Grace</title>
    </titles>
</properties>
    <lyrics>
        <verse name="v1">
            <lines>
                <line>Amazing grace how sweet the sound</line>
            </lines>
        </verse>
    </lyrics>
</song>

class openlp.plugins.songs.lib.openlyricsxml.OpenLyrics(manager)

Bases: object

This class represents the converter for OpenLyrics XML (version 0.8) to/from a song.

As OpenLyrics has a rich set of different features, we cannot support them all. The following features are supported by the OpenLyrics class:

<authors>

OpenLP does not support the attribute lang.

<chord>

This property is fully supported.

<comments>

The <comments> property is fully supported. But comments in lyrics are not supported.

<copyright>

This property is fully supported.

<customVersion>

This property is not supported.

<key>

This property is not supported.

<format>

The custom formatting tags are fully supported.

<keywords>

This property is not supported.

<lines>

The attribute part is not supported. The break attribute is supported.

<publisher>

This property is not supported.

<songbooks>

As OpenLP does only support one songbook, we cannot consider more than one songbook.

<tempo>

This property is not supported.

<themes>

Topics, as they are called in OpenLP, are fully supported, whereby only the topic text (e. g. Grace) is considered, but neither the id nor lang.

<transposition>

This property is not supported.

<variant>

This property is not supported.

<verse name="v1a" lang="he" translit="en">

The attribute translit is not supported. Note, the attribute lang is considered, but there is not further functionality implemented yet. The following verse “types” are supported by OpenLP:

• v
• c
• b
• p
• i
• e
• o

The verse “types” stand for Verse, Chorus, Bridge, Pre-Chorus, Intro, Ending and Other. Any numeric value is allowed after the verse type. The complete verse name in OpenLP always consists of the verse type and the verse number. If not number is present 1 is assumed. OpenLP will merge verses which are split up by appending a letter to the verse name, such as v1a.

<verseOrder>

OpenLP supports this property.

END_TAGS_REGEX = re.compile('\\{\\/(\\w+)\\}')

IMPLEMENTED_VERSION = '0.8'

START_TAGS_REGEX = re.compile('\\{(\\w+)\\}')

VERSE_TAG_SPLITTER = re.compile('([a-zA-Z]+)([0-9]*)([a-zA-Z]?)')

song_to_xml(song)

Convert the song to OpenLyrics Format.

xml_to_song(xml, parse_and_temporary_save=False)

Create and save a song from OpenLyrics format xml to the database. Since we also export XML from external sources (e. g. OpenLyrics import), we cannot ensure, that it completely conforms to the OpenLyrics standard.

Parameters:

• xml – The XML to parse (unicode).
• parse_and_temporary_save – Switch to skip processing the whole song and storing the songs in the database with a temporary flag. Defaults to False.

exception openlp.plugins.songs.lib.openlyricsxml.OpenLyricsError(type, log_message, display_message)

Bases: Exception

LyricsError = 1

VerseError = 2

class openlp.plugins.songs.lib.openlyricsxml.SongXML

Bases: object

This class builds and parses the XML used to describe songs.

add_verse_to_lyrics(type, number, content, lang=None)

Add a verse to the <lyrics> tag.

Parameters:

• type – A string denoting the type of verse. Possible values are v, c, b, p, i, e and o. Any other type is not allowed, this also includes translated types.
• number – An integer denoting the number of the item, for example: verse 1.
• content – The actual text of the verse to be stored.
• lang – The verse’s language code (ISO-639). This is not required, but should be added if available.

dump_xml()

Debugging aid to dump XML so that we can see what we have.

extract_xml()

Extract our newly created XML song.

get_verses(xml)

Iterates through the verses in the XML and returns a list of verses and their attributes.

Parameters:xml – The XML of the song to be parsed.

The returned list has the following format:

[[{'type': 'v', 'label': '1'}, u"optional slide split 1[---]optional slide split 2"],
[{'lang': 'en', 'type': 'c', 'label': '1'}, u"English chorus"]]