raoul
/
openlp
forked from openlp/openlp
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Docstring cleanups

This commit is contained in:
Jonathan Springer 2015-09-08 15:13:59 -04:00
parent 46d4105cb1
commit eaf1e7a049
29 changed files with 153 additions and 141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
openlp/core/common/applocation.py
View File

@ -99,7 +99,7 @@ class AppLocation(object):
Get a list of files from the data files path.
:param section: Defaults to *None*. The section of code getting the files - used to load from a section's
data subdirectory.
data subdirectory.
:param extension:
Defaults to *None*. The extension to search for. For example::

6
openlp/core/common/settings.py
View File

@ -65,9 +65,9 @@ class Settings(QtCore.QSettings):
* Exposes all the methods of QSettings.
* Adds functionality for OpenLP Portable. If the ``defaultFormat`` is set to
``IniFormat``, and the path to the Ini file is set using ``set_filename``,
then the Settings constructor (without any arguments) will create a Settings
object for accessing settings stored in that Ini file.
``IniFormat``, and the path to the Ini file is set using ``set_filename``,
then the Settings constructor (without any arguments) will create a Settings
object for accessing settings stored in that Ini file.
``__default_settings__``
This dict contains all core settings with their default values.

10
openlp/core/lib/__init__.py
View File

@ -83,7 +83,7 @@ def get_text_file_string(text_file):
None.
:param text_file: The name of the file.
:return The file as a single string
:return: The file as a single string
"""
if not os.path.isfile(text_file):
return False
@ -108,7 +108,7 @@ def str_to_bool(string_value):
Convert a string version of a boolean into a real boolean.
:param string_value: The string value to examine and convert to a boolean type.
:return The correct boolean value
:return: The correct boolean value
"""
if isinstance(string_value, bool):
return string_value
@ -123,7 +123,7 @@ def build_icon(icon):
:param icon:
The icon to build. This can be a QIcon, a resource string in the form ``:/resource/file.png``, or a file
location like ``/path/to/file.png``. However, the **recommended** way is to specify a resource string.
:return The build icon.
:return: The build icon.
"""
button_icon = QtGui.QIcon()
if isinstance(icon, QtGui.QIcon):
@ -168,7 +168,7 @@ def create_thumb(image_path, thumb_path, return_icon=True, size=None):
:param return_icon: States if an icon should be build and returned from the thumb. Defaults to ``True``.
:param size: Allows to state a own size (QtCore.QSize) to use. Defaults to ``None``, which means that a default
height of 88 is used.
:return The final icon.
:return: The final icon.
"""
ext = os.path.splitext(thumb_path)[1].lower()
reader = QtGui.QImageReader(image_path)
@ -194,7 +194,7 @@ def validate_thumb(file_path, thumb_path):
:param file_path: The path to the file. The file **must** exist!
:param thumb_path: The path to the thumb.
:return True, False if the image has changed since the thumb was created.
:return: True, False if the image has changed since the thumb was created.
"""
if not os.path.exists(thumb_path):
return False

32
openlp/core/lib/formattingtags.py
View File

@ -164,29 +164,29 @@ class FormattingTags(object):
Add a list of tags to the list.
:param tags: The list with tags to add.
Each **tag** has to be a ``dict`` and should have the following keys:
Each **tag** has to be a ``dict`` and should have the following keys:
* desc
The formatting tag's description, e. g. **Red**
* desc
The formatting tag's description, e. g. **Red**
* start tag
The start tag, e. g. ``{r}``
* start tag
The start tag, e. g. ``{r}``
* end tag
The end tag, e. g. ``{/r}``
* end tag
The end tag, e. g. ``{/r}``
* start html
The start html tag. For instance ``<span style="-webkit-text-fill-color:red">``
* start html
The start html tag. For instance ``<span style="-webkit-text-fill-color:red">``
* end html
The end html tag. For example ``</span>``
* end html
The end html tag. For example ``</span>``
* protected
A boolean stating whether this is a build-in tag or not. Should be ``True`` in most cases.
* protected
A boolean stating whether this is a build-in tag or not. Should be ``True`` in most cases.
* temporary
A temporary tag will not be saved, but is also considered when displaying text containing the tag. It has
to be a ``boolean``.
* temporary
A temporary tag will not be saved, but is also considered when displaying text containing the tag. It has
to be a ``boolean``.
"""
FormattingTags.html_expands.extend(tags)

