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