[🚀 Feature]: More documentation and examples for `by.py`

[Andre-Medina]

Feature and motivation

Hi all, I've been using Selenium for a few months now. It's amazing, keep up the great work.

I was considering contributing by adding some documentation into the code itself. Particularly to the following classes:

• py/selenium/webdriver/remote/webdriver.py to WebDriver.find_element
• py/selenium/webdriver/common/by.py to By

I found these are some of the major components for interacting with webpages and there only documentation on selenium.dev which is a bit out of the way. I thinking adding some examples for when different By conditions into the code itself would be best. E.g. By.ID vs By.CSS_SELECTOR.

This documentation will definitely help beginners who are used to python side documentation in their IDE.

Usage example

Replicate Documation found on "https://www.selenium.dev/documentation/webdriver/elements/locators/" to the files in py/selenium/...

[github-actions]

@Andre-Medina, thank you for creating this issue. We will troubleshoot it as soon as we can.

---

Info for maintainers

Triage this issue by using labels.

If information is missing, add a helpful comment and then I-issue-template label.

If the issue is a question, add the I-question label.

If the issue is valid but there is no time to troubleshoot it, consider adding the help wanted label.

If the issue requires changes or fixes from an external project (e.g., ChromeDriver, GeckoDriver, MSEdgeDriver, W3C), add the applicable G-* label, and it will provide the correct link and auto-close the issue.

After troubleshooting the issue, please add the R-awaiting answer label.

Thank you!

[shbenzer]

How are you suggesting these comments be added if not in Selenium.dev? As docstrings?

[Andre-Medina]

Yes, in the class docstring, so they can work with interpreters like pylance.

E.g. this description

Comes from the class docstring

would be very helpful to have some examples and pretty standard across other python packages. For example, in the python package polars, the add method has the following description:

Which again, comes from the package itself:

[shbenzer]

I don't have an issue with this. @AutomatedTester @p0deje thoughts?

[p0deje]

No objections, let's add those!

[shbenzer]

@Andre-Medina We would love for you to contribute to this cause, thank you in advance!

[Andre-Medina]

Okay thanks all, I should have some time this week.

Edit: all good found CONTRIBUTING.md

[p0deje]

You’d normally fork and send PR from there.