Skip to content

[py] Add missing modules to Python API docs #15624

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 13, 2025

Conversation

cgoldberg
Copy link
Contributor

@cgoldberg cgoldberg commented Apr 13, 2025

User description

🔗 Related Issues

Fixes: #15623

💥 What does this PR do?

This PR updates the Python API documentation to include modules that were missing.

In py/docs/source/api.rst, all the Python modules in the selenium package are listed. Sphinx uses this file to generate the docs from source code docstrings. This file needs to be updated anytime a new module is added or removed from the Python package.

It hasn't been updated in a while, and the following modules were missing:

selenium.webdriver.common.bidi.browser
selenium.webdriver.common.bidi.common
selenium.webdriver.common.bidi.network
selenium.webdriver.common.fedcm.account
selenium.webdriver.common.fedcm.dialog

selenium.webdriver.remote.client_config
selenium.webdriver.remote.fedcm
selenium.webdriver.remote.locator_converter

I also rearranged some of the modules so they are in correct alphabetical order.


For future reference, here is the code I used to find all the modules in the package (run this from the ./py directory:

#!/usr/bin/env python3
#
# Find all modules in a package without importing the package.
# Returns a list of module names.
# This will work for a package installed in `site-packages` or read from source.
#
# Requires Python 3.9+

import importlib.util
import os
import site


def get_modules(package_name):
    try:
        mod_paths = importlib.util.find_spec(package_name).submodule_search_locations
    except AttributeError:
        raise Exception("package not found")
    modules = [package_name]
    for mod_path in mod_paths:
        path = mod_path if "site-packages" in mod_path else package_name
        for dirpath, _, filenames in os.walk(path):
            for filename in filenames:
                if filename.endswith(".py") and not filename.startswith("__"):
                    module_name = (
                        os.path.join(dirpath, filename)
                        .removeprefix(site.getsitepackages()[0])
                        .removeprefix(os.sep)
                        .removesuffix(".py")
                        .replace(os.sep, ".")
                    )
                    modules.append(module_name)
    return sorted(set(modules))


if __name__ == "__main__":
    modules = get_modules("selenium")
    for module in modules:
        if "devtools" not in module:
            print(f"   {module}")

🔄 Types of changes

  • Bug fix (backwards compatible)

PR Type

Documentation, Bug fix


Description

  • Added missing Python modules to API documentation.

  • Rearranged modules in alphabetical order for consistency.

  • Corrected placement of Webdriver.wpewebkit section in documentation.


Changes walkthrough 📝

Relevant files
Documentation
api.rst
Update and organize Python API documentation                         

py/docs/source/api.rst

  • Added missing modules to the Python API documentation.
  • Rearranged modules alphabetically for better organization.
  • Corrected the placement of Webdriver.wpewebkit section.
  • Updated Sphinx directives for accurate documentation generation.
  • +34/-26 

    Need help?
  • Type /help how to ... in the comments thread for any questions about Qodo Merge usage.
  • Check out the documentation for more information.
  • @selenium-ci selenium-ci added the C-py Python Bindings label Apr 13, 2025
    @qodo-merge-pro qodo-merge-pro bot added Review effort 2/5 and removed C-py Python Bindings labels Apr 13, 2025
    Copy link
    Contributor

    PR Reviewer Guide 🔍

    Here are some key observations to aid the review process:

    ⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
    🧪 No relevant tests
    🔒 No security concerns identified
    ⚡ No major issues detected

    Copy link
    Contributor

    PR Code Suggestions ✨

    No code suggestions found for the PR.

    @cgoldberg
    Copy link
    Contributor Author

    The 2 CI failures are due to #15584 and are unrelated to this PR.

    @cgoldberg cgoldberg merged commit 35c4323 into SeleniumHQ:trunk Apr 13, 2025
    19 of 20 checks passed
    @cgoldberg cgoldberg deleted the py-docs-missing-modules branch April 13, 2025 17:20
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Projects
    None yet
    Development

    Successfully merging this pull request may close these issues.

    [🐛 Bug]: [py] The API docs are missing some modules
    2 participants