[py] Use lazy imports in webdriver __init__.py

[titusfortner]

User description

Step 1 in getting Bazel Python to work for us instead of against us

💥 What does this PR do?

Replace eager imports of all browser modules in py/selenium/webdriver/__init__.py with lazy loading via __getattr__. This:

• Enables future modularization of the Bazel build
• Improves import performance for users who only use a subset of browsers

The public API is fully backwards compatible - all existing import patterns continue to work identically.

🔧 Implementation Notes

Uses Python's __getattr__ module-level function (PEP 562) to defer imports until attributes are actually accessed. This is the standard Python approach for lazy module loading.

💡 Additional Considerations

None - this is a drop-in replacement with no behavioral changes to the public API.

🔄 Types of changes

• New feature (non-breaking change which adds functionality and tests!)

---

PR Type

Enhancement

---

Description

• Replace eager imports with lazy loading via __getattr__

• Improves import performance for subset browser usage

• Enables future Bazel build modularization

• Maintains full backwards compatibility with public API

---

Diagram Walkthrough

flowchart LR
  A["Eager Imports<br/>All modules loaded<br/>at startup"] -->|"Replace with"| B["Lazy Import Mapping<br/>_LAZY_IMPORTS dict"]
  B -->|"__getattr__ function"| C["On-demand Loading<br/>Import when accessed"]
  C -->|"Result"| D["Faster startup<br/>Backwards compatible"]

Loading

File Walkthrough

Relevant files

Enhancement

__init__.py Convert eager imports to lazy loading mechanism                    py/selenium/webdriver/init.py Removed 24 eager import statements for browser modules and utilities Added importlib import for dynamic module loading Introduced _LAZY_IMPORTS dictionary mapping public names to module paths and attributes Implemented __getattr__ function to handle lazy loading on attribute access Added __dir__ function to support introspection of available attributes Preserved __all__ list for explicit public API exports +55/-30

---

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: ImportError not handled: The new lazy loader does not catch and re-raise importlib.import_module()/getattr() failures with additional actionable context, so missing optional modules will surface as raw import/attribute errors. Referred Code def __getattr__(name): if name in _LAZY_IMPORTS: module_path, attr_name = _LAZY_IMPORTS[name] module = importlib.import_module(module_path) return getattr(module, attr_name) raise AttributeError(f"module 'selenium.webdriver' has no attribute {name!r}") Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Potential detail leakage: Failures during lazy imports may propagate full internal module paths and stack traces to callers, which could be considered overly detailed for user-facing error handling depending on project policy. Referred Code def __getattr__(name): if name in _LAZY_IMPORTS: module_path, attr_name = _LAZY_IMPORTS[name] module = importlib.import_module(module_path) return getattr(module, attr_name) raise AttributeError(f"module 'selenium.webdriver' has no attribute {name!r}") Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Latest suggestions up to d3c78b6