2
openlp/core/lib/projector/pjlink1.py
View File

@ -25,7 +25,9 @@
See PJLink Class 1 Specifications for details.
http://pjlink.jbmia.or.jp/english/dl.html
Section 5-1 PJLink Specifications
Section 5-5 Guidelines for Input Terminals
NOTE:

4
openlp/core/lib/renderer.py
View File

@ -89,9 +89,9 @@ class Renderer(OpenLPMixin, RegistryMixin, RegistryProperties):
:param theme_name: The current theme name.
:param old_theme_name: The old theme name. Has only to be passed, when the theme has been renamed.
Defaults to *None*.
Defaults to *None*.
:param only_delete: Only remove the given ``theme_name`` from the ``_theme_dimensions`` list. This can be
used when a theme is permanently deleted.
used when a theme is permanently deleted.
"""
if old_theme_name is not None and old_theme_name in self._theme_dimensions:
del self._theme_dimensions[old_theme_name]

4
openlp/core/lib/screen.py
View File

@ -142,7 +142,9 @@ class ScreenList(object):
"""
Add a screen to the list of known screens.
:param screen: A dict with the screen properties::
:param screen: A dict with the screen properties:
::
{
'primary': True,

12
openlp/core/lib/searchedit.py
View File

@ -114,17 +114,17 @@ class SearchEdit(QtGui.QLineEdit):
default.
:param items: The list of tuples to use. The tuples should contain an integer identifier, an icon (QIcon
instance or string) and a title for the item in the menu. In short, they should look like this::
instance or string) and a title for the item in the menu. In short, they should look like this::
(<identifier>, <icon>, <title>, <place holder text>)
(<identifier>, <icon>, <title>, <place holder text>)
For instance::
For instance::
(1, <QIcon instance>, "Titles", "Search Song Titles...")
(1, <QIcon instance>, "Titles", "Search Song Titles...")
Or::
Or::
(2, ":/songs/authors.png", "Authors", "Search Authors...")
(2, ":/songs/authors.png", "Authors", "Search Authors...")
"""
menu = QtGui.QMenu(self)
first = None

2
openlp/core/lib/serviceitem.py
View File

@ -388,7 +388,7 @@ class ServiceItem(RegistryProperties):
:param service_item: The item to extract data from.
:param path: Defaults to *None*. This is the service manager path for things which have their files saved
with them or None when the saved service is lite and the original file paths need to be preserved.
with them or None when the saved service is lite and the original file paths need to be preserved.
"""
log.debug('set_from_service called with path %s' % path)
header = service_item['serviceitem']['header']

4
openlp/core/lib/ui.py
View File

@ -66,9 +66,9 @@ def create_button_box(dialog, name, standard_buttons, custom_buttons=None):
:param dialog: The parent object. This has to be a ``QDialog`` descendant.
:param name: A string which is set as object name.
:param standard_buttons: A list of strings for the used buttons. It might contain: ``ok``, ``save``, ``cancel``,
``close``, and ``defaults``.
``close``, and ``defaults``.
:param custom_buttons: A list of additional buttons. If an item is an instance of QtGui.QAbstractButton it is added
with QDialogButtonBox.ActionRole. Otherwise the item has to be a tuple of a Button and a ButtonRole.
with QDialogButtonBox.ActionRole. Otherwise the item has to be a tuple of a Button and a ButtonRole.
"""
if custom_buttons is None:
custom_buttons = []

2
openlp/core/ui/maindisplay.py
View File

@ -320,7 +320,7 @@ class MainDisplay(OpenLPMixin, Display, RegistryProperties):
cache.
:param path: The path to the image to be displayed. **Note**, the path is only passed to identify the image.
If the image has changed it has to be re-added to the image manager.
If the image has changed it has to be re-added to the image manager.
"""
image = self.image_manager.get_image_bytes(path, ImageSource.ImagePlugin)
self.controller.media_controller.media_reset(self.controller)

