browser documentation

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,4 +1,5 @@
 import sys, subprocess as sps, os
+from typing import Optional
 
 name = 'Edge'
 
@@ -27,7 +28,7 @@ def run(path: str, options: dict, start_urls: list) -> None:
         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() -> str | None:
+def find_path() -> Optional[str]:
     if sys.platform in ['win32', 'win64']:
         return _find_edge_win()
     else: