Skip to content

Commit ad3201b

Browse files
thalissonvsthalissonvs
committed
docs: add documentation for browser classes and command modules
1 parent a33bced commit ad3201b

39 files changed

+4226
-2252
lines changed

‎docs/api/browser/chrome.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Chrome Browser
2+
3+
::: pydoll.browser.chromium.Chrome
4+
options:
5+
show_root_heading: true
6+
show_source: false
7+
heading_level: 2

‎docs/api/browser/edge.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Edge Browser
2+
3+
::: pydoll.browser.chromium.Edge
4+
options:
5+
show_root_heading: true
6+
show_source: false
7+
heading_level: 2

‎docs/api/browser/managers.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Browser Managers
2+
3+
The managers module provides specialized classes for managing different aspects of browser lifecycle and configuration.
4+
5+
## Overview
6+
7+
Browser managers handle specific responsibilities in browser automation:
8+
9+
::: pydoll.browser.managers
10+
options:
11+
show_root_heading: true
12+
show_source: false
13+
heading_level: 2
14+
filters:
15+
- "!^_"
16+
- "!^__"
17+
18+
## Manager Classes
19+
20+
### Browser Process Manager
21+
Manages the browser process lifecycle, including starting, stopping, and monitoring browser processes.
22+
23+
::: pydoll.browser.managers.browser_process_manager
24+
options:
25+
show_root_heading: true
26+
show_source: false
27+
heading_level: 3
28+
29+
### Browser Options Manager
30+
Handles browser configuration options and command-line arguments.
31+
32+
::: pydoll.browser.managers.browser_options_manager
33+
options:
34+
show_root_heading: true
35+
show_source: false
36+
heading_level: 3
37+
38+
### Proxy Manager
39+
Manages proxy configuration and authentication for browser instances.
40+
41+
::: pydoll.browser.managers.proxy_manager
42+
options:
43+
show_root_heading: true
44+
show_source: false
45+
heading_level: 3
46+
47+
### Temporary Directory Manager
48+
Handles creation and cleanup of temporary directories used by browser instances.
49+
50+
::: pydoll.browser.managers.temp_dir_manager
51+
options:
52+
show_root_heading: true
53+
show_source: false
54+
heading_level: 3
55+
56+
## Usage
57+
58+
Managers are typically used internally by browser classes like `Chrome` and `Edge`. They provide modular functionality that can be composed together:
59+
60+
```python
61+
from pydoll.browser.managers.proxy_manager import ProxyManager
62+
from pydoll.browser.managers.temp_dir_manager import TempDirManager
63+
64+
# Managers are used internally by browser classes
65+
# Direct usage is for advanced scenarios only
66+
proxy_manager = ProxyManager()
67+
temp_manager = TempDirManager()
68+
```
69+
70+
!!! note "Internal Usage"
71+
These managers are primarily used internally by the browser classes. Direct usage is recommended only for advanced scenarios or when extending the library.

‎docs/api/browser/options.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Browser Options
2+
3+
## ChromiumOptions
4+
5+
::: pydoll.browser.options.ChromiumOptions
6+
options:
7+
show_root_heading: true
8+
show_source: false
9+
heading_level: 3
10+
11+
## Options Interface
12+
13+
::: pydoll.browser.interfaces.Options
14+
options:
15+
show_root_heading: true
16+
show_source: false
17+
heading_level: 3
18+
19+
## BrowserOptionsManager Interface
20+
21+
::: pydoll.browser.interfaces.BrowserOptionsManager
22+
options:
23+
show_root_heading: true
24+
show_source: false
25+
heading_level: 3

‎docs/api/browser/tab.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Tab
2+
3+
::: pydoll.browser.tab.Tab
4+
options:
5+
show_root_heading: true
6+
show_source: false
7+
heading_level: 2

