nautilus_network/python/
mod.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Python bindings from [PyO3](https://pyo3.rs).
17
18// We need to allow `unexpected_cfgs` because the PyO3 macros internally check for
19// the `gil-refs` feature. We don’t define or enable `gil-refs` ourselves (due to a
20// memory leak), so the compiler raises an error about an unknown cfg feature.
21// This attribute prevents those errors without actually enabling `gil-refs`.
22#![allow(unexpected_cfgs)]
23#![expect(
24    clippy::missing_errors_doc,
25    reason = "errors documented on underlying Rust methods"
26)]
27#![allow(
28    clippy::implicit_hasher,
29    reason = "PyO3 bindings receive concrete HashMap from Python and cannot be generic over hasher"
30)]
31#![allow(
32    clippy::trivially_copy_pass_by_ref,
33    reason = "PyO3 methods require &self for Python binding even when Rust impl does not need it"
34)]
35
36pub mod http;
37pub mod socket;
38pub mod websocket;
39
40use std::num::NonZeroU32;
41
42use nautilus_core::python::to_pyexception;
43use pyo3::prelude::*;
44
45use crate::{
46    python::{
47        http::{HttpClientBuildError, HttpError, HttpInvalidProxyError, HttpTimeoutError},
48        websocket::WebSocketClientError,
49    },
50    ratelimiter::quota::Quota,
51};
52
53#[pymethods]
54#[pyo3_stub_gen::derive::gen_stub_pymethods]
55impl Quota {
56    /// Construct a quota for a number of requests per second.
57    ///
58    /// # Errors
59    ///
60    /// Returns a `PyErr` if the max burst capacity is 0
61    #[staticmethod]
62    pub fn rate_per_second(max_burst: u32) -> PyResult<Self> {
63        let max_burst = NonZeroU32::new(max_burst)
64            .ok_or_else(|| to_pyexception("Max burst capacity should be a non-zero integer"))?;
65        Self::per_second(max_burst).ok_or_else(|| {
66            to_pyexception(
67                "Max burst too large: replenish interval rounds to zero (max 1_000_000_000)",
68            )
69        })
70    }
71
72    /// Construct a quota for a number of requests per minute.
73    ///
74    /// # Errors
75    ///
76    /// Returns a `PyErr` if the max burst capacity is 0
77    #[staticmethod]
78    pub fn rate_per_minute(max_burst: u32) -> PyResult<Self> {
79        match NonZeroU32::new(max_burst) {
80            Some(max_burst) => Ok(Self::per_minute(max_burst)),
81            None => Err(to_pyexception(
82                "Max burst capacity should be a non-zero integer",
83            )),
84        }
85    }
86
87    /// Construct a quota for a number of requests per hour.
88    ///
89    /// # Errors
90    ///
91    /// Returns a `PyErr` if the max burst capacity is 0
92    #[staticmethod]
93    pub fn rate_per_hour(max_burst: u32) -> PyResult<Self> {
94        match NonZeroU32::new(max_burst) {
95            Some(max_burst) => Ok(Self::per_hour(max_burst)),
96            None => Err(to_pyexception(
97                "Max burst capacity should be a non-zero integer",
98            )),
99        }
100    }
101}
102
103/// Loaded as `nautilus_pyo3.network`.
104///
105/// # Errors
106///
107/// Returns a `PyErr` if registering any module components fails.
108#[pymodule]
109pub fn network(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
110    m.add_class::<crate::http::HttpClient>()?;
111    m.add_class::<crate::http::HttpMethod>()?;
112    m.add_class::<crate::http::HttpResponse>()?;
113    m.add_class::<crate::ratelimiter::quota::Quota>()?;
114    m.add_class::<crate::websocket::WebSocketClient>()?;
115    m.add_class::<crate::websocket::WebSocketConfig>()?;
116    m.add_class::<crate::socket::SocketClient>()?;
117    m.add_class::<crate::socket::SocketConfig>()?;
118
119    m.add(
120        "WebSocketClientError",
121        m.py().get_type::<WebSocketClientError>(),
122    )?;
123    m.add("HttpError", m.py().get_type::<HttpError>())?;
124    m.add("HttpTimeoutError", m.py().get_type::<HttpTimeoutError>())?;
125    m.add(
126        "HttpInvalidProxyError",
127        m.py().get_type::<HttpInvalidProxyError>(),
128    )?;
129    m.add(
130        "HttpClientBuildError",
131        m.py().get_type::<HttpClientBuildError>(),
132    )?;
133
134    m.add_function(wrap_pyfunction!(http::http_get, m)?)?;
135    m.add_function(wrap_pyfunction!(http::http_post, m)?)?;
136    m.add_function(wrap_pyfunction!(http::http_patch, m)?)?;
137    m.add_function(wrap_pyfunction!(http::http_delete, m)?)?;
138    m.add_function(wrap_pyfunction!(http::http_download, m)?)?;
139
140    Ok(())
141}
nautilus_network/python/mod.rs

nautilus_network/python/
mod.rs