Category	Suggestion	Impact
Possible issue	Restrict star-import public exports *Define all in py/selenium/webdriver/chrome/init.py to ensure from selenium.webdriver.chrome import only exports the public submodules, preventing the export of internal helpers. py/selenium/webdriver/chrome/init.py [18-32] import importlib _LAZY_SUBMODULES = ["options", "remote_connection", "service", "webdriver"] +__all__ = list(_LAZY_SUBMODULES) def __getattr__(name): if name in _LAZY_SUBMODULES: module = importlib.import_module(f".{name}", __name__) globals()[name] = module return module raise AttributeError(f"module {__name__!r} has no attribute {name!r}") def __dir__(): return sorted(_LAZY_SUBMODULES) Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies that __all__ should be defined to control import * behavior and maintain a clean public API, a practice that was overlooked in the new lazy-loading implementation for this and other similar __init__.py files.	Low
Learned best practice	Make lazy imports thread-safe Guard the lazy-import/caching path with a module-level lock and re-check globals() inside the lock to avoid races where multiple threads import and assign the same attribute concurrently. py/selenium/webdriver/init.py [88-99] +_LAZY_LOCK = threading.Lock() + + def __getattr__(name): if name in _LAZY_IMPORTS: - module_path, attr_name = _LAZY_IMPORTS[name] - module = importlib.import_module(module_path) - value = getattr(module, attr_name) - globals()[name] = value - return value + with _LAZY_LOCK: + if name in globals(): + return globals()[name] + module_path, attr_name = _LAZY_IMPORTS[name] + module = importlib.import_module(module_path) + value = getattr(module, attr_name) + globals()[name] = value + return value if name in _LAZY_SUBMODULES: - module = importlib.import_module(_LAZY_SUBMODULES[name]) - globals()[name] = module - return module + with _LAZY_LOCK: + if name in globals(): + return globals()[name] + module = importlib.import_module(_LAZY_SUBMODULES[name]) + globals()[name] = module + return module raise AttributeError(f"module 'selenium.webdriver' has no attribute {name!r}") Apply / Chat Suggestion importance[1-10]: 6 __ Why: Relevant best practice - Make lifecycle/concurrency-sensitive initialization robust and free of hidden side effects by using thread-safe, idempotent initialization patterns.	Low
	Centralize repeated lazy-import boilerplate Extract the repeated getattr/dir lazy-submodule boilerplate into a shared utility (e.g., selenium.webdriver._lazy) and reuse it in each package to avoid copy/paste divergence. py/selenium/webdriver/chrome/init.py [18-32] -import importlib +from selenium.webdriver._lazy import install_lazy_submodules + _LAZY_SUBMODULES = ["options", "remote_connection", "service", "webdriver"] +__getattr__, __dir__ = install_lazy_submodules(__name__, _LAZY_SUBMODULES) - -def __getattr__(name): - if name in _LAZY_SUBMODULES: - module = importlib.import_module(f".{name}", __name__) - globals()[name] = module - return module - raise AttributeError(f"module {__name__!r} has no attribute {name!r}") - - -def __dir__(): - return sorted(_LAZY_SUBMODULES) - Apply / Chat Suggestion importance[1-10]: 5 __ Why: Relevant best practice - Reduce duplication by centralizing shared behavior into a common helper instead of repeating the same logic across multiple modules.	Low
More

---

Previous suggestions

✅ Suggestions up to commit b98c7a6

Category	Suggestion	Impact
Incremental [*]	✅ Fix incomplete module introspection Suggestion Impact: The commit modified the same __dir__() return line, but it did not implement the suggested introspection fix (it removed the set() wrapping and did not add globals().keys()). code diff: def __dir__(): - return sorted(set(_LAZY_SUBMODULES)) + return sorted(_LAZY_SUBMODULES) Update dir() to include existing module attributes from globals() in addition to the lazy-loadable submodules to ensure correct introspection. py/selenium/webdriver/chrome/init.py [31-32] def __dir__(): - return sorted(set(_LAZY_SUBMODULES)) + return sorted(set(globals().keys()) | set(_LAZY_SUBMODULES)) [Suggestion processed] Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies that the __dir__ implementation is incomplete, as it omits attributes already present in the module's namespace, which harms introspection and developer tools.	Low
	Include real attributes in dir() Update dir() to include existing module attributes from globals() in addition to the lazy-loadable submodules to ensure correct introspection. py/selenium/webdriver/firefox/init.py [31-32] def __dir__(): - return sorted(set(_LAZY_SUBMODULES)) + return sorted(set(globals().keys()) | set(_LAZY_SUBMODULES)) Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies that the __dir__ implementation is incomplete, as it omits attributes already present in the module's namespace, which harms introspection and developer tools.	Low
	Prevent hidden cached attributes Update dir() to include existing module attributes from globals() in addition to the lazy-loadable submodules to ensure correct introspection. py/selenium/webdriver/safari/init.py [31-32] def __dir__(): - return sorted(set(_LAZY_SUBMODULES)) + return sorted(set(globals().keys()) | set(_LAZY_SUBMODULES)) Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies that the __dir__ implementation is incomplete, as it omits attributes already present in the module's namespace, which harms introspection and developer tools.	Low

