Put the Session conventions in the Session docstring - #13
Merged
Merged
Conversation
The rules for calling an action -- keyword-only, snake_case after the browser's own names, `selector` winning over `backend_node_id`, `call` as the escape hatch, `ToolError` on failure -- were a fixed paragraph in the docs site's reference generator. They describe this class, so they belong on it: IDE hover and `help()` show them now, and they stay next to the code they describe instead of drifting in another repository. `AsyncSession` points at `Session` rather than repeating them. Part of #6.
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
1 participant
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.
Item 2 of #6.
The rules for calling an action live in the docs site's reference generator, as a fixed
CONVENTIONSlist plus aCLASS_NOTES["Session"]entry with hand-written#session-callanchors. They describe this class, so a reader in an IDE never sees them, and a repository that cannot import the package decides what the package promises.They move to the
Sessiondocstring: keyword-only methods named in snake_case after the browser's own action names,selectorwinning overbackend_node_idwhen both are given,callas the escape hatch that takes the browser's own names, andToolErroron failure.help(Session)and hover text carry them now.AsyncSessionrefers toSessionrather than repeating the text, which is what the generated page already says about the twin.The matching removal is lightpanda-io/docs#112. The
:meth:roles resolve to the same anchors the hardcoded links spelled out —[call()](#session-call),[tree()](#session-tree),[find_element()](#session-find-element)— so the rendered page keeps its links; the paragraphs just move from above the class list into theSessionsection, where they apply.Leaves items 1 (return shapes) open on #6. That one is worth doing after lightpanda-io/browser#3694 lands, since
outputSchemathen tellsgenerate_methods.pywhich tools return the mergedPageResultwithout a hand-maintained list.