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