Add DocStrings

This commit is contained in:
Jon Tibble 2010-06-10 02:57:59 +01:00
parent 5bd60d1fd4
commit 8d059fb84e
13 changed files with 180 additions and 57 deletions

View File

@ -22,3 +22,6 @@
# with this program; if not, write to the Free Software Foundation, Inc., 59 #
# Temple Place, Suite 330, Boston, MA 02111-1307 USA #
###############################################################################
"""
The :mod:`lib` module contains all the project produced OpenLP functionality
"""

View File

@ -22,3 +22,9 @@
# with this program; if not, write to the Free Software Foundation, Inc., 59 #
# Temple Place, Suite 330, Boston, MA 02111-1307 USA #
###############################################################################
"""
The :mod:`lib` module provides all core application functions
All the core functions of the OpenLP application including the GUI, settings,
logging and a plugin framework are contained within the openlp.core module.
"""

View File

@ -310,8 +310,7 @@ class MediaManagerItem(QtGui.QWidget):
def initialise(self):
"""
Implement this method in your descendent media manager item to
do any UI or other initialisation. This method is called
automatically.
do any UI or other initialisation. This method is called automatically.
"""
pass
@ -352,8 +351,7 @@ class MediaManagerItem(QtGui.QWidget):
def validate(self, file, thumb):
"""
Validates to see if the file still exists or
thumbnail is up to date
Validates to see if the file still exists or thumbnail is up to date
"""
if os.path.exists(file):
filedate = os.stat(file).st_mtime

View File

@ -22,7 +22,9 @@
# with this program; if not, write to the Free Software Foundation, Inc., 59 #
# Temple Place, Suite 330, Boston, MA 02111-1307 USA #
###############################################################################
"""
Provide plugin management
"""
import os
import sys
import logging

View File

