[py] Improve docstrings in generated BiDi modules#17392
Open
AutomatedTester wants to merge 4 commits intotrunkfrom
Open
[py] Improve docstrings in generated BiDi modules#17392AutomatedTester wants to merge 4 commits intotrunkfrom
AutomatedTester wants to merge 4 commits intotrunkfrom
Conversation
selenium-ci
added
C-py
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the Python BiDi codegen pipeline to support richer docstrings (via the enhancements manifest) and to generate additional BiDi-adjacent modules by merging multiple WebRef CDDL specs.
Changes:
- Add docstring formatting helpers and manifest-driven docstring injection to the BiDi generator.
- Merge multiple CDDL inputs during Bazel generation and expand the set of generated module outputs.
- Extend BiDi permissions tests to cover the new
embedded_originkeyword-only API behavior.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
py/generate_bidi.py |
Adds manifest-driven docstring handling and removes the bespoke permissions file generator. |
py/private/bidi_enhancements_manifest.py |
Provides new module/class/command docstrings and a custom Permissions.set_permission(..., *, embedded_origin=None) method. |
py/private/generate_bidi.bzl |
Extends the Bazel rule to merge extra CDDL inputs and declares additional generated module outputs. |
py/private/merge_cddl.py |
New helper tool to concatenate multiple CDDL files into a single generator input. |
py/private/BUILD.bazel |
Exposes merge_cddl.py as a Bazel py_binary for use by the generation rule. |
py/BUILD.bazel |
Wires extra WebRef CDDL specs into the BiDi generation target and configures the merge tool. |
py/test/selenium/webdriver/common/bidi_permissions_tests.py |
Adds regression/behavior tests for embedded_origin being keyword-only and accepted when passed by keyword. |
AutomatedTester
force-pushed
the
improve-bidi-docstrings
branch
from
a942e0f to
3c18960
Compare
AutomatedTester
force-pushed
the
improve-bidi-docstrings
branch
from
3c18960 to
df63f3b
Compare
Add three new manifest keys to the generator so end users get meaningful help() output and IDE hover docs for the new BiDi modules: - module_docstring: file-level triple-quoted string after imports - class_docstrings: per-class docstring override (dataclasses and enums) - command_docstrings: per-command method docstring override Continuation lines are automatically re-indented to match the enclosing block depth (4 spaces for class body, 8 for method body). Fallback docstrings (class name only) retain the trailing period they had before. Populate content for all four new modules: - permissions: module doc, PermissionState and Permissions class docs - bluetooth: module doc, 6 key dataclass docs, 13 command method docs - speculation: module doc, PreloadingStatus and PrefetchStatusUpdatedParameters docs - userAgentClientHints: module doc, ClientHintsMetadata and BrandVersion docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
AutomatedTester
force-pushed
the
improve-bidi-docstrings
branch
from
df63f3b to
5cd1644
Compare
AutomatedTester
changed the title
- Remove unused MODULE_HEADER constant (superseded by _MODULE_HEADER_COMMENTS + _MODULE_HEADER_IMPORTS) - Move enhancements normalisation before first .get() call to prevent AttributeError when generate_code() is called with enhancements=None Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The _emit_docstring docstring contained escaped backslash sequences which ruff flags as D301. Adding the r prefix satisfies the rule. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds manifest-driven docstring support to the BiDi code generator so end users get meaningful
help()output and IDE hover docs for generated modules.Changes
py/generate_bidi.py_docstring_text()+_emit_docstring()_emit_docstring()produces correct PEP 257 layout: opening/closing triple-quotes on their own lines for multi-line strings; inline for single-linemodule_docstringis now emitted beforefrom __future__ import annotationsso it becomes the real module__doc__module_docstring,class_docstrings,command_docstringspy/private/bidi_enhancements_manifest.pypermissions,bluetooth,speculation,userAgentClientHints)