Merge branch 'main' of https://github.com/brightdata/bright-data-sdk-python

Author: עידן וילנסקי

README.md

@@ -1,10 +1,11 @@
 
 <img width="1300" height="200" alt="sdk-banner(1)" src="https://github.com/user-attachments/assets/c4a7857e-10dd-420b-947a-ed2ea5825cb8" />
 
-<h3 align="center">A Python SDK for the Bright Data's Data extraction and Web unlocking tools, providing easy-to-use scalable methods for web scraping, web searches and more.</h3>
-
-
-For a quick start you can try to run our example files in this repositories under the "Codespace" section.
+```python
+pip install brightdata-sdk
+```
+<h3 align="center">Python SDK by Bright Data, providing easy-to-use scalable methods for web search & scraping</h3>
+<p></p>
 
 ## Features
 
@@ -18,58 +19,37 @@ For a quick start you can try to run our example files in this repositories unde
 
 ## Installation
 To install the package, open your terminal:
-> [!NOTE]
-> If you are using macOS you will need to open a virtual environment for your project first.
 
-```bash
+```python
 pip install brightdata-sdk
 ```
+> If using macOS, first open a virtual environment for your project
 
 ## Quick Start
 
+Create a [Bright Data](https://brightdata.com/) account and copy your API key
+
 ### 1. Initialize the Client
-> [!IMPORTANT]
-> Go to your [**account settings**](https://brightdata.com/cp/setting/users), to verify that your API key have **"admin permissions"**.
 
 ```python
 from brightdata import bdclient
 
 client = bdclient(api_token="your_api_token_here") # can also be defined as BRIGHTDATA_API_TOKEN in your .env file
 ```
 
-Or you can use a custom zone name
+Or you can configure a custom zone name
+
 ```python
 client = bdclient(
     api_token="your_token",
     auto_create_zones=False,          # Else it creates the Zone automatically
-    web_unlocker_zone="custom_zone",  # Custom zone name for web scraping
-    serp_zone="custom_serp_zone"      # Custom zone name for search requests
+    web_unlocker_zone="custom_zone",
+    serp_zone="custom_serp_zone"
 )
-```
-> [!TIP]
-> Hover over the "bdclient" (or over each function in the package) with your cursor to see all its available parameters.
-
 
-### 2. Scrape Websites
-
-```python
-# Single URL
-result = client.scrape("https://example.com")
-
-# Multiple URLs (parallel processing)
-urls = ["https://example1.com", "https://example2.com", "https://example3.com"]
-results = client.scrape(urls)
-
-# Custom options
-result = client.scrape(
-    "https://example.com",
-    format="raw",
-    country="gb",
-    data_format="screenshot"
-)
 ```
 
-### 3. Search Engine Results
+### 2. Search Engine Results
 
 ```python
 # Single search query
@@ -90,51 +70,56 @@ results = client.search(
 )
 ```
 
-### 4. Download Content
+> [!TIP]
+> Hover over the "search" or each function in the package, to see all its available parameters.
 
-```python
-# Download scraped content
-data = client.scrape("https://example.com")
-client.download_content(data, "results.json", "json") # Auto-generate filename if not specified
-```
+![Hover-Over1](https://github.com/user-attachments/assets/51324485-5769-48d5-8f13-0b534385142e)
 
-## Configuration
+### 3. Scrape Websites
 
-### Environment Variables
+```python
+# Single URL
+result = client.scrape("https://example.com")
 
-Create a `.env` file in your project root:
+# Multiple URLs (parallel processing)
+urls = ["https://example1.com", "https://example2.com", "https://example3.com"]
+results = client.scrape(urls)
 
-```env
-BRIGHTDATA_API_TOKEN=your_bright_data_api_token
-WEB_UNLOCKER_ZONE=your_web_unlocker_zone  # Optional
-SERP_ZONE=your_serp_zone                  # Optional
+# Custom options
+result = client.scrape(
+    "https://example.com",
+    format="raw",
+    country="gb",
+    data_format="screenshot"
+)
 ```
 
-### Manage Zones
+### 4. Download Content
 
 ```python
-# List all active zones
-zones = client.list_zones()
-print(f"Found {len(zones)} zones")
+# Download scraped content
+data = client.scrape("https://example.com")
+client.download_content(data) 
 ```
 
-## API Reference
-
-### bdclient Class
+## Function Parameters
+<details>
+    <summary>🔍 <strong>Search(...)</strong></summary>
+    
+Searches using the SERP API. Accepts the same arguments as scrape(), plus:
 
 ```python
-bdclient(
-    api_token: str = None,
-    auto_create_zones: bool = True,
-    web_unlocker_zone: str = None,
-    serp_zone: str = None,
-)
+- `query`: Search query string or list of queries
+- `search_engine`: "google", "bing", or "yandex"
+- Other parameters same as scrape()
 ```
+    
+</details>
+<details>
+    <summary>🔗 <strong>scrape(...)</strong></summary>
 
-### Key Methods
-
-#### scrape(...)
 Scrapes a single URL or list of URLs using the Web Unlocker.
+
 ```python
 - `url`: Single URL string or list of URLs
 - `zone`: Zone identifier (auto-configured if None)
@@ -147,48 +132,23 @@ Scrapes a single URL or list of URLs using the Web Unlocker.
 - `timeout`: Request timeout in seconds (default: 30)
 ```
 
-#### search(...)
-Searches using the SERP API. Accepts the same arguments as scrape(), plus:
-```python
-- `query`: Search query string or list of queries
-- `search_engine`: "google", "bing", or "yandex"
-- Other parameters same as scrape()
-```
-
-#### download_content(...)
+</details>
+<details>
+    <summary>💾 <strong>Download_Content(...)</strong></summary>
 
 Save content to local file.
+
 ```python
 - `content`: Content to save
 - `filename`: Output filename (auto-generated if None)
 - `format`: File format ("json", "csv", "txt", etc.)
 ```
 
-#### list_zones()
-
-List all active zones in your Bright Data account.
+</details>
+<details>
+    <summary>⚙️ <strong>Configuration Constants</strong></summary>
 
-## Error Handling
-
-The SDK includes built-in input validation and retry logic:
-```python
-try:
-    result = client.scrape("https://example.com")
-except ValueError as e:
-    print(f"Invalid input: {e}")
-except Exception as e:
-    print(f"API error: {e}")
-```
-
-## Production Features
-
-- **Retry Logic**: Automatic retries with exponential backoff for network failures
-- **Input Validation**: Validates URLs, zone names, and parameters
-- **Connection Pooling**: Efficient HTTP connection management
-- **Logging**: Comprehensive logging for debugging and monitoring
-- **Zone Auto-Creation**: Automatically creates required zones if they don't exist
-
-## Configuration Constants
+<p></p>
 
 | Constant               | Default | Description                     |
 | ---------------------- | ------- | ------------------------------- |
@@ -198,27 +158,59 @@ except Exception as e:
 | `MAX_RETRIES`          | `3`     | Retry attempts on failure       |
 | `RETRY_BACKOFF_FACTOR` | `1.5`   | Exponential backoff multiplier  |
 
-## Getting Your API Token
-
-1. Sign up at [brightdata.com](https://brightdata.com/), and navigate to your dashboard
-2. Create or access your API credentials
-3. Copy your API token and paste it in your .env or code file
+</details>
 
-## Development
+##  Advanced Configuration
 
-For development installation, open your terminal:
+<details>
+    <summary>🔧 <strong>Environment Variables</strong></summary>
 
-```bash
-git clone https://github.com/brightdata/bright-data-sdk-python.git
+Create a `.env` file in your project root:
 
-# If you are using Mac you will need to open a virtual environment for your project first.
-cd bright-data-sdk-python
-pip install .
+```env
+BRIGHTDATA_API_TOKEN=your_bright_data_api_token
+WEB_UNLOCKER_ZONE=your_web_unlocker_zone  # Optional
+SERP_ZONE=your_serp_zone                  # Optional
 ```
 
-## License
+</details>
+<details>
+    <summary>🌐 <strong>Manage Zones</strong></summary>
+
+List all active zones
+
+```python
+# List all active zones
+zones = client.list_zones()
+print(f"Found {len(zones)} zones")
+```
 
-This project is licensed under the MIT License.
+</details>
+<details>
+    <summary>👥 <strong>Client Management</strong></summary>
+    
+bdclient Class
+    
+```python
+bdclient(
+    api_token: str = None,
+    auto_create_zones: bool = True,
+    web_unlocker_zone: str = None,
+    serp_zone: str = None,
+)
+```
+    
+</details>
+<details>
+    <summary>⚠️ <strong>Error Handling</strong></summary>
+    
+bdclient Class
+    
+The SDK includes built-in input validation and retry logic
+
+In case of zone related problems, use the **list_zones()** function to check your active zones, and check that your [**account settings**](https://brightdata.com/cp/setting/users), to verify that your API key have **"admin permissions"**.
+    
+</details>
 
 ## Support