Suggestions up to commit 81e764b

Category	Suggestion	Impact
Incremental [*]	Prevent dir-time NameError Define all before dir to prevent a potential NameError and include _LAZY_SUBMODULES in all for consistent API exposure. py/selenium/webdriver/init.py [102-106] +__all__ = sorted(set(_LAZY_IMPORTS.keys()) | set(_LAZY_SUBMODULES.keys())) + + def __dir__(): return sorted(set(__all__) | set(_LAZY_SUBMODULES.keys())) - -__all__ = sorted(_LAZY_IMPORTS.keys()) - Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a potential NameError due to the definition order of __dir__ and __all__, and it improves API consistency by including submodules in __all__.	Medium
	Control star-import exports Add all and dir to the init.py file to prevent leaking implementation details like importlib and _LAZY_SUBMODULES during wildcard imports. py/selenium/webdriver/chrome/init.py [18-28] import importlib _LAZY_SUBMODULES = ["options", "remote_connection", "service", "webdriver"] + +__all__ = list(_LAZY_SUBMODULES) def __getattr__(name): if name in _LAZY_SUBMODULES: module = importlib.import_module(f".{name}", __name__) globals()[name] = module return module raise AttributeError(f"module {__name__!r} has no attribute {name!r}") + +def __dir__(): + return sorted(set(__all__)) + Suggestion importance[1-10]: 6 __ Why: The suggestion correctly points out that implementation details are exposed via wildcard imports and proposes adding __all__ and __dir__ to create a cleaner and more consistent public API.	Low
	Limit wildcard import surface Add all and dir to the init.py file to prevent leaking implementation details like importlib and _LAZY_SUBMODULES during wildcard imports. py/selenium/webdriver/firefox/init.py [18-28] import importlib _LAZY_SUBMODULES = ["firefox_profile", "options", "remote_connection", "service", "webdriver"] + +__all__ = list(_LAZY_SUBMODULES) def __getattr__(name): if name in _LAZY_SUBMODULES: module = importlib.import_module(f".{name}", __name__) globals()[name] = module return module raise AttributeError(f"module {__name__!r} has no attribute {name!r}") + +def __dir__(): + return sorted(set(__all__)) + Suggestion importance[1-10]: 6 __ Why: The suggestion correctly points out that implementation details are exposed via wildcard imports and proposes adding __all__ and __dir__ to create a cleaner and more consistent public API.	Low

✅ Suggestions up to commit d758f36

