Add Doc string and conform to PEP 8

IPython/Extensions/ipy_synchronize_with.py

@@ -10,11 +10,27 b' import scitedirector'
 
 # test to write.
 
-def setHook(synchronize_with_editor):
+def set_hook(synchronize_with_editor):
+    """Set the synchronize with editor hook with a callable object.
+    
+    The callable object will be called with the following arguments when
+    IPython wants to synchronize with you favorite editor:
+    
+     - ip: a running IPython instance.
+     
+     - filename: the path of the file the editor is supposed to display.
+     
+     - lineno : the line number of the line the editor is supposed to
+     highlight.
+     
+     - columnno : the column number of the character the editor is supposed
+     to highlight.
+    """
     ip.set_hook("synchronize_with_editor", synchronize_with_editor)
 
 
-def findFilename(filename):
+def find_filename(filename):
+    """Return the filename to synchronize with based on """
     filename = os.path.splitext(filename)
     if filename[1] == ".pyc":
         filename = (filename[0], ".py")
@@ -29,7 +45,12 b' def findFilename(filename):'
     return ""
 
 
-def runCommand(path, command, arguments, asynchronous = True):
+def run_command(path, command, arguments, asynchronous = True):
+    """Run a shell command and return the exit code of the command"""
+    # This is a thin wrapper around os.system that:
+    #  - Let you run command asynchronously.
+    #  - Accept spaces in command path.
+    #  - Dont throw exception if the command don't exist.
     line = ''
     if asynchronous:
         line += 'start '
@@ -46,16 +67,18 b' def runCommand(path, command, arguments, asynchronous = True):'
 
 
 def sleep(milliseconds):
+    """Wait some milliseconds."""
+    # This is used to make sure the editor did its job before we reset the focus on the console.
     win32api.Sleep(milliseconds)
 
 
-def restoreConsoleFocus():
+def restore_console_focus():
+    """Restore the focus to the IPython console."""
     h = win32console.GetConsoleWindow()
     console_window = win32ui.CreateWindowFromHandle(h)
     console_window.SetForegroundWindow()
     
     
-
 # This is the most simple example of hook:
 class GVimHook:
     def __init__(self, path, wakeup_duration):
@@ -63,21 +86,21 b' class GVimHook:'
         self.wakeup_duration = wakeup_duration
 
     def __call__(self, ip, filename, lineno, columnno):
-        filename = findFilename(filename)
+        filename = find_filename(filename)
 
         if not filename:
             return
 
-        runCommand(self.path, 'gvim', '--remote-silent +%d "%s"' % (lineno, filename))
+        run_command(self.path, 'gvim', '--remote-silent +%d "%s"' % (lineno, filename))
 
         sleep(self.wakeup_duration)
 
-        restoreConsoleFocus()
+        restore_console_focus()
 
 
 def gvim(path = r"C:\Program Files\vim\vim71", wakeup_duration = 100):
     synchronize_with_editor = GVimHook(path, wakeup_duration)
-    setHook(synchronize_with_editor)
+    set_hook(synchronize_with_editor)
 
 
 class EmacsHook:
@@ -87,24 +110,24 b' class EmacsHook:'
         self.start_duration = start_duration
 
     def __call__(self, ip, filename, lineno, columnno):
-        filename = findFilename(filename)
+        filename = find_filename(filename)
 
         if not filename:
             return
 
-        r = runCommand(self.path, "emacsclient", '-n +%d:%d "%s" 2>nul' % (lineno, columnno, filename), False)
+        r = run_command(self.path, "emacsclient", '-n +%d:%d "%s" 2>nul' % (lineno, columnno, filename), False)
         if r != 0:
-            runCommand(self.path, 'runemacs', '--quick -f server-start +%d:%d "%s"' % (lineno, columnno, filename))
+            run_command(self.path, 'runemacs', '--quick -f server-start +%d:%d "%s"' % (lineno, columnno, filename))
             sleep(self.start_duration)
         else:
             sleep(self.wakeup_duration)
 
-        restoreConsoleFocus()
+        restore_console_focus()
 
 
 def emacs(path = r"C:\Program Files\emacs\bin", wakeup_duration = 100, start_duration = 2000):
     synchronize_with_editor = EmacsHook(path, wakeup_duration, start_duration)
