From d174e492736600dfc1a16359434fab75d717f1f3 2014-04-29 19:35:06 From: Dimitry Kloper Date: 2014-04-29 19:35:06 Subject: [PATCH] Added more documentation for MagicHelper. --- diff --git a/IPython/qt/console/magic_helper.py b/IPython/qt/console/magic_helper.py index 17c3e20..1a00b07 100644 --- a/IPython/qt/console/magic_helper.py +++ b/IPython/qt/console/magic_helper.py @@ -1,4 +1,4 @@ -"""Magic Helper - dockable widget showing magic commands for the MainWindow +"""MagicHelper - dockable widget showing magic commands for the MainWindow Authors: @@ -22,28 +22,50 @@ from IPython.external.qt import QtGui,QtCore from IPython.core.magic import magic_escapes class MagicHelper(QtGui.QDockWidget): + """MagicHelper - dockable widget for convenient search and running of + magic command for IPython QtConsole. + """ + + #--------------------------------------------------------------------------- + # signals + #--------------------------------------------------------------------------- pasteRequested = QtCore.pyqtSignal(str, name = 'pasteRequested') + """This signal is emitted when user wants to paste selected magic + command into the command line. + """ + runRequested = QtCore.pyqtSignal(str, name = 'runRequested') + """This signal is emitted when user wants to execute selected magic command + """ + readyForUpdate = QtCore.pyqtSignal(name = 'readyForUpdate') + """This signal is emitted when MagicHelper is ready to be populated. + Since kernel querying mechanisms are out of scope of this class, + it expects its owner to invoke MagicHelper.populate_magic_helper() + as a reaction on this event. + """ #--------------------------------------------------------------------------- - # 'object' interface + # constructor #--------------------------------------------------------------------------- def __init__(self, name, parent): - super(MagicHelper, self).__init__(name, parent) self.data = None class MinListWidget(QtGui.QListWidget): + """Temp class to overide the default QListWidget size hint + in order to make MagicHelper narrow + """ def sizeHint(self): s = QtCore.QSize() s.setHeight(super(MinListWidget,self).sizeHint().height()) s.setWidth(self.sizeHintForColumn(0)) return s + # construct content self.frame = QtGui.QFrame() self.search_label = QtGui.QLabel("Search:") self.search_line = QtGui.QLineEdit() @@ -52,6 +74,7 @@ class MagicHelper(QtGui.QDockWidget): self.paste_button = QtGui.QPushButton("Paste") self.run_button = QtGui.QPushButton("Run") + # layout all the widgets main_layout = QtGui.QVBoxLayout() search_layout = QtGui.QHBoxLayout() search_layout.addWidget(self.search_label) @@ -67,7 +90,8 @@ class MagicHelper(QtGui.QDockWidget): self.frame.setLayout(main_layout) self.setWidget(self.frame) - self.visibilityChanged[bool].connect( self.update_magic_helper ) + # connect all the relevant signals to handlers + self.visibilityChanged[bool].connect( self._update_magic_helper ) self.search_class.activated[int].connect( self.class_selected ) @@ -84,15 +108,29 @@ class MagicHelper(QtGui.QDockWidget): self.run_requested ) - def update_magic_helper(self, visible): + #--------------------------------------------------------------------------- + # implementation + #--------------------------------------------------------------------------- + + def _update_magic_helper(self, visible): + """Start update sequence. + This method is called when MagicHelper becomes visible. It clears + the content and emits readyForUpdate signal. The owner of the + instance is expected to invoke populate_magic_helper() when magic + info is available. + """ if not visible or self.data != None: return self.data = {} self.search_class.clear() self.search_class.addItem("Populating...") + self.search_list.clear() self.readyForUpdate.emit() def populate_magic_helper(self, data): + """Expects data returned by lsmagics query from kernel. + Populates the search_class and search_list with relevant items. + """ self.search_class.clear() self.search_list.clear() @@ -115,17 +153,24 @@ class MagicHelper(QtGui.QDockWidget): self.filter_magic_helper('.', 'any') def class_selected(self, index): + """Handle search_class selection changes + """ item = self.search_class.itemData(index) regex = self.search_line.text() self.filter_magic_helper(regex = regex, cls = item) def search_changed(self, search_string): + """Handle search_line text changes. + The text is interpreted as a regular expression + """ item = self.search_class.itemData( self.search_class.currentIndex() ) self.filter_magic_helper(regex = search_string, cls = item) def _get_current_search_item(self, item = None): + """Retrieve magic command currently selected in the search_list + """ text = None if not isinstance(item, QtGui.QListWidgetItem): item = self.search_list.currentItem() @@ -133,16 +178,24 @@ class MagicHelper(QtGui.QDockWidget): return text def paste_requested(self, item = None): + """Emit pasteRequested signal with currently selected item text + """ text = self._get_current_search_item(item) if text != None: self.pasteRequested.emit(text) def run_requested(self, item = None): + """Emit runRequested signal with currently selected item text + """ text = self._get_current_search_item(item) if text != None: self.runRequested.emit(text) def filter_magic_helper(self, regex, cls): + """Update search_list with magic commands whose text match + regex and class match cls. + If cls equals 'any' - any class matches. + """ if regex == "" or regex == None: regex = '.' if cls == None: