0
# Proxy Configuration
1
2
Classes for configuring HTTP proxies to work around IP blocking by YouTube. Includes generic proxy support and specialized integration with Webshare residential proxies.
3
4
## Capabilities
5
6
### Base Proxy Configuration
7
8
Abstract base class defining the proxy configuration interface. All concrete proxy configs inherit from this class.
9
10
```python { .api }
11
class ProxyConfig:
12
def to_requests_dict(self):
13
"""
14
Convert to requests library proxy format.
15
16
Returns:
17
RequestsProxyConfigDict: Dictionary with 'http' and 'https' keys
18
19
Raises:
20
NotImplementedError: Must be implemented by subclasses
21
"""
22
23
@property
24
def prevent_keeping_connections_alive(self):
25
"""
26
Whether to prevent keeping TCP connections alive.
27
28
Returns:
29
bool: True if connections should be closed after each request
30
"""
31
32
@property
33
def retries_when_blocked(self):
34
"""
35
Number of retries when requests are blocked.
36
37
Returns:
38
int: Number of retry attempts
39
"""
40
```
41
42
### Generic Proxy Configuration
43
44
Configuration for any HTTP/HTTPS/SOCKS proxy. Supports both HTTP and HTTPS proxies with automatic fallback.
45
46
```python { .api }
47
class GenericProxyConfig(ProxyConfig):
48
def __init__(self, http_url=None, https_url=None):
49
"""
50
Configure generic HTTP/HTTPS proxy.
51
52
Args:
53
http_url (str, optional): Proxy URL for HTTP requests
54
https_url (str, optional): Proxy URL for HTTPS requests
55
56
Raises:
57
InvalidProxyConfig: Neither http_url nor https_url provided
58
59
Note:
60
If only one URL is provided, it will be used for both HTTP and HTTPS.
61
Supports HTTP, HTTPS, and SOCKS proxies as per requests library format.
62
"""
63
64
def to_requests_dict(self):
65
"""
66
Convert to requests proxy dictionary.
67
68
Returns:
69
RequestsProxyConfigDict: Proxy configuration for requests library
70
"""
71
72
@property
73
def http_url(self):
74
"""str: HTTP proxy URL"""
75
76
@property
77
def https_url(self):
78
"""str: HTTPS proxy URL"""
79
```
80
81
### Webshare Proxy Configuration
82
83
Specialized configuration for Webshare residential proxies with rotating IP addresses. Optimized for working around YouTube's IP blocking.
84
85
```python { .api }
86
class WebshareProxyConfig(GenericProxyConfig):
87
DEFAULT_DOMAIN_NAME = "p.webshare.io"
88
DEFAULT_PORT = 80
89
90
def __init__(self, proxy_username, proxy_password, filter_ip_locations=None,
91
retries_when_blocked=10, domain_name=DEFAULT_DOMAIN_NAME,
92
proxy_port=DEFAULT_PORT):
93
"""
94
Configure Webshare residential proxy with IP rotation.
95
96
Args:
97
proxy_username (str): Webshare proxy username
98
proxy_password (str): Webshare proxy password
99
filter_ip_locations (List[str], optional): Country codes to filter IPs
100
retries_when_blocked (int, optional): Retry attempts when blocked. Defaults to 10
101
domain_name (str, optional): Webshare domain. Defaults to "p.webshare.io"
102
proxy_port (int, optional): Proxy port. Defaults to 80
103
104
Note:
105
Requires Webshare "Residential" proxy package, not "Proxy Server" or "Static Residential".
106
Free tier uses "Proxy Server" and will not work reliably.
107
"""
108
109
@property
110
def url(self):
111
"""str: Complete proxy URL with rotation and location filtering"""
112
113
@property
114
def http_url(self):
115
"""str: HTTP proxy URL"""
116
117
@property
118
def https_url(self):
119
"""str: HTTPS proxy URL"""
120
121
@property
122
def prevent_keeping_connections_alive(self):
123
"""bool: Always True for rotating proxies to ensure IP rotation"""
124
125
@property
126
def retries_when_blocked(self):
127
"""int: Number of retry attempts when blocked"""
128
129
@property
130
def proxy_username(self):
131
"""str: Webshare proxy username"""
132
133
@property
134
def proxy_password(self):
135
"""str: Webshare proxy password"""
136
137
@property
138
def domain_name(self):
139
"""str: Webshare domain name"""
140
141
@property
142
def proxy_port(self):
143
"""int: Proxy port number"""
144
```
145
146
### Exceptions
147
148
Exception classes for proxy configuration errors.
149
150
```python { .api }
151
class InvalidProxyConfig(Exception):
152
"""
153
Raised when proxy configuration is invalid.
154
155
Args:
156
message (str): Error description
157
"""
158
```
159
160
## Usage Examples
161
162
### Generic Proxy Setup
163
164
```python
165
from youtube_transcript_api import YouTubeTranscriptApi
166
from youtube_transcript_api.proxies import GenericProxyConfig
167
168
# HTTP proxy only
169
proxy_config = GenericProxyConfig(http_url='http://proxy.example.com:8080')
170
171
# HTTPS proxy only
172
proxy_config = GenericProxyConfig(https_url='https://proxy.example.com:8080')
173
174
# Different proxies for HTTP and HTTPS
175
proxy_config = GenericProxyConfig(
176
http_url='http://http-proxy.example.com:8080',
177
https_url='https://https-proxy.example.com:8080'
178
)
179
180
# Use with API
181
api = YouTubeTranscriptApi(proxy_config=proxy_config)
182
transcript = api.fetch('dQw4w9WgXcQ')
183
```
184
185
### SOCKS Proxy Configuration
186
187
```python
188
from youtube_transcript_api import YouTubeTranscriptApi
189
from youtube_transcript_api.proxies import GenericProxyConfig
190
191
# SOCKS5 proxy
192
proxy_config = GenericProxyConfig(
193
http_url='socks5://proxy.example.com:1080',
194
https_url='socks5://proxy.example.com:1080'
195
)
196
197
# SOCKS5 with authentication
198
proxy_config = GenericProxyConfig(
199
http_url='socks5://username:password@proxy.example.com:1080',
200
https_url='socks5://username:password@proxy.example.com:1080'
201
)
202
203
api = YouTubeTranscriptApi(proxy_config=proxy_config)
204
transcript = api.fetch('dQw4w9WgXcQ')
205
```
206
207
### Webshare Residential Proxies
208
209
```python
210
from youtube_transcript_api import YouTubeTranscriptApi
211
from youtube_transcript_api.proxies import WebshareProxyConfig
212
213
# Basic Webshare configuration
214
proxy_config = WebshareProxyConfig(
215
proxy_username='your_username',
216
proxy_password='your_password'
217
)
218
219
# With country filtering and custom retry count
220
proxy_config = WebshareProxyConfig(
221
proxy_username='your_username',
222
proxy_password='your_password',
223
filter_ip_locations=['US', 'CA', 'GB'],
224
retries_when_blocked=15
225
)
226
227
# With custom domain and port
228
proxy_config = WebshareProxyConfig(
229
proxy_username='your_username',
230
proxy_password='your_password',
231
domain_name='custom.webshare.io',
232
proxy_port=8080
233
)
234
235
api = YouTubeTranscriptApi(proxy_config=proxy_config)
236
transcript = api.fetch('dQw4w9WgXcQ')
237
```
238
239
### Error Handling with Proxies
240
241
```python
242
from youtube_transcript_api import YouTubeTranscriptApi
243
from youtube_transcript_api.proxies import GenericProxyConfig, InvalidProxyConfig
244
from youtube_transcript_api import RequestBlocked, IpBlocked
245
246
try:
247
# Invalid proxy configuration
248
proxy_config = GenericProxyConfig() # No URLs provided
249
except InvalidProxyConfig as e:
250
print(f"Invalid proxy config: {e}")
251
252
try:
253
proxy_config = GenericProxyConfig(http_url='http://proxy.example.com:8080')
254
api = YouTubeTranscriptApi(proxy_config=proxy_config)
255
transcript = api.fetch('dQw4w9WgXcQ')
256
except RequestBlocked as e:
257
print(f"Request blocked despite proxy: {e}")
258
# The error message will include proxy-specific guidance
259
except IpBlocked as e:
260
print(f"IP blocked: {e}")
261
```
262
263
### Proxy with Custom HTTP Client
264
265
```python
266
from youtube_transcript_api import YouTubeTranscriptApi
267
from youtube_transcript_api.proxies import GenericProxyConfig
268
import requests
269
270
# Create custom session with proxy
271
proxy_config = GenericProxyConfig(http_url='http://proxy.example.com:8080')
272
session = requests.Session()
273
274
# Apply proxy configuration manually if needed
275
session.proxies.update(proxy_config.to_requests_dict())
276
session.timeout = 30
277
278
# Pass both proxy config and custom session
279
api = YouTubeTranscriptApi(proxy_config=proxy_config, http_client=session)
280
transcript = api.fetch('dQw4w9WgXcQ')
281
```
282
283
### Testing Proxy Configuration
284
285
```python
286
from youtube_transcript_api.proxies import GenericProxyConfig, WebshareProxyConfig
287
288
# Test proxy configuration format
289
generic_config = GenericProxyConfig(http_url='http://proxy:8080')
290
proxy_dict = generic_config.to_requests_dict()
291
print(f"Generic proxy config: {proxy_dict}")
292
293
webshare_config = WebshareProxyConfig('user', 'pass', filter_ip_locations=['US'])
294
webshare_dict = webshare_config.to_requests_dict()
295
print(f"Webshare proxy config: {webshare_dict}")
296
print(f"Webshare URL: {webshare_config.url}")
297
print(f"Retries when blocked: {webshare_config.retries_when_blocked}")
298
print(f"Close connections: {webshare_config.prevent_keeping_connections_alive}")
299
```
300
301
## Types
302
303
```python { .api }
304
from typing import TypedDict, Optional, List
305
306
class RequestsProxyConfigDict(TypedDict):
307
"""
308
Proxy configuration dictionary for requests library.
309
310
Attributes:
311
http (str): HTTP proxy URL
312
https (str): HTTPS proxy URL
313
"""
314
http: str
315
https: str
316
317
# Union type for all proxy configurations
318
ProxyConfig = Union[GenericProxyConfig, WebshareProxyConfig]
319
```