Commit 94a9a033 authored by Alexandru Băluț's avatar Alexandru Băluț

Update docstrings style

Should be Google's Python style now.

Differential Revision: https://phabricator.freedesktop.org/D1079
parent 4ea4a7d8
......@@ -255,7 +255,7 @@
<object class="GtkComboBoxText" id="halignment">
<property name="visible">True</property>
<property name="can_focus">False</property>
<signal name="changed" handler="_updateSource" swapped="no"/>
<signal name="changed" handler="_update_source_cb" swapped="no"/>
</object>
<packing>
<property name="left_attach">1</property>
......@@ -267,7 +267,7 @@
<property name="visible">True</property>
<property name="can_focus">False</property>
<property name="active">1</property>
<signal name="changed" handler="_updateSource" swapped="no"/>
<signal name="changed" handler="_update_source_cb" swapped="no"/>
</object>
<packing>
<property name="left_attach">1</property>
......@@ -282,7 +282,7 @@
<property name="adjustment">position_x_adj</property>
<property name="digits">2</property>
<property name="numeric">True</property>
<signal name="value-changed" handler="_updateSource" swapped="no"/>
<signal name="value-changed" handler="_update_source_cb" swapped="no"/>
</object>
<packing>
<property name="left_attach">2</property>
......@@ -297,7 +297,7 @@
<property name="adjustment">position_y_adj</property>
<property name="digits">2</property>
<property name="numeric">True</property>
<signal name="value-changed" handler="_updateSource" swapped="no"/>
<signal name="value-changed" handler="_update_source_cb" swapped="no"/>
</object>
<packing>
<property name="left_attach">2</property>
......
"""
Main Pitivi package
"""
......@@ -53,9 +53,7 @@ from pitivi.utils.timeline import Zoomable
class Pitivi(Gtk.Application, Loggable):
"""
Pitivi's application.
"""Pitivi's application.
Attributes:
action_log (UndoableActionLog): The undo/redo log for the current project.
......@@ -227,11 +225,10 @@ class Pitivi(Gtk.Application, Loggable):
return True
def shutdown(self):
"""
Close Pitivi.
"""Closes the app.
@return: C{True} if Pitivi was successfully closed, else C{False}.
@rtype: C{bool}
Returns:
bool: True if successful, False otherwise.
"""
self.debug("shutting down")
# Refuse to close if we are not done with the current project.
......@@ -298,9 +295,7 @@ class Pitivi(Gtk.Application, Loggable):
self._scenario_file = None
def _checkVersion(self):
"""
Check online for release versions information.
"""
"""Checks online for new versions of the app."""
self.info("Requesting version information async")
giofile = Gio.File.new_for_uri(RELEASES_URL)
giofile.load_contents_async(None, self._versionInfoReceivedCb, None)
......@@ -344,16 +339,12 @@ class Pitivi(Gtk.Application, Loggable):
self.warning("Version info could not be read: %s", e)
def isLatest(self):
"""
Whether the app's version is the latest as far as we know.
"""
"""Whether the app's version is the latest as far as we know."""
status = self._version_information.get("status")
return status is None or status.upper() == "CURRENT"
def getLatest(self):
"""
Get the latest version of the app or None.
"""
"""Get the latest version of the app or None."""
return self._version_information.get("current")
def _quitCb(self, unused_action, unused_param):
......
......@@ -17,14 +17,11 @@
# Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
# Boston, MA 02110-1301, USA.
# TODO reimplement after GES port
"""
Classes for automatic alignment of L{Clip}s
"""
"""Automatic alignment of `Clip`s."""
import array
import os
import time
from gi.repository import GObject
from gi.repository import Gst
from gi.repository import Gtk
......
......@@ -16,15 +16,10 @@
# License along with this program; if not, write to the
# Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
# Boston, MA 02110-1301, USA.
"""
This file is run by bin/pitivi on startup. Its purpose is to ensure that all
the important dependencies for running the pitivi UI can be imported and satisfy
our version number requirements.
"""Logic for ensuring important dependencies satisfy minimum requirements.
The checks here are supposed to take a negligible amount of time (< 0.2 seconds)
and not impact startup. Module imports have no impact (they get imported later
by the app anyway). For more complex checks, you can measure (with time.time()),
when called from application.py instead of bin/pitivi, if it has an impact.
and not impact startup.
Package maintainers should look at the bottom section of this file.
"""
......@@ -45,14 +40,14 @@ def _string_to_list(version):
class Dependency(object):
"""
This abstract class represents a module or component requirement.
@param modulename: The string allowing for import or lookup of the component.
@param version_required_string: A string in the format X.Y.Z or None if no version
check is necessary.
@param additional_message: A string that will be displayed to the user to further
explain the purpose of the missing component.
"""Represents a module or component requirement.
Args:
modulename (str): The name identifying the component.
version_required_string (Optional[str]): The minimum required version,
if any, formatted like "X.Y.Z".
additional_message (Optional[str]): Message displayed to the user to
further explain the purpose of the missing component.
"""
def __init__(self, modulename, version_required_string=None, additional_message=None):
......@@ -64,8 +59,9 @@ class Dependency(object):
self.additional_message = additional_message
def check(self):
"""
Sets the satisfied flag to True or False.
"""Checks whether the dependency is satisfied.
Sets the `satisfied` field to True or False.
"""
self.component = self._try_importing_component()
......@@ -81,18 +77,23 @@ class Dependency(object):
self.satisfied = True
def _try_importing_component(self):
"""
Subclasses must implement that method to return an object
on which version will be inspectable.
Return None on failure to import.
"""Performs the check.
Returns:
The dependent component.
"""
raise NotImplementedError
def _format_version(self, module):
"""
Subclasses must return the version number split
in an iterable of ints.
For example "1.2.10" should return [1, 2, 10]
"""Formats the version of the component.
Args:
module: The component returned by _try_importing_component.
Returns:
List[int]: The version number of the component.
For example "1.2.10" should return [1, 2, 10].
"""
raise NotImplementedError
......@@ -151,11 +152,6 @@ class ClassicDependency(Dependency):
class GstPluginDependency(Dependency):
"""
Don't call check on its instances before actually checking
Gst is importable.
"""
def _try_importing_component(self):
try:
from gi.repository import Gst
......@@ -253,6 +249,7 @@ class GICheck(ClassicDependency):
def check_requirements():
"""Checks Pitivi's dependencies are satisfied."""
hard_dependencies_satisfied = True
for dependency in HARD_DEPENDENCIES:
......@@ -307,8 +304,7 @@ def require_version(modulename, version):
def initialize_modules():
"""
Initialize the modules.
"""Initializes the modules.
This has to be done in a specific order otherwise the app
crashes on some systems.
......@@ -380,13 +376,11 @@ HARD_DEPENDENCIES = [GICheck("3.14.0"),
ClassicDependency("matplotlib"),
]
SOFT_DEPENDENCIES = \
(
ClassicDependency("pycanberra", None, _("enables sound notifications when rendering is complete")),
GIDependency("GnomeDesktop", "3.0", None, _("file thumbnails provided by GNOME's thumbnailers")),
GIDependency("Notify", "0.7", None, _("enables visual notifications when rendering is complete")),
GstPluginDependency("libav", None, _("additional multimedia codecs through the GStreamer Libav library")),
GstPluginDependency("debugutilsbad", None, _("enables a watchdog in the GStreamer pipeline."
" Use to detect errors happening in GStreamer"
" and recover from them")),
)
SOFT_DEPENDENCIES = (
ClassicDependency("pycanberra", None, _("enables sound notifications when rendering is complete")),
GIDependency("GnomeDesktop", "3.0", None, _("file thumbnails provided by GNOME's thumbnailers")),
GIDependency("Notify", "0.7", None, _("enables visual notifications when rendering is complete")),
GstPluginDependency("libav", None, _("additional multimedia codecs through the GStreamer Libav library")),
GstPluginDependency("debugutilsbad", None, _("enables a watchdog in the GStreamer pipeline."
" Use to detect errors happening in GStreamer"
" and recover from them")))
......@@ -16,9 +16,7 @@
# License along with this program; if not, write to the
# Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
# Boston, MA 02110-1301, USA.
"""
Widgets to control clips properties
"""
"""Widgets to control clips properties."""
import os
from gettext import gettext as _
......@@ -50,15 +48,14 @@ from pitivi.utils.ui import SPACING
class ClipPropertiesError(Exception):
"""Base Exception for errors happening in L{ClipProperties}s or L{EffectProperties}s"""
pass
class ClipProperties(Gtk.ScrolledWindow, Loggable):
"""
Widget for configuring the selected clip.
"""Widget for configuring the selected clip.
@type app: L{Pitivi}
Attributes:
app (Pitivi): The app.
"""
def __init__(self, app):
......@@ -91,9 +88,7 @@ class ClipProperties(Gtk.ScrolledWindow, Loggable):
vbox.pack_start(self.effect_expander, False, False, 0)
def createInfoBar(self, text):
"""
Create an infobar that is added at the beginning of the window
"""
"""Creates an infobar to be displayed at the top."""
label = Gtk.Label(label=text)
label.set_line_wrap(True)
infobar = Gtk.InfoBar()
......@@ -105,11 +100,10 @@ class ClipProperties(Gtk.ScrolledWindow, Loggable):
# pylint: disable=too-many-instance-attributes
class EffectProperties(Gtk.Expander, Loggable):
"""
Widget for viewing a list of effects and configuring them.
"""Widget for viewing a list of effects and configuring them.
@type app: C{Pitivi}
@type effects_properties_manager: C{EffectsPropertiesManager}
Attributes:
app (Pitivi): The app.
"""
# pylint: disable=too-many-statements
......@@ -148,14 +142,12 @@ class EffectProperties(Gtk.Expander, Loggable):
# We need to specify Gtk.TreeDragSource because otherwise we are hitting
# bug https://bugzilla.gnome.org/show_bug.cgi?id=730740.
class EffectsListStore(Gtk.ListStore, Gtk.TreeDragSource):
"""
Just a work around!
"""
"""Just a work around!"""
# pylint: disable=non-parent-init-called
def __init__(self, *args):
Gtk.ListStore.__init__(self, *args)
# Simply set the source index on the storemodrel directly
# to avoid issues with the selection_data API
# Set the source index on the storemodel directly,
# to avoid issues with the selection_data API.
# FIXME: Work around
# https://bugzilla.gnome.org/show_bug.cgi?id=737587
self.source_index = None
......@@ -336,12 +328,11 @@ class EffectProperties(Gtk.Expander, Loggable):
break
def addEffectToCurrentSelection(self, factory_name):
"""
Add an effect to the current selection
"""Adds an effect to the current selection.
Args:
factory_name (str): The name of the GstElementFactory to creaye the
effect from.
factory_name (str): The name of the GstElementFactory for creating
the effect.
"""
if not self.clips or len(self.clips) > 1:
return
......@@ -433,9 +424,7 @@ class EffectProperties(Gtk.Expander, Loggable):
@staticmethod
def calculateEffectPriority(source_index, drop_index, drop_pos):
"""
Return where the effect from source_index will end up
"""
"""Calculates where the effect from source_index will end up."""
if drop_pos in (Gtk.TreeViewDropPosition.INTO_OR_BEFORE, Gtk.TreeViewDropPosition.INTO_OR_AFTER):
return drop_index
if drop_pos == Gtk.TreeViewDropPosition.BEFORE:
......@@ -539,9 +528,7 @@ class EffectProperties(Gtk.Expander, Loggable):
class TransformationProperties(Gtk.Expander, Loggable):
"""
Widget for viewing and configuring speed
"""
"""Widget for configuring the placement and size of the clip."""
__signals__ = {
'selection-changed': []}
......@@ -617,10 +604,7 @@ class TransformationProperties(Gtk.Expander, Loggable):
spinbtn.set_value(value)
def __setupSpinButton(self, widget_name, property_name):
"""
Create a spinbutton widget and connect its signals to change property
values. While focused, disable the timeline actions' sensitivity.
"""
"""Creates a SpinButton for editing a property value."""
spinbtn = self.builder.get_object(widget_name)
spinbtn.connect("output", self._onValueChangedCb, property_name)
disable_scroll(spinbtn)
......
......@@ -16,8 +16,8 @@
# License along with this program; if not, write to the
# Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
# Boston, MA 02110-1301, USA.
"""
Utilities for getting the location of various directories.
"""Utilities for getting the location of various directories.
Enables identical use for installed and uninstalled versions.
"""
......@@ -30,9 +30,7 @@ def _get_root_dir():
def in_devel():
"""
Returns whether the app is run from a git checkout.
"""
"""Returns whether the app is run from a git checkout."""
return os.environ.get("PITIVI_DEVELOPMENT", "0") != "0"
if "APPDIR" in os.environ:
......@@ -68,29 +66,29 @@ def get_data_dir():
def get_pixmap_dir():
""" Returns the directory for program-only pixmaps """
"""Returns our directory with pixmaps."""
return os.path.join(get_data_dir(), 'pixmaps')
def get_ui_dir():
""" Returns the directory for GtkBuilder/Glade files """
"""Returns our directory with Gtk.Builder/Glade files."""
return os.path.join(get_data_dir(), 'ui')
def get_renderpresets_dir():
""" Returns the directory for Render Presets files """
"""Returns our directory with Render Presets files."""
return os.path.join(get_data_dir(), 'renderpresets')
def get_audiopresets_dir():
""" Returns the directory for Audio Presets files """
"""Returns our directory with Audio Presets files."""
return os.path.join(get_data_dir(), 'audiopresets')
def get_videopresets_dir():
""" Returns the directory for Video Presets files """
"""Returns our directory with Video Presets files."""
return os.path.join(get_data_dir(), 'videopresets')
def get_gstpresets_dir():
""" Returns the directory for Video Presets files """
"""Returns our directory with Gst Presets files."""
return os.path.join(get_data_dir(), 'gstpresets')
"""
Gtk+ v2.x User Interface package
"""
......@@ -30,12 +30,13 @@ from pitivi.utils.ui import pixel_aspect_ratios
class ClipMediaPropsDialog(object):
"""Displays the properties of an asset.
"""
Displays the properties of an asset, and allows applying them to a project.
Allows applying them to the project.
@type project: L{Project}
@type asset: L{GES.UriClipAsset}
Attributes:
project (Project): The project.
asset (GES.UriClipAsset): The displayed asset.
"""
def __init__(self, project, asset):
......@@ -73,7 +74,7 @@ class ClipMediaPropsDialog(object):
self.video_header_label = builder.get_object("label2")
def run(self):
"""Set up widgets and run the dialog"""
"""Sets up widgets and run the dialog."""
# TODO: in "onApplyButtonClicked", we only use the first stream...
# If we have multiple audio or video streams, we should reflect that
# in the UI, instead of acting as if there was only one. But that means
......@@ -137,7 +138,7 @@ class ClipMediaPropsDialog(object):
self.dialog.run()
def _applyButtonCb(self, unused_button):
"""Apply widget values to the project"""
"""Applies the widgets values to the project."""
project = self.project
if self.has_video:
# This also handles the case where the video is a still image
......@@ -160,7 +161,7 @@ class ClipMediaPropsDialog(object):
self.dialog.destroy()
def _cancelButtonCb(self, unused_button):
"""Destroy the dialog"""
"""Destroys the dialog."""
self.dialog.destroy()
def _keyPressCb(self, unused_widget, event):
......
......@@ -16,7 +16,7 @@
# License along with this program; if not, write to the
# Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
# Boston, MA 02110-1301, USA.
""" This module implements the notions of missing dependencies """
"""Missing dependencies logic."""
import os
from gi.repository import Gtk
......@@ -26,10 +26,7 @@ from pitivi.configure import get_ui_dir
class DepsManager(object):
"""Display a dialog listing missing soft dependencies.
The sane way to query and install is by using PackageKit's InstallResource()
"""
"""Manages a dialog listing missing soft dependencies."""
def __init__(self, app, parent_window=None):
self.app = app
......@@ -54,11 +51,11 @@ class DepsManager(object):
self.show()
def _onCloseButtonClickedCb(self, unused_button):
""" Hide on close """
"""Hides the dialog."""
self.hide()
def _onInstallButtonClickedCb(self, unused_button):
""" Hide on install and try to install dependencies """
"""Hides on install and tries to install dependencies."""
self.hide()
# FIXME: this is not implemented properly.
# Here is some partially working code:
......@@ -84,10 +81,7 @@ class DepsManager(object):
# TODO: catch exceptions/create callbacks to _installFailedCb
def _setDepsLabel(self):
"""
Set the contents of the label containing the list of
missing dependencies
"""
"""Updates the UI to display the list of missing dependencies."""
label_contents = ""
for depname, dep in missing_soft_deps.items():
label_contents += "• %s (%s)\n" % (
......@@ -95,13 +89,13 @@ class DepsManager(object):
self.builder.get_object("pkg_list").set_text(label_contents)
def show(self):
"""Show internal window"""
"""Shows the dialog."""
self.window.show()
def hide(self):
"""Hide internal window"""
"""Hides the dialog."""
self.window.hide()
def _installFailedCb(self, unused_exception):
"""Handle the failure of installing packages."""
"""Handles the failure of installing packages."""
self.show()
......@@ -16,9 +16,7 @@
# License along with this program; if not, write to the
# Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
# Boston, MA 02110-1301, USA.
"""
Dialog box listing files which had errors, and the reasons.
"""
"""Assets discovery errors."""
import os
from gettext import gettext as _
from urllib.parse import unquote
......@@ -32,8 +30,7 @@ from pitivi.utils.loggable import Loggable
class FileListErrorDialog(GObject.Object, Loggable):
""" Dialog box for showing errors in a list of files """
"""Dialog for showing errors blocking importing media files."""
__gsignals__ = {
'close': (GObject.SIGNAL_RUN_LAST, None, ()),
......@@ -55,9 +52,11 @@ class FileListErrorDialog(GObject.Object, Loggable):
self.errorvbox = self.builder.get_object("errorvbox")
def addFailedFile(self, uri, reason=_("Unknown reason"), extra=None):
"""Add the given uri to the list of failed files. You can optionnaly
give a string identifying the reason why the file failed to be
discovered
"""Adds the specified URI to the list of failures.
Args:
uri (str): The URI of the asset which cannot be imported.
reason (Optional[str]): The reason of the file discovery failure.
"""
self.debug("Uri: %s, reason: %s, extra: %s", uri, reason, extra)
exp = self.__createFileExpander(uri, reason, extra)
......@@ -105,19 +104,19 @@ class FileListErrorDialog(GObject.Object, Loggable):
return exp
def isVisible(self):
""" returns True if this dialog is currently shown """
"""Returns True if the dialog is currently shown."""
return self.window.get_property("visible")
def destroy(self):
"""Destroy internal window"""
"""Destroys the dialog."""
self.window.destroy()
# Callbacks from glade
def _closeCb(self, unused_dialog):
"""Emit the close signal"""
"""Emits the `close` signal."""
self.emit('close')
def _responseCb(self, unused_dialog, response):
"""Emit the response signal"""
"""Emits the `response` signal."""
self.emit('response', response)
......@@ -16,9 +16,7 @@
# License along with this program; if not, write to the
# Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
# Boston, MA 02110-1301, USA.
"""
Dialog box for user preferences.
"""
"""User preferences."""
import os
from gettext import gettext as _
......@@ -45,10 +43,7 @@ GlobalSettings.addConfigOption('prefsDialogHeight',
class PreferencesDialog(Loggable):
"""
Preferences for how the app works.
"""
"""Preferences for how the app works."""
prefs = {}
original_values = {}
......@@ -84,31 +79,25 @@ class PreferencesDialog(Loggable):
self.dialog.set_default_size(width, height)
def run(self):
"""Run the internal dialog"""
"""Runs the dialog."""
self.dialog.run()
# Public API
@classmethod
def addPreference(cls, attrname, label, description, section=None,
widget_class=None, **args):
"""
Add a user preference. The preferences dialog will try
to guess the appropriate widget to use based on the type of the
option, but you can override this by specifying a custom class.
@param attrname: the id of the setting holding the preference
@type attrname: C{str}
@param label: user-visible name for this option
@type label: C{str}
@param description: a user-visible description documenting this option
(ignored unless prefs_label is non-null)
@type description: C{str}
@param : user-visible category to which this option
belongs (ignored unless prefs_label is non-null)
@type section: C{str}
@param widget_class: overrides auto-detected widget
@type widget_class: C{class}
def _add_preference(cls, attrname, label, description, section,
widget_class, **args):
"""Adds a user preference.
Args:
attrname (str): The id of the setting holding the preference.
label (str): The user-visible name for this option.
description (str): The user-visible description explaining this
option. Ignored unless `label` is non-None.
section (str): The user-visible category to which this option
belongs. Ignored unless `label` is non-None.
widget_class (type): The class of the widget for displaying the
option.
"""
if not section:
section = "General"
......@@ -118,143 +107,51 @@ class PreferencesDialog(Loggable):
@classmethod
def addPathPreference(cls, attrname, label, description, section=None):
"""
Add an auto-generated user preference that will show up as a
Gtk.FileChooserButton.
@param label: user-visible name for this option
@type label: C{str}
@param description: a user-visible description documenting this option
(ignored unless prefs_label is non-null)
@type description: C{str}
@param section: user-visible category to which this option
belongs (ignored unless prefs_label is non-null)
@type section: C{str}
"""
cls.addPreference(attrname, label, description, section,
widgets.PathWidget)
"""Adds a user preference for a file path."""
cls._add_preference(attrname, label, description, section,
widgets.PathWidget)
@classmethod
def addNumericPreference(cls, attrname, label, description, section=None,
upper=None, lower=None):
"""Adds a user preference for a number.
Show up as either a Gtk.SpinButton or a horizontal Gtk.Scale, depending
whether both the upper and lower limits are set.
"""
Add an auto-generated user preference that will show up as either a
Gtk.SpinButton or an horizontal Gtk.Scale, depending whether both the
upper and lower limits are set.
@param label: user-visible name for this option
@type label: C{str}
@param description: a user-visible description documenting this option
(ignored unless prefs_label is non-null)
@type description: C{str}
@param section: user-visible category to which this option
belongs (ignored unless prefs_label is non-null)
@type section: C{str}
@param upper: upper limit for this widget, or None
@type upper: C{number}
@param lower: lower limit for this widget, or None
@type lower: C{number}
"""
cls.addPreference(attrname, label, description, section,
widgets.NumericWidget, upper=upper, lower=lower)
cls._add_preference(attrname, label, description, section,
widgets.NumericWidget, upper=upper, lower=lower)
@classmethod
def addTextPreference(cls, attrname, label, description, section=None, matches=None):
"""
Add an auto-generated user preference that will show up as either a
Gtk.SpinButton or an horizontal Gtk.Scale, depending on the upper and
lower limits
@param label: user-visible name for this option
@type label: C{str}
@param description: a user-visible description documenting this option
(ignored unless prefs_label is non-null)
@type description: C{str}
@param section: user-visible category to which this option
belongs (ignored unless prefs_label is non-null)
@type section: C{str}
"""
cls.addPreference(attrname, label, description, section,
widgets.TextWidget, matches=matches)
"""Adds a user preference for text."""
cls._add_preference(attrname, label, description, section,
widgets.TextWidget, matches=matches)
@classmethod
def addChoicePreference(cls, attrname, label, description, choices, section=None):
"""
Add an auto-generated user preference that will show up as either a
Gtk.ComboBox or a group of radio buttons, depending on the number of
choices.
@param label: user-visible name for this option
@type label: C{str}
@param description: a user-visible description documenting this option
(ignored unless prefs_label is non-null)