@ -22,7 +22,12 @@
# with this program; if not, write to the Free Software Foundation, Inc., 59 #
# Temple Place, Suite 330, Boston, MA 02111-1307 USA #
###############################################################################
"""
OpenLP version 1 theme handling
Provides reference data, a default v1 XML theme and class wrapper for
processing version 1 themes in OpenLP version 2.
"""
import types
from xml.etree.ElementTree import ElementTree, XML
@ -56,9 +61,10 @@ BLANK_STYLE_XML = \
'''
class Theme(object):
def __init__(self, xml):
""" stores the info about a theme
attributes:
"""
Provide a class wrapper storing data from an XML theme
Attributes:
name : theme name
BackgroundMode : 1 - Transparent
@ -96,11 +102,18 @@ class Theme(object):
WrapStyle : 0 - normal
1 - lyrics
"""
def __init__(self, xml):
"""
Initialise a theme with data from xml
"""
# init to defaults
self._set_from_XML(BLANK_STYLE_XML)
self._set_from_XML(xml)
def _get_as_string(self):
"""
Return single line string representation of a theme
"""
theme_strings = []
keys = dir(self)
keys.sort()
@ -110,6 +123,9 @@ class Theme(object):
return u''.join(theme_strings)
def _set_from_XML(self, xml):
"""
Set theme class attributes with data from XML
"""
root = ElementTree(element=XML(xml))
iter = root.getiterator()
for element in iter:
@ -149,8 +165,12 @@ class Theme(object):
setattr(self, element.tag, val)
def __str__(self):
"""
Provide Python string representation for the class (multiline output)
"""
theme_strings = []
for key in dir(self):
if key[0:1] != u'_':
theme_strings.append(u'%30s : %s' % (key, getattr(self, key)))
return u'\n'.join(theme_strings)

View File

@ -29,16 +29,19 @@ from openlp.core.lib import SettingsTab, Receiver, translate
class DisplayTab(SettingsTab):
"""
Class documentation goes here.
Provide the UI for managing display related settings
"""
def __init__(self, screens):
"""
Constructor
Initialise the display tab from a SettingsTab
"""
self.screens = screens
SettingsTab.__init__(self, u'Display')
def setupUi(self):
"""
Set up the UI widgets to show the settings
"""
self.tabTitleVisible = translate(u'DisplayTab', u'Displays')
self.layoutWidget = QtGui.QWidget(self)
self.layoutWidget.setGeometry(QtCore.QRect(0, 40, 241, 79))
@ -158,6 +161,9 @@ class DisplayTab(SettingsTab):
QtCore.SIGNAL(u'stateChanged(int)'), self.onOverrideCheckBoxChanged)
def retranslateUi(self):
"""
Provide i18n support for this UI
"""
self.setWindowTitle(translate(u'DisplayTab', u'Amend Display Settings'))
self.CurrentGroupBox.setTitle(
translate(u'DisplayTab', u'Default Settings'))
@ -179,6 +185,9 @@ class DisplayTab(SettingsTab):
translate(u'DisplayTab', u'Override Output Display'))
def load(self):
"""
Load current display settings
"""
settings = QtCore.QSettings()
settings.beginGroup(self.settingsSection)
self.Xpos.setText(unicode(self.screens.current[u'size'].x()))
@ -209,6 +218,9 @@ class DisplayTab(SettingsTab):
self.amend_display = True
def save(self):
"""
Save chosen settings
"""
settings = QtCore.QSettings()
settings.beginGroup(self.settingsSection)
settings.setValue('x position', QtCore.QVariant(self.XposEdit.text()))

View File

@ -38,7 +38,9 @@ from openlp.core.ui import ServiceNoteForm, ServiceItemEditForm
from openlp.core.utils import AppLocation
class ServiceManagerList(QtGui.QTreeWidget):
"""
Set up key bindings and mouse behaviour for the service list
"""
def __init__(self, parent=None, name=None):
QtGui.QTreeWidget.__init__(self, parent)
self.parent = parent

View File

@ -121,6 +121,10 @@ class ThemeManager(QtGui.QWidget):
QtCore.QVariant(u'')).toString())
def changeGlobalFromTab(self, themeName):
"""
Change the global theme when it is changed through the Themes settings
tab
"""
log.debug(u'changeGlobalFromTab %s', themeName)
for count in range (0, self.ThemeListWidget.count()):
#reset the old name
@ -136,6 +140,10 @@ class ThemeManager(QtGui.QWidget):
self.ThemeListWidget.item(count).setText(name)
def changeGlobalFromScreen(self, index = -1):
"""
Change the global theme when a theme is double clicked upon in the
Theme Manager list
"""
log.debug(u'changeGlobalFromScreen %s', index)
selected_row = self.ThemeListWidget.currentRow()
for count in range (0, self.ThemeListWidget.count()):
@ -159,12 +167,24 @@ class ThemeManager(QtGui.QWidget):
self.pushThemes()
def onAddTheme(self):
"""
Add a new theme
Loads a new theme with the default settings and then launches the theme
editing form for the user to make their customisations.
"""
theme = self.createThemeFromXml(self.baseTheme(), self.path)
self.amendThemeForm.loadTheme(theme)
self.saveThemeName = u''
self.amendThemeForm.exec_()
def onEditTheme(self):
"""
Edit a theme
Loads the settings for the theme that is to be edited and launches the
theme editing form so the user can make their changes.
"""
item = self.ThemeListWidget.currentItem()
if item:
theme = self.getThemeData(
@ -175,6 +195,9 @@ class ThemeManager(QtGui.QWidget):
self.amendThemeForm.exec_()
def onDeleteTheme(self):
"""
Delete a theme
"""
self.global_theme = unicode(QtCore.QSettings().value(
self.settingsSection + u'/global theme',
QtCore.QVariant(u'')).toString())
@ -255,6 +278,13 @@ class ThemeManager(QtGui.QWidget):
zip.close()
def onImportTheme(self):
"""
Import a theme
Opens a file dialog to select the theme file(s) to import before
attempting to extract OpenLP themes from those files. This process
will load both OpenLP version 1 and version 2 themes.
"""
files = QtGui.QFileDialog.getOpenFileNames(
self, translate(u'ThemeManager', u'Select Theme Import File'),
SettingsManager.get_last_dir(self.settingsSection), u'Theme (*.*)')
@ -304,12 +334,24 @@ class ThemeManager(QtGui.QWidget):
self.pushThemes()
def pushThemes(self):
"""
Notify listeners that the theme list has been updated
"""
Receiver.send_message(u'theme_update_list', self.getThemes())
def getThemes(self):
"""
Return the list of loaded themes
"""
return self.themelist
def getThemeData(self, themename):
"""
Returns a theme object from an XML file
``themename``
Name of the theme to load from file
"""
log.debug(u'getthemedata for theme %s', themename)
xml_file = os.path.join(self.path, unicode(themename),
unicode(themename) + u'.xml')
@ -319,6 +361,12 @@ class ThemeManager(QtGui.QWidget):
return self.createThemeFromXml(xml, self.path)
def checkThemesExists(self, dir):
"""
Check a theme directory exists and if not create it
``dir``
Theme directory to make sure exists
"""
log.debug(u'check themes')
if not os.path.exists(dir):
os.mkdir(dir)
@ -382,7 +430,10 @@ class ThemeManager(QtGui.QWidget):
def checkVersion1(self, xmlfile):
"""
Am I a version 1 theme
Check if a theme is from OpenLP version 1
``xmlfile``
Theme XML to check the version of
"""
log.debug(u'checkVersion1 ')
theme = xmlfile
@ -394,9 +445,13 @@ class ThemeManager(QtGui.QWidget):
def migrateVersion122(self, filename, fullpath, xml_data):
"""
Called by convert the xml data from version 1 format
to the current format.
New fields are defaulted but the new theme is useable
Convert the xml data from version 1 format to the current format.
New fields are loaded with defaults to provide a complete, working
theme containing all compatible customisations from the old theme.
``xml_data``
Version 1 theme to convert
"""
log.debug(u'migrateVersion122 %s %s', filename, fullpath)
theme = Theme(xml_data)

View File

@ -22,3 +22,6 @@
# with this program; if not, write to the Free Software Foundation, Inc., 59 #
# Temple Place, Suite 330, Boston, MA 02111-1307 USA #
###############################################################################
"""
The :mod:`lib` module provides all the project produced plugins
"""

View File

@ -32,11 +32,11 @@ from alertdialog import Ui_AlertDialog
class AlertForm(QtGui.QDialog, Ui_AlertDialog):
"""
Class documentation goes here.
Provide UI for the alert system
"""
def __init__(self, manager, parent):
"""
Constructor
Initialise the alert form
"""
self.manager = manager
self.parent = parent
@ -103,6 +103,9 @@ class AlertForm(QtGui.QDialog, Ui_AlertDialog):
self.loadList()
def onSaveClick(self):
"""
Save an alert
"""
if self.item_id:
alert = self.manager.get_alert(self.item_id)
alert.text = unicode(self.AlertTextEdit.text())
@ -113,7 +116,9 @@ class AlertForm(QtGui.QDialog, Ui_AlertDialog):
self.onNewClick()
def onTextChanged(self):
#Data has changed by editing it so potential storage required
"""
Enable save button when data has been changed by editing the form
"""
self.SaveButton.setEnabled(True)
def onDoubleClick(self):

View File

@ -372,8 +372,7 @@ class ImpressDocument(PresentationDocument):
def get_slide_preview_file(self, slide_no):
"""
Returns an image path containing a preview for the
requested slide
Returns an image path containing a preview for the requested slide
``slide_no``
The slide an image is required for, starting at 1

View File

@ -26,6 +26,12 @@
from openlp.core.lib import translate
class VerseType(object):
"""
Provide a type definition for verses
VerseType provides the type definition for the tags that may be associated
with verses in songs.
"""
Verse = 0
Chorus = 1
Bridge = 2
@ -36,6 +42,12 @@ class VerseType(object):
@staticmethod
def to_string(verse_type):
"""
Return a string for a given VerseType
``verse_type``
The type to return a string for
"""
if verse_type == VerseType.Verse:
return translate(u'VerseType', u'Verse')
elif verse_type == VerseType.Chorus:
@ -53,6 +65,12 @@ class VerseType(object):
@staticmethod
def from_string(verse_type):
"""
Return the VerseType for a given string
``verse_type``
The string to return a VerseType for
"""
verse_type = verse_type.lower()
if verse_type == unicode(VerseType.to_string(VerseType.Verse)).lower():
return VerseType.Verse