AGENTS.md

1<!-- Guidance for AI agents working in Selenium Python Bindings -->
2 
3## Code location
4 
5- Package: `py/selenium/`
6- Remote/transport: `py/selenium/webdriver/remote/`
7 
8## Common commands
9 
10- Build: `bazel build //py/...`
11 
12## Testing
13 
14Run tests via `bazel test //py/...`. See `/AGENTS.md` for toolchain details.
15 
16## Testing
17 
18Run tests via `bazel test //py:test-{browser}` or `bazel test //py:test-{browser}-bidi`, where `{browser}` is the target browser (e.g., `chrome`, `firefox`, `edge`). See `/AGENTS.md` for toolchain details.
19 
20## Code conventions
21 
22### Logging
23 
24```python
25logger = logging.getLogger(__name__)
26 
27logger.warning("actionable: something needs attention")
28logger.info("useful: driver started successfully")
29logger.debug("diagnostic: request payload for debugging")
30```
31 
32### Deprecation
33 
34```python
35warnings.warn(
36    "old_method is deprecated, use new_method instead",
37    DeprecationWarning,
38    stacklevel=2
39)
40```
41 
42### Type hints
43 
44Type hints are used throughout; add type annotations to new code
45 
46Use union notation (`|`) instead of `Optional`:
47 
48```python
49# Preferred
50def method(param: str | None) -> int | None:
51    pass
52 
53# Avoid
54def method(param: Optional[str]) -> Optional[int]:
55    pass
56```
57 
58### Python version
59 
60Code must work with Python 3.10 or later. Use modern syntax features available in 3.10+:
61 
62- Use `|` for union types instead of `Union[]`
63- Use `X | None` instead of `Optional[X]`
64 
65When running tests or code in the terminal, explicitly use `python3.10` or later:
66 
67```bash
68# Use explicitly
69python3.10 -c &quot;...&quot;
70python3.11 -c &quot;...&quot;
71 
72# Avoid relying on `python3` as it may be 3.9 or earlier
73```
74 
75### Documentation
76 
77Use Google-style docstrings:
78 
79```python
80def method(param: str) -> bool:
81    """Brief description.
82 
83    Args:
84        param: Description of param.
85 
86    Returns:
87        Description of return value.
88 
89    Raises:
90        ValueError: When condition.
91    """
92```
93