Category	Suggestion	Impact
Possible issue	Normalize lazy-load lookup failures Wrap lazy-loading imports in try-except blocks to catch ImportError or AttributeError and raise a consistent AttributeError from the selenium.webdriver module. py/selenium/webdriver/init.py [88-99] def __getattr__(name): if name in _LAZY_IMPORTS: module_path, attr_name = _LAZY_IMPORTS[name] - module = importlib.import_module(module_path) - value = getattr(module, attr_name) + try: + module = importlib.import_module(module_path) + value = getattr(module, attr_name) + except (ImportError, AttributeError) as e: + raise AttributeError( + f"module 'selenium.webdriver' has no attribute {name!r}" + ) from e globals()[name] = value return value if name in _LAZY_SUBMODULES: - module = importlib.import_module(_LAZY_SUBMODULES[name]) + try: + module = importlib.import_module(_LAZY_SUBMODULES[name]) + except ImportError as e: + raise AttributeError( + f"module 'selenium.webdriver' has no attribute {name!r}" + ) from e globals()[name] = module return module raise AttributeError(f"module 'selenium.webdriver' has no attribute {name!r}") Suggestion importance[1-10]: 8 __ Why: This suggestion correctly identifies that the lazy loading implementation can leak ImportError exceptions, and proposes a robust solution to wrap them in a consistent AttributeError, which improves the user experience.	Medium
Incremental [*]	Make submodule imports package-relative Modify _LAZY_SUBMODULES to use package-relative paths and update the importlib.import_module call to use package=name for improved robustness when vendoring the library. py/selenium/webdriver/init.py [73-98] _LAZY_SUBMODULES = { - "chrome": "selenium.webdriver.chrome", - "chromium": "selenium.webdriver.chromium", - "common": "selenium.webdriver.common", - "edge": "selenium.webdriver.edge", - "firefox": "selenium.webdriver.firefox", - "ie": "selenium.webdriver.ie", - "remote": "selenium.webdriver.remote", - "safari": "selenium.webdriver.safari", - "support": "selenium.webdriver.support", - "webkitgtk": "selenium.webdriver.webkitgtk", - "wpewebkit": "selenium.webdriver.wpewebkit", + "chrome": ".chrome", + "chromium": ".chromium", + "common": ".common", + "edge": ".edge", + "firefox": ".firefox", + "ie": ".ie", + "remote": ".remote", + "safari": ".safari", + "support": ".support", + "webkitgtk": ".webkitgtk", + "wpewebkit": ".wpewebkit", } ... - module = importlib.import_module(_LAZY_SUBMODULES[name]) + module = importlib.import_module(_LAZY_SUBMODULES[name], package=__name__) globals()[name] = module return module Suggestion importance[1-10]: 7 __ Why: The suggestion correctly proposes using relative imports for robustness, which is a good practice, especially for a library like Selenium that might be vendored. This improves the maintainability and resilience of the new lazy-loading mechanism.	Medium
General	✅ Stabilize and de-duplicate introspection Suggestion Impact: The commit changed __dir__ from returning a concatenation of __all__ and globals() (which could include duplicates and be unstable) to returning a sorted, de-duplicated set. It also refactored __all__ to be derived from _LAZY_IMPORTS keys. However, __dir__ only unions __all__ with _LAZY_SUBMODULES keys (not explicitly adding _LAZY_IMPORTS keys as suggested), so the implementation differs from the proposed approach. code diff: def __dir__(): - return list(__all__) + list(globals().keys()) + return sorted(set(__all__) | set(_LAZY_SUBMODULES.keys())) -__all__ = [ - "ActionChains", - "Chrome", - "ChromeOptions", - "ChromeService", - "ChromiumEdge", - "DesiredCapabilities", - "Edge", - "EdgeOptions", - "EdgeService", - "Firefox", - "FirefoxOptions", - "FirefoxProfile", - "FirefoxService", - "Ie", - "IeOptions", - "IeService", - "Keys", - "Proxy", - "Remote", - "Safari", - "SafariOptions", - "SafariService", - "WPEWebKit", - "WPEWebKitOptions", - "WPEWebKitService", - "WebKitGTK", - "WebKitGTKOptions", - "WebKitGTKService", -] +__all__ = sorted(_LAZY_IMPORTS.keys()) Improve the dir implementation to include lazily imported symbols, remove duplicates, and return a sorted list of public names for stable introspection. py/selenium/webdriver/init.py [102-103] def __dir__(): - return list(__all__) + list(globals().keys()) + public = set(globals().get("__all__", ())) + public.update(_LAZY_IMPORTS.keys()) + public.update(_LAZY_SUBMODULES.keys()) + return sorted(public) [Suggestion processed] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies that the __dir__ implementation is incomplete and could produce duplicates. The proposed change correctly includes the lazily-imported names, which is crucial for introspection and autocompletion.	Medium

✅ Suggestions up to commit acfa8ca

