Merge pull request #25 from python-paling/refactoring-and-typing

Refactoring and typing

Author: savelkouls

paling/browsers.py

@@ -47,6 +47,22 @@ def _build_urls(start_pages: Iterable[Union[str, Dict[str, str]]], options: Opti
 
 
 def open(start_pages: Iterable[Union[str, Dict[str, str]]], options: OptionsDictT) -> None:
+    """
+    Open a browser and navigate to the specified start pages.
+
+    Args:
+        start_pages (Iterable[Union[str, Dict[str, str]]]): A collection of start pages to navigate to.
+            Each start page can be either a URL string or a dictionary with 'url' and 'params' keys.
+        options (OptionsDictT): A dictionary of options for configuring the browser.
+
+    Raises:
+        TypeError: If the 'mode' option is not a string, boolean, or None.
+        TypeError: If the 'cmdline_args' option is not a list of strings.
+        EnvironmentError: If the specified browser installation cannot be found.
+
+    Returns:
+        None
+    """
     # Build full URLs for starting pages (including host and port)
     start_urls = _build_urls(start_pages, options)
 

paling/chrome.py

@@ -8,6 +8,20 @@
 name: str = 'Google Chrome/Chromium'
 
 def run(path: str, options: OptionsDictT, start_urls: List[str]) -> None:
+    """
+    Run the Chrome browser with the specified path, options, and start URLs.
+
+    Args:
+        path (str): The path to the Chrome browser executable.
+        options (OptionsDictT): A dictionary containing the options for running Chrome.
+        start_urls (List[str]): A list of URLs to open in Chrome.
+
+    Raises:
+        TypeError: If the 'cmdline_args' option is not of type List[str].
+
+    Returns:
+        None
+    """
     if not isinstance(options['cmdline_args'], list):
         raise TypeError("'cmdline_args' option must be of type List[str]")
     if options['app_mode']:
@@ -22,6 +36,12 @@ def run(path: str, options: OptionsDictT, start_urls: List[str]) -> None:
 
 
 def find_path() -> Optional[str]:
+    """
+    Finds the path of the Chrome executable based on the current operating system.
+
+    Returns:
+        Optional[str]: The path of the Chrome executable if found, otherwise None.
+    """
     if sys.platform in ['win32', 'win64']:
         return _find_chrome_win()
     elif sys.platform == 'darwin':
@@ -33,6 +53,12 @@ def find_path() -> Optional[str]:
 
 
 def _find_chrome_mac() -> Optional[str]:
+    """
+    Find the path of Google Chrome executable on macOS.
+
+    Returns:
+        Optional[str]: The path of Google Chrome executable if found, otherwise None.
+    """
     default_dir = r'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
     if os.path.exists(default_dir):
         return default_dir
@@ -45,6 +71,12 @@ def _find_chrome_mac() -> Optional[str]:
 
 
 def _find_chromium_mac() -> Optional[str]:
+    """
+    Find the Chromium executable path on macOS.
+
+    Returns:
+        Optional[str]: The path to the Chromium executable if found, None otherwise.
+    """
     default_dir = r'/Applications/Chromium.app/Contents/MacOS/Chromium'
     if os.path.exists(default_dir):
         return default_dir
@@ -57,6 +89,12 @@ def _find_chromium_mac() -> Optional[str]:
 
 
 def _find_chrome_linux() -> Optional[str]:
+    """
+    Finds the path of the Chrome executable on a Linux system.
+
+    Returns:
+        Optional[str]: The path of the Chrome executable if found, None otherwise.
+    """
     import whichcraft as wch
     chrome_names = ['chromium-browser',
                     'chromium',
@@ -71,6 +109,12 @@ def _find_chrome_linux() -> Optional[str]:
 
 
 def _find_chrome_win() -> Optional[str]:
+    """
+    Find the path of the Chrome executable on Windows.
+
+    Returns:
+        Optional[str]: The path of the Chrome executable if found, None otherwise.
+    """
     import winreg as reg
     reg_path = r'SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\chrome.exe'
     chrome_path: Optional[str] = None

paling/edge.py

@@ -1,8 +1,20 @@
 import sys, subprocess as sps, os
+from typing import Optional
 
 name = 'Edge'
 
-def run(path, options, start_urls):
+def run(path: str, options: dict, start_urls: list) -> None:
+    """
+    Run the specified web browser with the given options and start URLs.
+
+    Args:
+        path (str): The path to the web browser executable.
+        options (dict): A dictionary of options for the web browser.
+        start_urls (list): A list of URLs to open in the web browser.
+
+    Returns:
+        None
+    """
     if path != 'edge_legacy':
         if options['app_mode']:
             for url in start_urls:
@@ -16,13 +28,19 @@ def run(path, options, start_urls):
         cmd = 'start microsoft-edge:{}'.format(start_urls[0])
         sps.Popen(cmd, stdout=sys.stdout, stderr=sys.stderr, stdin=sps.PIPE, shell=True)
 
-def find_path():
+def find_path() -> Optional[str]:
     if sys.platform in ['win32', 'win64']:
         return _find_edge_win()
     else:
         return None
 
-def _find_edge_win():
+def _find_edge_win() -> str:
+    """
+    Finds the path of the Microsoft Edge browser executable on Windows.
+
+    Returns:
+        str: The path of the Microsoft Edge browser executable.
+    """
     import winreg as reg
     reg_path = r'SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\msedge.exe'
 
@@ -33,7 +51,7 @@ def _find_edge_win():
             reg_key.Close()
             if not os.path.isfile(edge_path):
                 continue
-        except WindowsError:
+        except FileNotFoundError:
             edge_path = 'edge_legacy'
         else:
             break

paling/electron.py

@@ -10,6 +10,17 @@
 name: str = 'Electron'
 
 def run(path: str, options: OptionsDictT, start_urls: List[str]) -> None:
+    """
+    Run the specified Electron application.
+
+    Args:
+        path (str): The path to the Electron application executable.
+        options (OptionsDictT): A dictionary containing options for the Electron application.
+        start_urls (List[str]): A list of URLs to open in the Electron application.
+
+    Raises:
+        TypeError: If the 'cmdline_args' option is not of type List[str].
+    """
     if not isinstance(options['cmdline_args'], list):
         raise TypeError("'cmdline_args' option must be of type List[str]")
     cmd = [path] + options['cmdline_args']
@@ -18,12 +29,18 @@ def run(path: str, options: OptionsDictT, start_urls: List[str]) -> None:
 
 
 def find_path() -> Optional[str]:
+    """
+    Finds the path to the Electron executable.
+
+    Returns:
+        Optional[str]: The path to the Electron executable if found, otherwise None.
+    """
     if sys.platform in ['win32', 'win64']:
         # It doesn't work well passing the .bat file to Popen, so we get the actual .exe
         bat_path = wch.which('electron')
         return os.path.join(bat_path, r'..\node_modules\electron\dist\electron.exe')
     elif sys.platform in ['darwin', 'linux']:
-        # This should work find...
+        # This should work fine...
         return wch.which('electron') # type: ignore # whichcraft doesn't currently have type hints
     else:
         return None