‎docs/api/commands/browser.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Browser Commands
2+
3+
Browser commands provide low-level control over browser instances and their configuration.
4+
5+
## Overview
6+
7+
The browser commands module handles browser-level operations such as version information, target management, and browser-wide settings.
8+
9+
::: pydoll.commands.browser_commands
10+
options:
11+
show_root_heading: true
12+
show_source: false
13+
heading_level: 2
14+
filters:
15+
- "!^_"
16+
- "!^__"
17+
18+
## Usage
19+
20+
Browser commands are typically used internally by browser classes to manage browser instances:
21+
22+
```python
23+
from pydoll.commands.browser_commands import get_version
24+
from pydoll.connection.connection_handler import ConnectionHandler
25+
26+
# Get browser version information
27+
connection = ConnectionHandler()
28+
version_info = await get_version(connection)
29+
```
30+
31+
## Available Commands
32+
33+
The browser commands module provides functions for:
34+
35+
- Getting browser version and user agent information
36+
- Managing browser targets (tabs, windows)
37+
- Controlling browser-wide settings and permissions
38+
- Handling browser lifecycle events
39+
40+
!!! note "Internal Usage"
41+
These commands are primarily used internally by the `Chrome` and `Edge` browser classes. Direct usage is recommended only for advanced scenarios.

‎docs/api/commands/dom.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# DOM Commands
2+
3+
DOM commands provide comprehensive functionality for interacting with the Document Object Model of web pages.
4+
5+
## Overview
6+
7+
The DOM commands module is one of the most important modules in Pydoll, providing all the functionality needed to find, interact with, and manipulate HTML elements on web pages.
8+
9+
::: pydoll.commands.dom_commands
10+
options:
11+
show_root_heading: true
12+
show_source: false
13+
heading_level: 2
14+
filters:
15+
- "!^_"
16+
- "!^__"
17+
18+
## Usage
19+
20+
DOM commands are used extensively by the `WebElement` class and element finding methods:
21+
22+
```python
23+
from pydoll.commands.dom_commands import query_selector, get_attributes
24+
from pydoll.connection.connection_handler import ConnectionHandler
25+
26+
# Find element and get its attributes
27+
connection = ConnectionHandler()
28+
node_id = await query_selector(connection, selector="#username")
29+
attributes = await get_attributes(connection, node_id=node_id)
30+
```
31+
32+
## Key Functionality
33+
34+
The DOM commands module provides functions for:
35+
36+
### Element Finding
37+
- `query_selector()` - Find single element by CSS selector
38+
- `query_selector_all()` - Find multiple elements by CSS selector
39+
- `get_document()` - Get the document root node
40+
41+
### Element Interaction
42+
- `click_element()` - Click on elements
43+
- `focus_element()` - Focus elements
44+
- `set_attribute_value()` - Set element attributes
45+
- `get_attributes()` - Get element attributes
46+
47+
### Element Information
48+
- `get_box_model()` - Get element positioning and dimensions
49+
- `describe_node()` - Get detailed element information
50+
- `get_outer_html()` - Get element HTML content
51+
52+
### DOM Manipulation
53+
- `remove_node()` - Remove elements from DOM
54+
- `set_node_value()` - Set element values
55+
- `request_child_nodes()` - Get child elements
56+
57+
!!! tip "High-Level APIs"
58+
While these commands provide powerful low-level access, most users should use the higher-level `WebElement` class methods like `click()`, `type()`, and `get_attribute()` which use these commands internally.