46
openlp/core/ui/projector/sourceselectform.py
View File

@ -44,17 +44,19 @@ def source_group(inputs, source_text):
Return a dictionary where key is source[0] and values are inputs
grouped by source[0].
source_text = dict{"key1": "key1-text",
"key2": "key2-text",
...}
return:
dict{ key1[0]: { "key11": "key11-text",
"key12": "key12-text",
"key13": "key13-text",
... }
key2[0]: {"key21": "key21-text",
"key22": "key22-text",
... }
::
source_text = dict{"key1": "key1-text",
"key2": "key2-text",
...}
return:
dict{key1[0]: {"key11": "key11-text",
"key12": "key12-text",
"key13": "key13-text",
...}
key2[0]: {"key21": "key21-text",
"key22": "key22-text",
...}
:param inputs: List of inputs
:param source_text: Dictionary of {code: text} values to display
@ -81,16 +83,18 @@ def Build_Tab(group, source_key, default, projector, projectordb, edit=False):
Create the radio button page for a tab.
Dictionary will be a 1-key entry where key=tab to setup, val=list of inputs.
source_key: {"groupkey1": {"key11": "key11-text",
"key12": "key12-text",
...
},
"groupkey2": {"key21": "key21-text",
"key22": "key22-text",
....
},
...
}
::
source_key: {"groupkey1": {"key11": "key11-text",
"key12": "key12-text",
...
},
"groupkey2": {"key21": "key21-text",
"key22": "key22-text",
...
},
...
}
:param group: Button group widget to add buttons to
:param source_key: Dictionary of sources for radio buttons

2
openlp/core/ui/servicemanager.py
View File

@ -480,7 +480,7 @@ class ServiceManager(OpenLPMixin, RegistryMixin, QtGui.QWidget, Ui_ServiceManage
"""
Create the initial service array with the base items to be saved.
:return service array
:return: service array
"""
service = []
core = {'lite-service': self._save_lite,

10
openlp/core/ui/thememanager.py
View File

@ -503,7 +503,7 @@ class ThemeManager(OpenLPMixin, RegistryMixin, QtGui.QWidget, Ui_ThemeManager, R
Returns a theme object from an XML file
:param theme_name: Name of the theme to load from file
:return The theme object.
:return: The theme object.
"""
self.log_debug('get theme data for theme %s' % theme_name)
xml_file = os.path.join(self.path, str(theme_name), str(theme_name) + '.xml')
@ -519,7 +519,7 @@ class ThemeManager(OpenLPMixin, RegistryMixin, QtGui.QWidget, Ui_ThemeManager, R
Display a warning box to the user that a theme already exists
:param theme_name: Name of the theme.
:return Confirm if the theme is to be overwritten.
:return: Confirm if the theme is to be overwritten.
"""
ret = QtGui.QMessageBox.question(self, translate('OpenLP.ThemeManager', 'Theme Already Exists'),
translate('OpenLP.ThemeManager',
@ -607,7 +607,7 @@ class ThemeManager(OpenLPMixin, RegistryMixin, QtGui.QWidget, Ui_ThemeManager, R
Check if theme already exists and displays error message
:param theme_name: Name of the Theme to test
:return True or False if theme exists
:return: True or False if theme exists
"""
theme_dir = os.path.join(self.path, theme_name)
if os.path.exists(theme_dir):
@ -718,7 +718,7 @@ class ThemeManager(OpenLPMixin, RegistryMixin, QtGui.QWidget, Ui_ThemeManager, R
:param theme_xml: The Theme data object.
:param image_path: Where the theme image is stored
:return Theme data.
:return: Theme data.
"""
theme = ThemeXML()
theme.parse(theme_xml)
@ -734,7 +734,7 @@ class ThemeManager(OpenLPMixin, RegistryMixin, QtGui.QWidget, Ui_ThemeManager, R
:param confirm_text: Confirm message text to be displayed.
:param test_plugin: Do we check the plugins for theme usage.
:param confirm: Do we display a confirm box before run checks.
:return True or False depending on the validity.
:return: True or False depending on the validity.
"""
self.global_theme = Settings().value(self.settings_section + '/global theme')
if check_item_selected(self.theme_list_widget, select_text):

6
openlp/core/utils/actions.py
View File

@ -238,10 +238,10 @@ class ActionList(object):
:param action: The action to add (QAction). **Note**, the action must not have an empty ``objectName``.
:param category: The category this action belongs to. The category has to be a python string. . **Note**,
if the category is ``None``, the category and its actions are being hidden in the shortcut dialog. However,
if they are added, it is possible to avoid assigning shortcuts twice, which is important.
if the category is ``None``, the category and its actions are being hidden in the shortcut dialog. However,
if they are added, it is possible to avoid assigning shortcuts twice, which is important.
:param weight: The weight specifies how important a category is. However, this only has an impact on the order
the categories are displayed.
the categories are displayed.
"""
if category not in self.categories:
self.categories.append(category)

2
openlp/plugins/bibles/lib/http.py
View File

@ -743,7 +743,7 @@ def get_soup_for_bible_ref(reference_url, header=None, pre_parse_regex=None, pre
:param reference_url: The URL to obtain the soup from.
:param header: An optional HTTP header to pass to the bible web server.
:param pre_parse_regex: A regular expression to run on the webpage. Allows manipulation of the webpage before
passing to BeautifulSoup for parsing.
passing to BeautifulSoup for parsing.
:param pre_parse_substitute: The text to replace any matches to the regular expression with.
"""
if not reference_url:

2
openlp/plugins/custom/lib/customxmlhandler.py
View File

@ -84,7 +84,7 @@ class CustomXMLBuilder(object):
Add a verse to the ``<lyrics>`` tag.
:param verse_type: A string denoting the type of verse. Possible values are "Chorus", "Verse", "Bridge",
and "Custom".
and "Custom".
:param number: An integer denoting the number of the item, for example: verse 1.
:param content: The actual text of the verse to be stored.

2
openlp/plugins/images/forms/addgroupform.py
View File

@ -44,7 +44,7 @@ class AddGroupForm(QtGui.QDialog, Ui_AddGroupDialog):
:param clear: Set to False if the text input box should not be cleared when showing the dialog (default: True).
:param show_top_level_group: Set to True when "-- Top level group --" should be showed as first item
(default: False).
(default: False).
:param selected_group: The ID of the group that should be selected by default when showing the dialog.
"""
if clear:

26
openlp/plugins/images/lib/db.py
View File

@ -48,24 +48,24 @@ def init_schema(url):
Setup the images database connection and initialise the database schema.
:param url: The database to setup
The images database contains the following tables:
The images database contains the following tables:
* image_groups
* image_filenames
* image_groups
* image_filenames
**image_groups Table**
This table holds the names of the images groups. It has the following columns:
**image_groups Table**
This table holds the names of the images groups. It has the following columns:
* id
* parent_id
* group_name
* id
* parent_id
* group_name
**image_filenames Table**
This table holds the filenames of the images and the group they belong to. It has the following columns:
**image_filenames Table**
This table holds the filenames of the images and the group they belong to. It has the following columns:
* id
* group_id
* filename
* id
* group_id
* filename
"""
session, metadata = init_db(url)

6
openlp/plugins/images/lib/mediaitem.py
View File

@ -285,7 +285,7 @@ class ImageMediaItem(MediaManagerItem):
:param combobox: The QComboBox to add the options to.
:param parent_group_id: The ID of the group that will be added.
:param prefix: A string containing the prefix that will be added in front of the groupname for each level of
the tree.
the tree.
"""
if parent_group_id == 0:
combobox.clear()
@ -333,7 +333,7 @@ class ImageMediaItem(MediaManagerItem):
:param images: A List of Image Filenames objects that will be used to reload the mediamanager list.
:param initial_load: When set to False, the busy cursor and progressbar will be shown while loading images.
:param open_group: ImageGroups object of the group that must be expanded after reloading the list in the
interface.
interface.
"""
if not initial_load:
self.application.set_busy_cursor()
@ -469,7 +469,7 @@ class ImageMediaItem(MediaManagerItem):
:param images_list: A List of strings containing image filenames
:param group_id: The ID of the group to save the images in
:param reload_list: This boolean is set to True when the list in the interface should be reloaded after saving
the new images
the new images
"""
for filename in images_list:
if not isinstance(filename, str):

1
openlp/plugins/songs/forms/songimportform.py
View File

@ -228,6 +228,7 @@ class SongImportForm(OpenLPWizard, RegistryProperties):
:param listbox: A listbox (QListWidget).
:param filters: The file extension filters. It should contain the file descriptions as well as the file
extensions. For example::
'SongBeamer Files (*.sng)'
"""
if filters:

1
openlp/plugins/songs/lib/db.py
View File

@ -173,6 +173,7 @@ def init_schema(url):
Setup the songs database connection and initialise the database schema.
:param url: The database to setup
The song database contains the following tables:
* authors

2
openlp/plugins/songs/lib/importers/easyslides.py
View File

@ -36,7 +36,7 @@ class EasySlidesImport(SongImport):
Import songs exported from EasySlides
The format example is here:
http://wiki.openlp.org/Development:EasySlides_-_Song_Data_Format
http://wiki.openlp.org/Development:EasySlides\_-_Song_Data_Format
"""
def __init__(self, manager, **kwargs):
"""

2
openlp/plugins/songs/lib/importers/powersong.py
View File

@ -71,7 +71,7 @@ class PowerSongImport(SongImport):
"""
Checks if source is a PowerSong 1.0 folder:
* is a directory
* contains at least one *.song file
* contains at least one \*.song file
"""
if os.path.isdir(import_source):
for file in os.listdir(import_source):

2
openlp/plugins/songs/lib/importers/songimport.py
View File

@ -105,7 +105,7 @@ class SongImport(QtCore.QObject):
This should be called, when a song could not be imported.
:param file_path: This should be the file path if ``self.import_source`` is a list with different files. If it
is not a list, but a single file (for instance a database), then this should be the song's title.
is not a list, but a single file (for instance a database), then this should be the song's title.
:param reason: The reason why the import failed. The string should be as informative as possible.
"""
self.set_defaults()

48
openlp/plugins/songs/lib/importers/songpro.py
View File

@ -36,30 +36,30 @@ class SongProImport(SongImport):
**SongPro Song File Format:**
SongPro has the option to export under its File menu
This produces files containing single or multiple songs
The file is text with lines tagged with # followed by an identifier.
This is documented here: http://creationsoftware.com/ImportIdentifiers.php
An example here: http://creationsoftware.com/ExampleImportingManySongs.txt
#A - next line is the Song Author
#B - the lines following until next tagged line are the "Bridge" words
(can be in rtf or plain text) which we map as B1
#C - the lines following until next tagged line are the chorus words
(can be in rtf or plain text)
which we map as C1
#D - the lines following until next tagged line are the "Ending" words
(can be in rtf or plain text) which we map as E1
#E - this song ends here, so we process the song -
and start again at the next line
#G - next line is the Group
#M - next line is the Song Number
#N - next line are Notes
#R - next line is the SongCopyright
#O - next line is the Verse Sequence
#T - next line is the Song Title
#1 - #7 the lines following until next tagged line are the verse x words
(can be in rtf or plain text)
| SongPro has the option to export under its File menu
| This produces files containing single or multiple songs
| The file is text with lines tagged with # followed by an identifier.
| This is documented here: http://creationsoftware.com/ImportIdentifiers.php
| An example here: http://creationsoftware.com/ExampleImportingManySongs.txt
|
| #A - next line is the Song Author
| #B - the lines following until next tagged line are the "Bridge" words
| (can be in rtf or plain text) which we map as B1
| #C - the lines following until next tagged line are the chorus words
| (can be in rtf or plain text)
| which we map as C1
| #D - the lines following until next tagged line are the "Ending" words
| (can be in rtf or plain text) which we map as E1
| #E - this song ends here, so we process the song -
| and start again at the next line
| #G - next line is the Group
| #M - next line is the Song Number
| #N - next line are Notes
| #R - next line is the SongCopyright
| #O - next line is the Verse Sequence
| #T - next line is the Song Title
| #1 - #7 the lines following until next tagged line are the verse x words
| (can be in rtf or plain text)
"""
def __init__(self, manager, **kwargs):
"""

24
openlp/plugins/songs/lib/importers/songshowplus.py
View File

@ -60,22 +60,22 @@ class SongShowPlusImport(SongImport):
* Each piece of data in the song file has some information that precedes it.
* The general format of this data is as follows:
4 Bytes, forming a 32 bit number, a key if you will, this describes what the data is (see blockKey below)
4 Bytes, forming a 32 bit number, which is the number of bytes until the next block starts
1 Byte, which tells how many bytes follows
1 or 4 Bytes, describes how long the string is, if its 1 byte, the string is less than 255
The next bytes are the actual data.
The next block of data follows on.
| 4 Bytes, forming a 32 bit number, a key if you will, this describes what the data is (see blockKey below)
| 4 Bytes, forming a 32 bit number, which is the number of bytes until the next block starts
| 1 Byte, which tells how many bytes follows
| 1 or 4 Bytes, describes how long the string is, if its 1 byte, the string is less than 255
| The next bytes are the actual data.
| The next block of data follows on.
This description does differ for verses. Which includes extra bytes stating the verse type or number. In some cases
a "custom" verse is used, in that case, this block will in include 2 strings, with the associated string length
descriptors. The first string is the name of the verse, the second is the verse content.
This description does differ for verses. Which includes extra bytes stating the verse type or number. In some
cases a "custom" verse is used, in that case, this block will in include 2 strings, with the associated string
length descriptors. The first string is the name of the verse, the second is the verse content.
The file is ended with four null bytes.
The file is ended with four null bytes.
Valid extensions for a SongShow Plus song file are:
Valid extensions for a SongShow Plus song file are:
* .sbsong
* .sbsong
"""
other_count = 0

5
openlp/plugins/songs/lib/openlyricsxml.py
View File

@ -91,7 +91,7 @@ class SongXML(object):
Add a verse to the ``<lyrics>`` tag.
:param 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.
Any other type is **not** allowed, this also includes translated types.
:param number: An integer denoting the number of the item, for example: verse 1.
:param content: The actual text of the verse to be stored.
:param lang: The verse's language code (ISO-639). This is not required, but should be added if available.
@ -113,6 +113,7 @@ class SongXML(object):
Iterates through the verses in the XML and returns a list of verses and their attributes.
:param 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"],
@ -371,7 +372,7 @@ class OpenLyrics(object):
:param xml: The XML to parse (unicode).
:param 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``.
with a temporary flag. Defaults to ``False``.
"""
# No xml get out of here.
if not xml:

27
openlp/plugins/songs/lib/songcompare.py
View File

@ -21,20 +21,21 @@
###############################################################################
"""
The :mod:`songcompare` module provides functionality to search for
duplicate songs. It has one single :function:`songs_probably_equal`.
duplicate songs. It has one single :func:`songs_probably_equal`.
The algorithm is based on the diff algorithm.
First a diffset is calculated for two songs.
To compensate for typos all differences that are smaller than a
limit (<max_typo_size) and are surrounded by larger equal blocks
(>min_fragment_size) are removed and the surrounding equal parts are merged.
Finally two conditions can qualify a song tuple to be a duplicate:
1. There is a block of equal content that is at least min_block_size large.
This condition should hit for all larger songs that have a long enough
equal part. Even if only one verse is equal this condition should still hit.
2. Two thirds of the smaller song is contained in the larger song.
This condition should hit if one of the two songs (or both) is small (smaller
than the min_block_size), but most of the song is contained in the other song.
| The algorithm is based on the diff algorithm.
| First a diffset is calculated for two songs.
| To compensate for typos all differences that are smaller than a
limit (<max_typo_size) and are surrounded by larger equal blocks
(>min_fragment_size) are removed and the surrounding equal parts are merged.
| Finally two conditions can qualify a song tuple to be a duplicate:
1. There is a block of equal content that is at least min_block_size large.
This condition should hit for all larger songs that have a long enough
equal part. Even if only one verse is equal this condition should still hit.
2. Two thirds of the smaller song is contained in the larger song.
This condition should hit if one of the two songs (or both) is small (smaller
than the min_block_size), but most of the song is contained in the other song.
"""
import difflib