Skip to content

API Reference

Jump to bottom
Auto Bot Solutions edited this page Apr 27, 2026 · 1 revision

This document provides a comprehensive API reference for the Secure Browser project, including all classes, methods, and their parameters.

Table of Contents

Main Entry Point

main()

Location: main.py

Description: Main entry point for the Secure Browser application. Handles command-line argument parsing and browser selection.

Parameters: None

Returns: None

Raises: None

Example:

# Run from command line
python main.py --browser pyqt5
python main.py --browser tkinter
python main.py --browser webview
python main.py --browser search

Command-Line Arguments:

  • --browser: Browser implementation to launch
    • Choices: pyqt5, tkinter, webview, search
    • Default: pyqt5

PyQt5 Browser API

Browser Class

Location: src/browsers/hope.py

Description: Main browser window class with tabbed interface, dark theme, and advanced UI features.

__init__()

Description: Initialize the browser window with default settings.

Parameters: None

Returns: Browser instance

Example:

from src.browsers.hope import Browser
browser = Browser()
browser.show()

create_navigation_bar()

Description: Creates the navigation bar with buttons and URL input.

Parameters: None

Returns: QHBoxLayout - Navigation bar layout

Example:

nav_layout = browser.create_navigation_bar()

open_new_tab(url=None)

Description: Opens a new tab with the given URL, or default URL if none provided.

Parameters:

Returns: None

Example:

browser.open_new_tab("https://example.com")
browser.open_new_tab()  # Opens default URL

close_tab(index)

Description: Closes the tab at the given index.

Parameters:

  • index (int): Index of the tab to close

Returns: None

Example:

browser.close_tab(0)

load_url()

Description: Loads a URL typed into the URL bar. Automatically adds https:// prefix if missing.

Parameters: None (reads from URL bar)

Returns: None

Example:

browser.url_bar.setText("example.com")
browser.load_url()  # Loads https://example.com

update_tab_url(url)

Description: Updates the URL bar when the tab's URL changes.

Parameters:

  • url (QUrl): New URL to display

Returns: None

Example:

browser.update_tab_url(QUrl("https://example.com"))

update_tab_title(title)

Description: Updates the tab's title based on the webpage title.

Parameters:

  • title (str): New title for the tab

Returns: None

Example:

browser.update_tab_title("Example Page")

go_back()

Description: Navigates back to the previous page in the current tab.

Parameters: None

Returns: None

Example:

browser.go_back()

go_forward()

Description: Navigates forward to the next page in the current tab.

Parameters: None

Returns: None

Example:

browser.go_forward()

reload_page()

Description: Reloads the current tab's page.

Parameters: None

Returns: None

Example:

browser.reload_page()

go_home()

