Skip to main content

eggfetch_python/
lib.rs

1//! Python bindings for eggfetch.
2
3use pyo3::prelude::*;
4
5mod async_client;
6mod auth;
7mod client;
8mod conversion;
9mod cookies;
10mod errors;
11mod extensions;
12mod headers;
13mod limits;
14mod multipart;
15mod network_stream;
16mod proxy;
17mod request_preparation;
18mod response;
19mod retry;
20mod streaming;
21mod timeout;
22mod tls;
23mod trace_bridge;
24
25use async_client::PyAsyncClient;
26use auth::{PyBasicAuth, PyBearerAuth, PyNoAuth};
27use client::PyClient;
28use cookies::PyCookies;
29use errors::map_err;
30use headers::PyHeaders;
31use limits::PyLimits;
32use multipart::PyFile;
33use response::PyResponse;
34use retry::PyRetry;
35use streaming::{
36    PyAsyncBytesIterator, PyAsyncLinesIterator, PyAsyncRawBytesIterator, PyAsyncTextIterator,
37    PyBytesChunkIterator, PyLinesChunkIterator, PyRawBytesChunkIterator, PyStreamingResponse,
38    PyTextChunkIterator,
39};
40use timeout::PyTimeout;
41
42/// Send an HTTP request using a short-lived client.
43///
44/// Args:
45///     method: HTTP method string.
46///     url: Target URL.
47///     headers: Request headers dict or sequence of pairs (optional).
48///     params: Query parameters dict or sequence of pairs (optional).
49///     content: Raw request body as bytes (optional).
50///     data: Form data as dict or sequence of pairs (optional).
51///     json: JSON-serializable object (optional).
52///     files: File uploads as mapping or sequence of pairs (optional).
53///     timeout: Request timeout in seconds, or Timeout object (optional).
54///     cookies: Initial cookies as dict of name=value pairs (optional).
55///     auth: Authentication credentials (optional).
56///     `follow_redirects`: Whether to follow redirects (default False).
57///     `max_redirects`: Maximum redirects to follow (default 20).
58#[pyfunction]
59#[pyo3(signature = (method, url, *, headers=None, params=None, content=None, data=None, json=None, files=None, timeout=None, cookies=None, auth=None, follow_redirects=None, max_redirects=None, decompress=None, proxy=None, verify=None, cert=None, retries=None, limits=None))]
60#[allow(clippy::too_many_arguments, clippy::too_many_lines)]
61fn request<'py>(
62    py: Python<'py>,
63    method: &str,
64    url: &str,
65    headers: Option<&Bound<'py, PyAny>>,
66    params: Option<&Bound<'py, PyAny>>,
67    content: Option<&Bound<'py, PyAny>>,
68    data: Option<&Bound<'py, PyAny>>,
69    json: Option<&Bound<'py, PyAny>>,
70    files: Option<&Bound<'py, PyAny>>,
71    timeout: Option<&Bound<'py, PyAny>>,
72    cookies: Option<&Bound<'py, PyAny>>,
73    auth: Option<&Bound<'py, PyAny>>,
74    follow_redirects: Option<bool>,
75    max_redirects: Option<usize>,
76    decompress: Option<bool>,
77    proxy: Option<&Bound<'py, PyAny>>,
78    verify: Option<&Bound<'py, PyAny>>,
79    cert: Option<&Bound<'py, PyAny>>,
80    retries: Option<&Bound<'py, PyAny>>,
81    limits: Option<&Bound<'py, PyAny>>,
82) -> PyResult<Bound<'py, PyAny>> {
83    let prepared = request_preparation::prepare_request(
84        py,
85        method,
86        url,
87        headers,
88        params,
89        content,
90        data,
91        json,
92        files,
93        timeout,
94        cookies,
95        auth,
96        follow_redirects,
97        max_redirects,
98        proxy,
99        retries,
100        None,
101        false,
102    )?;
103
104    let runtime = tokio::runtime::Runtime::new()
105        .map_err(|e| PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(e.to_string()))?;
106
107    let tls_config = tls::build_tls_config(verify, cert, None)?;
108
109    let mut client_builder = eggfetch_core::Client::builder()
110        .redirect_policy(eggfetch_core::redirect::RedirectPolicy::new(
111            follow_redirects.unwrap_or(false),
112            max_redirects.unwrap_or(20),
113        ))
114        .tls_config(tls_config);
115
116    if let Some(l) = limits {
117        let py_limits: PyLimits = l.extract()?;
118        client_builder = client_builder.limits(py_limits.inner);
119    }
120
121    let client = client_builder.build();
122    let dispatch = request_preparation::prepare_core_dispatch(
123        &client,
124        prepared,
125        request_preparation::RequestDispatchDefaults {
126            redirect_policy: eggfetch_core::redirect::RedirectPolicy::new(
127                follow_redirects.unwrap_or(false),
128                max_redirects.unwrap_or(20),
129            ),
130            decompress,
131        },
132    )?;
133    let builder = dispatch.builder;
134
135    let result = py.detach(|| {
136        runtime.block_on(async {
137            let mut response = Box::pin(builder.send()).await.map_err(map_err)?;
138            let content = response.bytes().await.map_err(map_err)?;
139            Ok::<_, PyErr>((response, content))
140        })
141    });
142
143    let (mut response, content) = result?;
144    // The top-level short-lived helpers do not own a persistent runtime,
145    // so the network stream (if any) gets no explicit handle or lease.
146    let py_response =
147        PyResponse::from_core_response_with_body(&mut response, content, None, None, false)?;
148    Ok(Py::new(py, py_response)?.into_bound(py).into_any())
149}
150
151/// Send a GET request using a short-lived client.
152#[pyfunction]
153#[pyo3(signature = (url, *, headers=None, params=None, timeout=None, cookies=None, auth=None, follow_redirects=None, max_redirects=None, decompress=None, proxy=None, verify=None, cert=None, retries=None, limits=None))]
154#[allow(clippy::too_many_arguments)]
155fn get<'py>(
156    py: Python<'py>,
157    url: &str,
158    headers: Option<&Bound<'py, PyAny>>,
159    params: Option<&Bound<'py, PyAny>>,
160    timeout: Option<&Bound<'py, PyAny>>,
161    cookies: Option<&Bound<'py, PyAny>>,
162    auth: Option<&Bound<'py, PyAny>>,
163    follow_redirects: Option<bool>,
164    max_redirects: Option<usize>,
165    decompress: Option<bool>,
166    proxy: Option<&Bound<'py, PyAny>>,
167    verify: Option<&Bound<'py, PyAny>>,
168    cert: Option<&Bound<'py, PyAny>>,
169    retries: Option<&Bound<'py, PyAny>>,
170    limits: Option<&Bound<'py, PyAny>>,
171) -> PyResult<Bound<'py, PyAny>> {
172    request(
173        py,
174        "GET",
175        url,
176        headers,
177        params,
178        None,
179        None,
180        None,
181        None,
182        timeout,
183        cookies,
184        auth,
185        follow_redirects,
186        max_redirects,
187        decompress,
188        proxy,
189        verify,
190        cert,
191        retries,
192        limits,
193    )
194}
195
196/// Send a POST request using a short-lived client.
197#[pyfunction]
198#[pyo3(signature = (url, *, headers=None, params=None, content=None, data=None, json=None, files=None, timeout=None, cookies=None, auth=None, follow_redirects=None, max_redirects=None, decompress=None, proxy=None, verify=None, cert=None, retries=None, limits=None))]
199#[allow(clippy::too_many_arguments)]
200fn post<'py>(
201    py: Python<'py>,
202    url: &str,
203    headers: Option<&Bound<'py, PyAny>>,
204    params: Option<&Bound<'py, PyAny>>,
205    content: Option<&Bound<'py, PyAny>>,
206    data: Option<&Bound<'py, PyAny>>,
207    json: Option<&Bound<'py, PyAny>>,
208    files: Option<&Bound<'py, PyAny>>,
209    timeout: Option<&Bound<'py, PyAny>>,
210    cookies: Option<&Bound<'py, PyAny>>,
211    auth: Option<&Bound<'py, PyAny>>,
212    follow_redirects: Option<bool>,
213    max_redirects: Option<usize>,
214    decompress: Option<bool>,
215    proxy: Option<&Bound<'py, PyAny>>,
216    verify: Option<&Bound<'py, PyAny>>,
217    cert: Option<&Bound<'py, PyAny>>,
218    retries: Option<&Bound<'py, PyAny>>,
219    limits: Option<&Bound<'py, PyAny>>,
220) -> PyResult<Bound<'py, PyAny>> {
221    request(
222        py,
223        "POST",
224        url,
225        headers,
226        params,
227        content,
228        data,
229        json,
230        files,
231        timeout,
232        cookies,
233        auth,
234        follow_redirects,
235        max_redirects,
236        decompress,
237        proxy,
238        verify,
239        cert,
240        retries,
241        limits,
242    )
243}
244
245/// Send a PUT request using a short-lived client.
246#[pyfunction]
247#[pyo3(signature = (url, *, headers=None, params=None, content=None, data=None, json=None, files=None, timeout=None, cookies=None, auth=None, follow_redirects=None, max_redirects=None, decompress=None, proxy=None, verify=None, cert=None, retries=None, limits=None))]
248#[allow(clippy::too_many_arguments)]
249fn put<'py>(
250    py: Python<'py>,
251    url: &str,
252    headers: Option<&Bound<'py, PyAny>>,
253    params: Option<&Bound<'py, PyAny>>,
254    content: Option<&Bound<'py, PyAny>>,
255    data: Option<&Bound<'py, PyAny>>,
256    json: Option<&Bound<'py, PyAny>>,
257    files: Option<&Bound<'py, PyAny>>,
258    timeout: Option<&Bound<'py, PyAny>>,
259    cookies: Option<&Bound<'py, PyAny>>,
260    auth: Option<&Bound<'py, PyAny>>,
261    follow_redirects: Option<bool>,
262    max_redirects: Option<usize>,
263    decompress: Option<bool>,
264    proxy: Option<&Bound<'py, PyAny>>,
265    verify: Option<&Bound<'py, PyAny>>,
266    cert: Option<&Bound<'py, PyAny>>,
267    retries: Option<&Bound<'py, PyAny>>,
268    limits: Option<&Bound<'py, PyAny>>,
269) -> PyResult<Bound<'py, PyAny>> {
270    request(
271        py,
272        "PUT",
273        url,
274        headers,
275        params,
276        content,
277        data,
278        json,
279        files,
280        timeout,
281        cookies,
282        auth,
283        follow_redirects,
284        max_redirects,
285        decompress,
286        proxy,
287        verify,
288        cert,
289        retries,
290        limits,
291    )
292}
293
294/// Send a PATCH request using a short-lived client.
295#[pyfunction]
296#[pyo3(signature = (url, *, headers=None, params=None, content=None, data=None, json=None, files=None, timeout=None, cookies=None, auth=None, follow_redirects=None, max_redirects=None, decompress=None, proxy=None, verify=None, cert=None, retries=None, limits=None))]
297#[allow(clippy::too_many_arguments)]
298fn patch<'py>(
299    py: Python<'py>,
300    url: &str,
301    headers: Option<&Bound<'py, PyAny>>,
302    params: Option<&Bound<'py, PyAny>>,
303    content: Option<&Bound<'py, PyAny>>,
304    data: Option<&Bound<'py, PyAny>>,
305    json: Option<&Bound<'py, PyAny>>,
306    files: Option<&Bound<'py, PyAny>>,
307    timeout: Option<&Bound<'py, PyAny>>,
308    cookies: Option<&Bound<'py, PyAny>>,
309    auth: Option<&Bound<'py, PyAny>>,
310    follow_redirects: Option<bool>,
311    max_redirects: Option<usize>,
312    decompress: Option<bool>,
313    proxy: Option<&Bound<'py, PyAny>>,
314    verify: Option<&Bound<'py, PyAny>>,
315    cert: Option<&Bound<'py, PyAny>>,
316    retries: Option<&Bound<'py, PyAny>>,
317    limits: Option<&Bound<'py, PyAny>>,
318) -> PyResult<Bound<'py, PyAny>> {
319    request(
320        py,
321        "PATCH",
322        url,
323        headers,
324        params,
325        content,
326        data,
327        json,
328        files,
329        timeout,
330        cookies,
331        auth,
332        follow_redirects,
333        max_redirects,
334        decompress,
335        proxy,
336        verify,
337        cert,
338        retries,
339        limits,
340    )
341}
342
343/// Send a DELETE request using a short-lived client.
344#[pyfunction]
345#[pyo3(signature = (url, *, headers=None, params=None, timeout=None, cookies=None, auth=None, follow_redirects=None, max_redirects=None, decompress=None, proxy=None, verify=None, cert=None, retries=None, limits=None))]
346#[allow(clippy::too_many_arguments)]
347fn delete<'py>(
348    py: Python<'py>,
349    url: &str,
350    headers: Option<&Bound<'py, PyAny>>,
351    params: Option<&Bound<'py, PyAny>>,
352    timeout: Option<&Bound<'py, PyAny>>,
353    cookies: Option<&Bound<'py, PyAny>>,
354    auth: Option<&Bound<'py, PyAny>>,
355    follow_redirects: Option<bool>,
356    max_redirects: Option<usize>,
357    decompress: Option<bool>,
358    proxy: Option<&Bound<'py, PyAny>>,
359    verify: Option<&Bound<'py, PyAny>>,
360    cert: Option<&Bound<'py, PyAny>>,
361    retries: Option<&Bound<'py, PyAny>>,
362    limits: Option<&Bound<'py, PyAny>>,
363) -> PyResult<Bound<'py, PyAny>> {
364    request(
365        py,
366        "DELETE",
367        url,
368        headers,
369        params,
370        None,
371        None,
372        None,
373        None,
374        timeout,
375        cookies,
376        auth,
377        follow_redirects,
378        max_redirects,
379        decompress,
380        proxy,
381        verify,
382        cert,
383        retries,
384        limits,
385    )
386}
387
388/// Send a HEAD request using a short-lived client.
389#[pyfunction]
390#[pyo3(signature = (url, *, headers=None, params=None, timeout=None, cookies=None, auth=None, follow_redirects=None, max_redirects=None, decompress=None, proxy=None, verify=None, cert=None, retries=None, limits=None))]
391#[allow(clippy::too_many_arguments)]
392fn head<'py>(
393    py: Python<'py>,
394    url: &str,
395    headers: Option<&Bound<'py, PyAny>>,
396    params: Option<&Bound<'py, PyAny>>,
397    timeout: Option<&Bound<'py, PyAny>>,
398    cookies: Option<&Bound<'py, PyAny>>,
399    auth: Option<&Bound<'py, PyAny>>,
400    follow_redirects: Option<bool>,
401    max_redirects: Option<usize>,
402    decompress: Option<bool>,
403    proxy: Option<&Bound<'py, PyAny>>,
404    verify: Option<&Bound<'py, PyAny>>,
405    cert: Option<&Bound<'py, PyAny>>,
406    retries: Option<&Bound<'py, PyAny>>,
407    limits: Option<&Bound<'py, PyAny>>,
408) -> PyResult<Bound<'py, PyAny>> {
409    request(
410        py,
411        "HEAD",
412        url,
413        headers,
414        params,
415        None,
416        None,
417        None,
418        None,
419        timeout,
420        cookies,
421        auth,
422        follow_redirects,
423        max_redirects,
424        decompress,
425        proxy,
426        verify,
427        cert,
428        retries,
429        limits,
430    )
431}
432
433/// Send an OPTIONS request using a short-lived client.
434#[pyfunction]
435#[pyo3(signature = (url, *, headers=None, params=None, timeout=None, cookies=None, auth=None, follow_redirects=None, max_redirects=None, decompress=None, proxy=None, verify=None, cert=None, retries=None, limits=None))]
436#[allow(clippy::too_many_arguments)]
437fn options<'py>(
438    py: Python<'py>,
439    url: &str,
440    headers: Option<&Bound<'py, PyAny>>,
441    params: Option<&Bound<'py, PyAny>>,
442    timeout: Option<&Bound<'py, PyAny>>,
443    cookies: Option<&Bound<'py, PyAny>>,
444    auth: Option<&Bound<'py, PyAny>>,
445    follow_redirects: Option<bool>,
446    max_redirects: Option<usize>,
447    decompress: Option<bool>,
448    proxy: Option<&Bound<'py, PyAny>>,
449    verify: Option<&Bound<'py, PyAny>>,
450    cert: Option<&Bound<'py, PyAny>>,
451    retries: Option<&Bound<'py, PyAny>>,
452    limits: Option<&Bound<'py, PyAny>>,
453) -> PyResult<Bound<'py, PyAny>> {
454    request(
455        py,
456        "OPTIONS",
457        url,
458        headers,
459        params,
460        None,
461        None,
462        None,
463        None,
464        timeout,
465        cookies,
466        auth,
467        follow_redirects,
468        max_redirects,
469        decompress,
470        proxy,
471        verify,
472        cert,
473        retries,
474        limits,
475    )
476}
477
478/// Register all exception types on the module.
479fn register_exceptions(m: &Bound<'_, PyModule>) -> PyResult<()> {
480    m.add("EggfetchError", m.py().get_type::<errors::EggfetchError>())?;
481    m.add("RequestError", m.py().get_type::<errors::RequestError>())?;
482    m.add("InvalidUrl", m.py().get_type::<errors::InvalidUrl>())?;
483    m.add(
484        "TimeoutException",
485        m.py().get_type::<errors::TimeoutException>(),
486    )?;
487    m.add("PoolTimeout", m.py().get_type::<errors::PoolTimeout>())?;
488    m.add(
489        "ConnectTimeout",
490        m.py().get_type::<errors::ConnectTimeout>(),
491    )?;
492    m.add("ReadTimeout", m.py().get_type::<errors::ReadTimeout>())?;
493    m.add("WriteTimeout", m.py().get_type::<errors::WriteTimeout>())?;
494    m.add("NetworkError", m.py().get_type::<errors::NetworkError>())?;
495    m.add("ProtocolError", m.py().get_type::<errors::ProtocolError>())?;
496    m.add("BodyError", m.py().get_type::<errors::BodyError>())?;
497    m.add(
498        "HTTPStatusError",
499        m.py().get_type::<errors::HTTPStatusError>(),
500    )?;
501    m.add(
502        "UnsupportedKwarg",
503        m.py().get_type::<errors::UnsupportedKwarg>(),
504    )?;
505    m.add(
506        "TooManyRedirects",
507        m.py().get_type::<errors::TooManyRedirects>(),
508    )?;
509    m.add(
510        "StreamConsumed",
511        m.py().get_type::<errors::StreamConsumed>(),
512    )?;
513    m.add("StreamClosed", m.py().get_type::<errors::StreamClosed>())?;
514    m.add(
515        "ResponseNotRead",
516        m.py().get_type::<errors::ResponseNotRead>(),
517    )?;
518    m.add(
519        "DecompressionError",
520        m.py().get_type::<errors::DecompressionError>(),
521    )?;
522    m.add(
523        "UnsupportedContentEncoding",
524        m.py().get_type::<errors::UnsupportedContentEncoding>(),
525    )?;
526    m.add("ProxyError", m.py().get_type::<errors::ProxyError>())?;
527    m.add(
528        "ProxyConnectError",
529        m.py().get_type::<errors::ProxyConnectError>(),
530    )?;
531    m.add(
532        "ProxyAuthError",
533        m.py().get_type::<errors::ProxyAuthError>(),
534    )?;
535    m.add(
536        "BodyNotReplayableForRetry",
537        m.py().get_type::<errors::BodyNotReplayableForRetry>(),
538    )?;
539    m.add(
540        "RetryBudgetExhausted",
541        m.py().get_type::<errors::RetryBudgetExhausted>(),
542    )?;
543    m.add(
544        "RetryNotConfigured",
545        m.py().get_type::<errors::RetryNotConfigured>(),
546    )?;
547    m.add("Http2Error", m.py().get_type::<errors::Http2Error>())?;
548    m.add("Http2GoAway", m.py().get_type::<errors::Http2GoAway>())?;
549    m.add(
550        "Http2StreamReset",
551        m.py().get_type::<errors::Http2StreamReset>(),
552    )?;
553    m.add(
554        "Http2FlowControlError",
555        m.py().get_type::<errors::Http2FlowControlError>(),
556    )?;
557    m.add("H3Error", m.py().get_type::<errors::H3Error>())?;
558    m.add(
559        "H3ConnectError",
560        m.py().get_type::<errors::H3ConnectError>(),
561    )?;
562    m.add(
563        "H3ProtocolError",
564        m.py().get_type::<errors::H3ProtocolError>(),
565    )?;
566    Ok(())
567}
568
569/// eggfetch - Python bindings for eggfetch.
570#[pymodule]
571fn _native(m: &Bound<'_, PyModule>) -> PyResult<()> {
572    m.add("__version__", env!("CARGO_PKG_VERSION"))?;
573
574    m.add_class::<PyAsyncClient>()?;
575    m.add_class::<PyClient>()?;
576    m.add_class::<cookies::PyCookie>()?;
577    m.add_class::<PyCookies>()?;
578    m.add_class::<PyHeaders>()?;
579    m.add_class::<PyResponse>()?;
580    m.add_class::<PyStreamingResponse>()?;
581    m.add_class::<PyBytesChunkIterator>()?;
582    m.add_class::<PyTextChunkIterator>()?;
583    m.add_class::<PyLinesChunkIterator>()?;
584    m.add_class::<PyRawBytesChunkIterator>()?;
585    m.add_class::<PyAsyncBytesIterator>()?;
586    m.add_class::<PyAsyncTextIterator>()?;
587    m.add_class::<PyAsyncLinesIterator>()?;
588    m.add_class::<PyAsyncRawBytesIterator>()?;
589    m.add_class::<PyTimeout>()?;
590    m.add_class::<PyBasicAuth>()?;
591    m.add_class::<PyBearerAuth>()?;
592    m.add_class::<PyNoAuth>()?;
593    m.add_class::<PyFile>()?;
594    m.add_class::<PyRetry>()?;
595    m.add_class::<PyLimits>()?;
596    m.add_class::<network_stream::PyNetworkStream>()?;
597    m.add_class::<network_stream::PyAsyncNetworkStream>()?;
598
599    // Create the NOAUTH singleton instance.
600    let noauth_obj = Py::new(m.py(), PyNoAuth)?;
601    m.add("NOAUTH", noauth_obj.bind(m.py()).clone())?;
602
603    register_exceptions(m)?;
604
605    m.add_function(wrap_pyfunction!(request, m)?)?;
606    m.add_function(wrap_pyfunction!(get, m)?)?;
607    m.add_function(wrap_pyfunction!(post, m)?)?;
608    m.add_function(wrap_pyfunction!(put, m)?)?;
609    m.add_function(wrap_pyfunction!(patch, m)?)?;
610    m.add_function(wrap_pyfunction!(delete, m)?)?;
611    m.add_function(wrap_pyfunction!(head, m)?)?;
612    m.add_function(wrap_pyfunction!(options, m)?)?;
613
614    // PyO3 automatically builds a module __all__ from every add/add_class
615    // call. The pure-Python eggfetch package owns the supported export
616    // contract, so do not expose a second contract from this private module.
617    m.delattr("__all__")?;
618
619    Ok(())
620}