-    setHook(synchronize_with_editor)
+    set_hook(synchronize_with_editor)
 
 
 class SciteHook:
@@ -114,17 +137,17 b' class SciteHook:'
         self.start_duration = start_duration
 
     def __call__(self, ip, filename, lineno, columnno):
-        filename = findFilename(filename)
+        filename = find_filename(filename)
 
         if not filename:
             return
 
         scites = scitedirector.findWindows()
         if not scites:
-            runCommand(self.path, "scite", '"-open:%s" -goto:%d' % (filename.replace("\\", "/"), lineno))
+            run_command(self.path, "scite", '"-open:%s" -goto:%d' % (filename.replace("\\", "/"), lineno))
 
             sleep(self.start_duration)
-            restoreConsoleFocus()
+            restore_console_focus()
         else:
             scite = scites[0]
             scitedirector.sendCommand(scite, 'open:%s' % filename.replace("\\", "/"))
@@ -133,7 +156,7 b' class SciteHook:'
 
 def scite(path = r"C:\Program Files\SciTE Source Code Editor", wakeup_duration = 100, start_duration = 500):
     synchronize_with_editor = SciteHook(path, wakeup_duration, start_duration)
-    setHook(synchronize_with_editor)
+    set_hook(synchronize_with_editor)
 
 
 class NodePadPlusPlusHook:
@@ -142,21 +165,21 b' class NodePadPlusPlusHook:'
         self.wakeup_duration = wakeup_duration
 
     def __call__(self, ip, filename, lineno, columnno):
-        filename = findFilename(filename)
+        filename = find_filename(filename)
 
         if not filename:
             return
 
-        runCommand(self.path, "notepad++", '"%s" -n%d' % (filename, lineno))
+        run_command(self.path, "notepad++", '"%s" -n%d' % (filename, lineno))
 
         sleep(self.wakeup_duration)
 
-        restoreConsoleFocus()
+        restore_console_focus()
 
 
 def notepadplusplus(path = r"C:\Program Files\Notepad++", wakeup_duration = 100):
     synchronize_with_editor = NodePadPlusPlusHook(path, wakeup_duration)
-    setHook(synchronize_with_editor)
+    set_hook(synchronize_with_editor)
 
 
 class PsPadHook:
@@ -165,21 +188,21 b' class PsPadHook:'
         self.wakeup_duration = wakeup_duration
 
     def __call__(self, ip, filename, lineno, columnno):
-        filename = findFilename(filename)
+        filename = find_filename(filename)
 
         if not filename:
             return
 
-        runCommand(self.path, "pspad", '"%s" -%d' % (filename, lineno))
+        run_command(self.path, "pspad", '"%s" -%d' % (filename, lineno))
 
         sleep(self.wakeup_duration)
 
-        restoreConsoleFocus()
+        restore_console_focus()
 
 
 def pspad(path = r"C:\Program Files\PSPad editor", wakeup_duration = 100):
     synchronize_with_editor = PsPadHook(path, wakeup_duration)
-    setHook(synchronize_with_editor)
+    set_hook(synchronize_with_editor)
 
 
 # This is an example of DDE hook:
@@ -190,7 +213,7 b' class UltraEditHook:'
         self.start_duration = start_duration
 
     def __call__(self, ip, filename, lineno, columnno):
-        filename = findFilename(filename)
+        filename = find_filename(filename)
 
         if not filename:
             return
@@ -204,16 +227,16 b' class UltraEditHook:'
             
             sleep(self.wakeup_duration)
         except:
-            runCommand(self.path, 'uedit32', '"%s/%d"' % (filename, lineno))
+            run_command(self.path, 'uedit32', '"%s/%d"' % (filename, lineno))
             
             sleep(self.start_duration)
 
         server.Shutdown()
 
-        restoreConsoleFocus()
+        restore_console_focus()
 
 
 def ultraedit(path = r"C:\Program Files\IDM Computer Solutions\UltraEdit-32", wakeup_duration = 10, start_duration = 2000):
     synchronize_with_editor = UltraEditHook(path, wakeup_duration, start_duration)
-    setHook(synchronize_with_editor)
+    set_hook(synchronize_with_editor)
     
  No newline at end of file