Description: Navigates to the home page (https://search.brave.com/).

Parameters: None

Returns: None

Example:

browser.go_home()

open_settings_panel()

Description: Opens the settings dialog for adjusting configurations.

Parameters: None

Returns: None

Example:

browser.open_settings_panel()

SettingsDialog Class

Location: src/browsers/hope.py

Description: Settings dialog for configuring browser options.

__init__(parent=None)

Description: Initialize the settings dialog.

Parameters:

  • parent (QWidget, optional): Parent widget. Defaults to None.

Returns: SettingsDialog instance

Example:

from src.browsers.hope import SettingsDialog
dialog = SettingsDialog(browser)
dialog.exec_()

Attributes:

  • vpn_checkbox (QCheckBox): VPN toggle
  • javascript_checkbox (QCheckBox): JavaScript enable/disable
  • proxy_input (QLineEdit): Proxy configuration

main()

Location: src/browsers/hope.py

Description: Main function to launch the PyQt5 browser.

Parameters: None

Returns: None

Example:

from src.browsers.hope import main
main()

Tkinter Browser API

SimpleBrowser Class

Location: src/browsers/secure_browser.py

Description: Lightweight secure browser with security features, whitelist/blacklist filtering, and bookmark management.

__init__(root)

Description: Initialize the browser with Tkinter root window.

Parameters:

  • root (tk.Tk): Tkinter root window

Returns: SimpleBrowser instance

Example:

import tkinter as tk
from src.browsers.secure_browser import SimpleBrowser

root = tk.Tk()
browser = SimpleBrowser(root)
root.mainloop()

Attributes:

  • history (list): Navigation history
  • current_index (int): Current position in history
  • bookmarks (list): Saved bookmarks
  • security_headers (dict): Security header configurations
  • whitelist (list): Allowed websites
  • blacklist (list): Blocked websites

load_url(event=None)

Description: Loads a URL from the address bar. Enforces HTTPS and applies security filters.

Parameters:

  • event (tk.Event, optional): Event object. Defaults to None.

Returns: None

Example:

browser.url_entry.delete(0, tk.END)
browser.url_entry.insert(0, "example.com")
browser.load_url()

add_bookmark()

Description: Adds the current URL to bookmarks.

Parameters: None

Returns: None

Example:

browser.add_bookmark()

search_web()

Description: Performs a web search using the current URL bar content.

Parameters: None

Returns: None

Example:

browser.url_entry.delete(0, tk.END)
browser.url_entry.insert(0, "Python tutorial")
browser.search_web()

apply_security_headers(content)

Description: Applies security headers to the content (placeholder function).

Parameters:

  • content (str): Content to process

Returns: str - Processed content

Example:

secured_content = browser.apply_security_headers(raw_content)

reload_page()

Description: Reloads the current page from history.

Parameters: None

Returns: None

Example:

browser.reload_page()

go_back()

Description: Navigates back in history.

Parameters: None

Returns: None

Example:

browser.go_back()

go_forward()

Description: Navigates forward in history.

Parameters: None

Returns: None

Example:

browser.go_forward()

go_home()

Description: Navigates to the home page.

Parameters: None

Returns: None

Example:

browser.go_home()

open_settings()

Description: Opens the settings window with all configuration options.

Parameters: None

Returns: None

Example:

browser.open_settings()

set_user_agent()

Description: Sets the User-Agent string for requests.

Parameters: None (reads from user_agent_var)

Returns: None

Example:

browser.user_agent_var.set("Mozilla/5.0 (Custom)")
browser.set_user_agent()

set_proxy()

Description: Configures HTTP and HTTPS proxy settings.

Parameters: None (reads from proxy input fields)

Returns: None

Example:

browser.http_proxy_var.set("http://proxy.example.com:8080")
browser.https_proxy_var.set("https://proxy.example.com:8080")
browser.set_proxy()

toggle_javascript()

Description: Enables or disables JavaScript execution.

Parameters: None (reads from javascript_var)

Returns: None

Example:

browser.javascript_var.set(True)
browser.toggle_javascript()

set_security_settings()

Description: Saves whitelist and blacklist settings.

Parameters: None (reads from whitelist_var and blacklist_var)

Returns: None

Example:

browser.whitelist_var.set("example.com, trusted.org")
browser.blacklist_var.set("malicious.com")
browser.set_security_settings()

update_navigation_controls()

Description: Enables/disables navigation buttons based on history state.

Parameters: None

Returns: None

Example:

browser.update_navigation_controls()

WebView Browser API

SimpleBrowser Class

Location: src/browsers/modern_browser.py

Description: Modern browser using native webview integration with cross-platform support.

__init__(root)

Description: Initialize the browser with Tkinter root window and webview.

Parameters:

  • root (tk.Tk): Tkinter root window

Returns: SimpleBrowser instance

Example:

import tkinter as tk
from src.browsers.modern_browser import SimpleBrowser

root = tk.Tk()
browser = SimpleBrowser(root)
root.mainloop()

Attributes:

  • history (list): Navigation history
  • current_index (int): Current position in history
  • webview_window: Native webview window instance

initialize_webview(url)

Description: Initializes the webview window with the given URL.

Parameters:

  • url (str): Initial URL to load

Returns: None

Example:

browser.initialize_webview("https://example.com")

load_into_webview(url)

Description: Loads a URL into the webview.

Parameters:

  • url (str): URL to load

Returns: None

Example:

browser.load_into_webview("https://example.com")

load_url(event=None)

Description: Loads a URL from the address bar.

Parameters:

  • event (tk.Event, optional): Event object. Defaults to None.

Returns: None

Example:

browser.url_entry.delete(0, tk.END)
browser.url_entry.insert(0, "example.com")
browser.load_url()

reload_page()

Description: Reloads the current page.

Parameters: None

Returns: None

Example:

browser.reload_page()

go_back()

Description: Navigates back in history.

Parameters: None

Returns: None

Example:

browser.go_back()

go_forward()

Description: Navigates forward in history.

Parameters: None

Returns: None

Example:

browser.go_forward()

go_home()

Description: Navigates to the home page.

Parameters: None

Returns: None

Example:

browser.go_home()

load_url_from_history()

Description: Loads the URL at the current history index.

Parameters: None

Returns: None

Example:

browser.load_url_from_history()

open_settings()

Description: Opens the settings window.

Parameters: None

Returns: None

Example:

browser.open_settings()

set_user_agent()

Description: Attempts to set custom user-agent (not supported in current PyWebView version).

Parameters: None

Returns: None

Example:

browser.set_user_agent()  # Prints limitation message

set_proxy()

Description: Configures proxy settings via environment variables.

Parameters: None (reads from proxy input fields)

Returns: None

Example:

browser.http_proxy_var.set("http://proxy.example.com:8080")
browser.set_proxy()

update_navigation_controls()

Description: Updates navigation button states based on history.

Parameters: None

Returns: None

Example:

browser.update_navigation_controls()

main()

Location: src/browsers/modern_browser.py

Description: Main function to launch the WebView browser.

Parameters: None

Returns: None

Example:

from src.browsers.modern_browser import main
main()

Search Operators Tool API

SearchOperatorsTool Class

Location: src/tools/search.py

Description: Advanced search query builder with support for various search operators.

__init__()

Description: Initialize the search operators tool with dark theme.

Parameters: None

Returns: SearchOperatorsTool instance

Example:

from src.tools.search import SearchOperatorsTool
tool = SearchOperatorsTool()
tool.show()

Attributes:

  • query_input (QLineEdit): Base search query input
  • site_checkbox (QCheckBox): Site filtering toggle
  • site_input (QLineEdit): Site domain input
  • title_checkbox (QCheckBox): Title filtering toggle
  • title_input (QLineEdit): Title text input
  • filetype_checkbox (QCheckBox): Filetype filtering toggle
  • filetype_input (QLineEdit): Filetype input
  • exclude_checkbox (QCheckBox): Exclusion toggle
  • exclude_input (QLineEdit): Words to exclude
  • custom_checkbox (QCheckBox): Custom operator toggle
  • custom_input (QLineEdit): Custom operator input
  • preview_output (QTextEdit): Query preview display

apply_dark_theme()

Description: Applies a dark theme with advanced colorization to the application.

Parameters: None

Returns: None

Example:

tool.apply_dark_theme()

add_search_query_section()

Description: Adds the search query input section to the UI.

Parameters: None

Returns: None

Example:

tool.add_search_query_section()

add_operator_options()

Description: Adds the search operator options section to the UI.

Parameters: None

Returns: None

Example:

tool.add_operator_options()

add_preview_and_actions()

Description: Adds the query preview and action buttons to the UI.

Parameters: None

Returns: None

Example:

tool.add_preview_and_actions()

generate_query()

Description: Generates the search query based on user inputs and selected operators.

Parameters: None

Returns: None (updates preview_output)

Example:

tool.query_input.setText("Python tutorial")
tool.site_checkbox.setChecked(True)
tool.site_input.setText("docs.python.org")
tool.generate_query()
# Result: "Python tutorial site:docs.python.org"

Supported Operators:

  • site: - Restrict search to specific domain
  • intitle: - Search for words in page title
  • filetype: - Search for specific file types
  • - - Exclude words from search
  • Custom operators

execute_search()

Description: Executes the generated search query using the default web browser.

Parameters: None

Returns: None

Example:

tool.generate_query()
tool.execute_search()  # Opens search in default browser

main()

Location: src/tools/search.py

Description: Main function to launch the search operators tool.

Parameters: None

Returns: None

Example:

from src.tools.search import main
main()

Developer Tools Integration API

Browser Class

Location: src/tools/dev_tools_integration.py

Description: Web browser with integrated developer tools dock.

Note: This class is designed to be used as a mixin or base class for other browser implementations.

__init__(*args, **kwargs)

Description: Initialize the browser with developer tools integration.

Parameters:

  • *args: Variable positional arguments
  • **kwargs: Variable keyword arguments

Returns: Browser instance

Example:

from src.tools.dev_tools_integration import Browser
from PyQt5.QtWidgets import QMainWindow

class MyBrowser(Browser, QMainWindow):
    def __init__(self):
        super().__init__()
        # Additional initialization

Attributes:

  • dev_tools_dock (QDockWidget): Dock widget for developer tools
  • dev_tools_area (QWebEngineView): WebEngineView displaying developer tools
  • current_tab_page (QWebEnginePage): Current webpage linked with dev tools

show_dev_tools()

Description: Shows the Developer Tools Dock.

Parameters: None

Returns: None

Example:

browser.show_dev_tools()

create_navigation_bar()

Description: Modifies the navigation bar to add a Developer Tools button.

Parameters: None

Returns: None

Note: This method should be called after the navigation bar is created by the parent class.

Example:

browser.create_navigation_bar()

Module Exports

src/__init__.py

Exports:

  • Browser from src.browsers.hope
  • SecureBrowser from src.browsers.secure_browser
  • ModernBrowser from src.browsers.modern_browser

Example:

from src import Browser, SecureBrowser, ModernBrowser

src/browsers/__init__.py

Exports:

  • Browser from hope.py
  • SecureBrowser from secure_browser.py
  • ModernBrowser from modern_browser.py

Example:

from src.browsers import Browser, SecureBrowser, ModernBrowser

src/tools/__init__.py

Exports:

  • SearchOperatorsTool from search.py

Example:

from src.tools import SearchOperatorsTool

Type Definitions

URL Type

Description: URL string or QUrl object

Valid Formats:

History Type

Description: List of URLs representing navigation history

Format:

history = [
    "https://example.com/page1",
    "https://example.com/page2",
    "https://example.com/page3"
]

Settings Type

Description: Dictionary containing browser settings

Format:

settings = {
    "vpn": bool,
    "javascript": bool,
    "proxy": str,
    "user_agent": str,
    "whitelist": list,
    "blacklist": list
}

Error Handling

Common Exceptions

URL Validation Error

Description: Invalid URL format

Handling: Browser displays "Invalid URL" in URL bar

Example:

# In PyQt5 browser
if not QUrl(url).isValid():
    self.url_bar.setText("Invalid URL")

Loading Error

Description: Error loading webpage

Handling: Browser displays error message in HTML frame

Example:

# In Tkinter browser
except Exception as e:
    error_message = f"<h1>Error loading {url}</h1><p>{str(e)}</p>"
    self.html_frame.set_html(error_message)

WebView Initialization Error

Description: Error initializing webview

Handling: Prints error message to console

Example:

# In WebView browser
except Exception as e:
    print(f"Error initializing WebView: {e}")

Constants

Default URLs

Security Headers

SECURITY_HEADERS = {
    "X-Content-Type-Options": "nosniff",
    "X-Frame-Options": "DENY",
    "Content-Security-Policy": "default-src 'self'; script-src 'self'; object-src 'none';"
}

UI Dimensions

  • PyQt5 Browser Window: 1280x720
  • PyQt5 Settings Dialog: 400x300
  • Search Tool Window: 800x600
  • WebView Browser Window: 900x650
  • Tkinter Settings Window: 400x600

Event Signals

PyQt5 Browser Signals

  • urlChanged.connect(callback): Fired when URL changes
  • titleChanged.connect(callback): Fired when page title changes
  • tabCloseRequested.connect(callback): Fired when tab close is requested

Tkinter Browser Events

  • <Return>: URL bar enter key press
  • <Double-Button-1>: Bookmark double-click

Configuration File Format

user_settings.json

{
    "home_url": "https://search.brave.com/",
    "proxy": {
        "http": "",
        "https": ""
    },
    "javascript_enabled": true,
    "vpn_enabled": false,
    "user_agent": "default",
    "whitelist": [],
    "blacklist": [],
    "bookmarks": []
}

Clone this wiki locally