Skip to content

Commit 8612183

Browse files
thalissonvsthalissonvs
committed
docs: refactor docs folder structure
1 parent cdd415f commit 8612183

File tree

116 files changed

+18252
-1
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

116 files changed

+18252
-1
lines changed

‎mkdocs.yml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ site_url: https://pydoll.tech/docs/
33
repo_url: https://github.com/autoscrape-labs/pydoll
44
repo_name: autoscrape-labs/pydoll
55
use_directory_urls: true
6+
docs_dir: public/docs
67

78
# Configuração da navegação
89
nav:
@@ -84,7 +85,7 @@ theme:
8485
icon:
8586
repo: fontawesome/brands/github
8687
logo: material/lightning-bolt
87-
favicon: images/favicon.png
88+
favicon: ./images/favicon.png
8889
features:
8990
- navigation.tabs
9091
- navigation.tabs.sticky

‎public/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

‎public/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

‎public/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.

‎public/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

‎public/docs/api/browser/requests.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Browser Requests
2+
3+
The requests module provides HTTP request capabilities within the browser context, enabling seamless API calls that inherit the browser's session state, cookies, and authentication.
4+
5+
## Overview
6+
7+
The browser requests module offers a `requests`-like interface for making HTTP calls directly within the browser's JavaScript context. This approach provides several advantages over traditional HTTP libraries:
8+
9+
- **Session inheritance**: Automatic cookie, authentication, and CORS handling
10+
- **Browser context**: Requests execute in the same security context as the page
11+
- **No session juggling**: Eliminate the need to transfer cookies and tokens between automation and API calls
12+
- **SPA compatibility**: Perfect for Single Page Applications with complex authentication flows
13+
14+
## Request Class
15+
16+
The main interface for making HTTP requests within the browser context.
17+
18+
::: pydoll.browser.requests.request.Request
19+
options:
20+
show_root_heading: true
21+
show_source: false
22+
heading_level: 3
23+
group_by_category: true
24+
members_order: source
25+
filters:
26+
- "!^__"
27+
28+
## Response Class
29+
30+
Represents the response from HTTP requests, providing a familiar interface similar to the `requests` library.
31+
32+
::: pydoll.browser.requests.response.Response
33+
options:
34+
show_root_heading: true
35+
show_source: false
36+
heading_level: 3
37+
group_by_category: true
38+
members_order: source
39+
filters:
40+
- "!^__"
41+
42+
## Usage Examples
43+
44+
### Basic HTTP Methods
45+
46+
```python
47+
from pydoll.browser.chromium import Chrome
48+
49+
async with Chrome() as browser:
50+
tab = await browser.start()
51+
await tab.go_to("https://api.example.com")
52+
53+
# GET request
54+
response = await tab.request.get("/users/123")
55+
user_data = await response.json()
56+
57+
# POST request
58+
response = await tab.request.post("/users", json={
59+
"name": "John Doe",
60+
"email": "[email protected]"
61+
})
62+
63+
# PUT request with headers
64+
response = await tab.request.put("/users/123",
65+
json={"name": "Jane Doe"},
66+
headers={"Authorization": "Bearer token123"}
67+
)
68+
```
69+
70+
### Response Handling
71+
72+
```python
73+
# Check response status
74+
if response.ok:
75+
print(f"Success: {response.status_code}")
76+
else:
77+
print(f"Error: {response.status_code}")
78+
response.raise_for_status() # Raises HTTPError for 4xx/5xx
79+
80+
# Access response data
81+
text_data = response.text
82+
json_data = await response.json()
83+
raw_bytes = response.content
84+
85+
# Inspect headers and cookies
86+
print("Response headers:", response.headers)
87+
print("Request headers:", response.request_headers)
88+
for cookie in response.cookies:
89+
print(f"Cookie: {cookie.name}={cookie.value}")
90+
```
91+
92+
### Advanced Features
93+
94+
```python
95+
# Request with custom headers and parameters
96+
response = await tab.request.get("/search",
97+
params={"q": "python", "limit": 10},
98+
headers={
99+
"User-Agent": "Custom Bot 1.0",
100+
"Accept": "application/json"
101+
}
102+
)
103+
104+
# File upload simulation
105+
response = await tab.request.post("/upload",
106+
data={"description": "Test file"},
107+
files={"file": ("test.txt", "file content", "text/plain")}
108+
)
109+
110+
# Form data submission
111+
response = await tab.request.post("/login",
112+
data={"username": "user", "password": "pass"}
113+
)
114+
```
115+
116+
## Integration with Tab
117+
118+
The request functionality is accessed through the `tab.request` property, which provides a singleton `Request` instance for each tab:
119+
120+
```python
121+
# Each tab has its own request instance
122+
tab1 = await browser.get_tab(0)
123+
tab2 = await browser.new_tab()
124+
125+
# These are separate Request instances
126+
request1 = tab1.request # Request bound to tab1
127+
request2 = tab2.request # Request bound to tab2
128+
129+
# Requests inherit the tab's context
130+
await tab1.go_to("https://site1.com")
131+
await tab2.go_to("https://site2.com")
132+
133+
# These requests will have different cookie/session contexts
134+
response1 = await tab1.request.get("/api/data") # Uses site1.com cookies
135+
response2 = await tab2.request.get("/api/data") # Uses site2.com cookies
136+
```
137+
138+
!!! tip "Hybrid Automation"
139+
This module is particularly powerful for hybrid automation scenarios where you need to combine UI interactions with API calls. For example, log in through the UI, then use the authenticated session for API calls without manually handling cookies or tokens.

‎public/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

‎public/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.

‎public/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_text()`, and `get_attribute()` which use these commands internally.

0 commit comments

Comments
 (0)