Category	Suggestion	Impact
High-level	Add a type stub file The dynamic loading via getattr breaks static type checking and IDE autocompletion. To fix this, a type stub file (init.pyi) should be created to explicitly define the module's public API for these tools. Examples: py/selenium/webdriver/__init__.py [73-78] def __getattr__(name): if name in _LAZY_IMPORTS: module_path, attr_name = _LAZY_IMPORTS[name] module = importlib.import_module(module_path) return getattr(module, attr_name) raise AttributeError(f"module 'selenium.webdriver' has no attribute {name!r}") Solution Walkthrough: Before: # In py/selenium/webdriver/__init__.py _LAZY_IMPORTS = { "Chrome": ("selenium.webdriver.chrome.webdriver", "WebDriver"), # ... other lazy imports } def __getattr__(name): if name in _LAZY_IMPORTS: module = importlib.import_module(_LAZY_IMPORTS[name][0]) return getattr(module, _LAZY_IMPORTS[name][1]) raise AttributeError(...) # No __init__.pyi file exists. # Static analysis tools will report errors for attributes like `webdriver.Chrome`. After: # In py/selenium/webdriver/__init__.py (no changes) # ... (code with __getattr__ remains) # In py/selenium/webdriver/__init__.pyi (new file) from .chrome.webdriver import WebDriver as Chrome from .chrome.options import Options as ChromeOptions from .edge.webdriver import WebDriver as Edge from .firefox.webdriver import WebDriver as Firefox from .remote.webdriver import WebDriver as Remote from .common.action_chains import ActionChains from .common.keys import Keys # ... and so on for all public attributes. # Static analysis tools can now correctly resolve all attributes. Suggestion importance[1-10]: 9 __ Why: This suggestion correctly identifies a critical developer experience issue where using __getattr__ breaks static analysis, and proposes the standard, correct solution of adding a .pyi stub file.	High
Possible issue	✅ Cache lazy imports for performance Suggestion Impact: The commit updates __getattr__ to cache the lazily imported attribute in globals() before returning it, preventing repeated import/getattr work on subsequent accesses. code diff: @@ -74,7 +74,9 @@ if name in _LAZY_IMPORTS: module_path, attr_name = _LAZY_IMPORTS[name] module = importlib.import_module(module_path) - return getattr(module, attr_name) + value = getattr(module, attr_name) + globals()[name] = value + return value Optimize the getattr function by caching the lazy-loaded attributes in the module's globals(). This will prevent re-importing on every attribute access and improve performance. py/selenium/webdriver/init.py [73-78] def __getattr__(name): if name in _LAZY_IMPORTS: module_path, attr_name = _LAZY_IMPORTS[name] module = importlib.import_module(module_path) - return getattr(module, attr_name) + attr = getattr(module, attr_name) + globals()[name] = attr + return attr raise AttributeError(f"module 'selenium.webdriver' has no attribute {name!r}") [Suggestion processed] Suggestion importance[1-10]: 7 __ Why: This is a valid and important performance optimization for the new lazy-loading mechanism. Caching the imported attribute in globals() is a standard practice that prevents re-importing on every access, making subsequent lookups much faster.	Medium
General	✅ Avoid exposing internal module details Suggestion Impact: The commit removed the use of globals().keys() from __dir__, preventing exposure of internal module globals to introspection. Instead of returning only __all__ exactly, it returns a sorted union of __all__ and lazily importable submodule names. code diff: def __dir__(): - return list(__all__) + list(globals().keys()) + return sorted(set(__all__) | set(_LAZY_SUBMODULES.keys())) Modify the dir function to return only the all list. This will prevent exposing internal module details to introspection tools. py/selenium/webdriver/init.py [81-82] def __dir__(): - return list(__all__) + list(globals().keys()) + return __all__ Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies that including globals().keys() in __dir__ exposes internal implementation details. Returning only __all__ correctly lists the public API as intended, improving encapsulation and providing a cleaner interface for introspection.	Low

[Copilot]

Pull request overview

This PR replaces eager imports with lazy loading in the selenium/webdriver/__init__.py module to improve startup performance and enable future Bazel build modularization. The implementation uses Python's PEP 562 module-level __getattr__ to defer imports until attributes are accessed.

Changes:

• Removed 24 eager import statements for browser modules and utilities
• Added lazy import mechanism using __getattr__ with a _LAZY_IMPORTS dictionary mapping
• Maintained full backwards compatibility with the public API

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 8 comments.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 8 comments.

[qodo-code-review]

Persistent suggestions updated to latest commit d3c78b6

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.