‎docs/api/commands/fetch.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Fetch Commands
2+
3+
Fetch commands provide advanced network request handling and interception capabilities using the Fetch API domain.
4+
5+
## Overview
6+
7+
The fetch commands module enables sophisticated network request management, including request modification, response interception, and authentication handling.
8+
9+
::: pydoll.commands.fetch_commands
10+
options:
11+
show_root_heading: true
12+
show_source: false
13+
heading_level: 2
14+
filters:
15+
- "!^_"
16+
- "!^__"
17+
18+
## Usage
19+
20+
Fetch commands are used for advanced network interception and request handling:
21+
22+
```python
23+
from pydoll.commands.fetch_commands import enable, request_paused, continue_request
24+
from pydoll.connection.connection_handler import ConnectionHandler
25+
26+
# Enable fetch domain
27+
connection = ConnectionHandler()
28+
await enable(connection, patterns=[{
29+
"urlPattern": "*",
30+
"requestStage": "Request"
31+
}])
32+
33+
# Handle paused requests
34+
async def handle_paused_request(request_id, request):
35+
# Modify request or continue as-is
36+
await continue_request(connection, request_id=request_id)
37+
```
38+
39+
## Key Functionality
40+
41+
The fetch commands module provides functions for:
42+
43+
### Request Interception
44+
- `enable()` - Enable fetch domain with patterns
45+
- `disable()` - Disable fetch domain
46+
- `continue_request()` - Continue intercepted requests
47+
- `fail_request()` - Fail requests with specific errors
48+
49+
### Request Modification
50+
- Modify request headers
51+
- Change request URLs
52+
- Alter request methods (GET, POST, etc.)
53+
- Modify request bodies
54+
55+
### Response Handling
56+
- `fulfill_request()` - Provide custom responses
57+
- `get_response_body()` - Get response content
58+
- Response header modification
59+
- Response status code control
60+
61+
### Authentication
62+
- `continue_with_auth()` - Handle authentication challenges
63+
- Basic authentication support
64+
- Custom authentication flows
65+
66+
## Advanced Features
67+
68+
### Pattern-Based Interception
69+
```python
70+
# Intercept specific URL patterns
71+
patterns = [
72+
{"urlPattern": "*/api/*", "requestStage": "Request"},
73+
{"urlPattern": "*.js", "requestStage": "Response"},
74+
{"urlPattern": "https://example.com/*", "requestStage": "Request"}
75+
]
76+
77+
await enable(connection, patterns=patterns)
78+
```
79+
80+
### Request Modification
81+
```python
82+
# Modify intercepted requests
83+
async def modify_request(request_id, request):
84+
# Add authentication header
85+
headers = request.headers.copy()
86+
headers["Authorization"] = "Bearer token123"
87+
88+
# Continue with modified headers
89+
await continue_request(
90+
connection,
91+
request_id=request_id,
92+
headers=headers
93+
)
94+
```
95+
96+
### Response Mocking
97+
```python
98+
# Mock API responses
99+
await fulfill_request(
100+
connection,
101+
request_id=request_id,
102+
response_code=200,
103+
response_headers=[
104+
{"name": "Content-Type", "value": "application/json"},
105+
{"name": "Access-Control-Allow-Origin", "value": "*"}
106+
],
107+
body='{"status": "success", "data": {"mocked": true}}'
108+
)
109+
```
110+
111+
### Authentication Handling
112+
```python
113+
# Handle authentication challenges
114+
await continue_with_auth(
115+
connection,
116+
request_id=request_id,
117+
auth_challenge_response={
118+
"response": "ProvideCredentials",
119+
"username": "user",
120+
"password": "pass"
121+
}
122+
)
123+
```
124+
125+
## Request Stages
126+
127+
Fetch commands can intercept requests at different stages:
128+
129+
| Stage | Description | Use Cases |
130+
|-------|-------------|-----------|
131+
| Request | Before request is sent | Modify headers, URL, method |
132+
| Response | After response received | Mock responses, modify content |
133+
134+
## Error Handling
135+
136+
```python
137+
# Fail requests with specific errors
138+
await fail_request(
139+
connection,
140+
request_id=request_id,
141+
error_reason="ConnectionRefused" # or "AccessDenied", "TimedOut", etc.
142+
)
143+
```
144+
145+
## Integration with Network Commands
146+
147+
Fetch commands work alongside network commands but provide more granular control:
148+
149+
- **Network Commands**: Broader network monitoring and control
150+
- **Fetch Commands**: Specific request/response interception and modification
151+
152+
!!! tip "Performance Considerations"
153+
Fetch interception can impact page loading performance. Use specific URL patterns and disable when not needed to minimize overhead.

0 commit comments

Comments
 (0)