Skip to content

Commit d152bee

Browse files
authored
feat(bindings/python): add TimeoutLayer (#7963)
* feat(bindings/python): add TimeoutLayer * docs(bindings/python): fix layer headings and improve Layer docstring * fix(bindings/python): reject non-positive TimeoutLayer values
1 parent 2208c5f commit d152bee

5 files changed

Lines changed: 189 additions & 6 deletions

File tree

‎bindings/python/docs/api/layers.md‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,25 +4,36 @@ This page documents all layers in OpenDAL.
44

55
::: opendal.layers.Layer
66
options:
7-
heading: "opendal.layers.Layer"
7+
heading: "Layer"
88
heading_level: 2
9+
show_root_heading: true
910
show_source: false
1011
show_bases: false
1112

1213
::: opendal.layers.RetryLayer
1314
options:
14-
heading: "opendal.layers.RetryLayer"
15+
heading: "RetryLayer"
1516
heading_level: 2
17+
show_root_heading: true
1618
show_source: false
1719

1820
::: opendal.layers.ConcurrentLimitLayer
1921
options:
20-
heading: "opendal.layers.ConcurrentLimitLayer"
22+
heading: "ConcurrentLimitLayer"
2123
heading_level: 2
24+
show_root_heading: true
2225
show_source: false
2326

2427
::: opendal.layers.MimeGuessLayer
2528
options:
26-
heading: "opendal.layers.MimeGuessLayer"
29+
heading: "MimeGuessLayer"
2730
heading_level: 2
31+
show_root_heading: true
32+
show_source: false
33+
34+
::: opendal.layers.TimeoutLayer
35+
options:
36+
heading: "TimeoutLayer"
37+
heading_level: 2
38+
show_root_heading: true
2839
show_source: false

‎bindings/python/python/opendal/layers.pyi‎

Lines changed: 56 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,17 @@ class ConcurrentLimitLayer(Layer):
6363
"""
6464

6565
class Layer:
66-
"""Layers are used to intercept the operations on the underlying storage."""
66+
"""
67+
Base class for all layers.
68+
69+
A layer wraps an operator to intercept operations on the underlying
70+
storage, adding behavior such as retries, timeouts, concurrency limits,
71+
or content-type detection.
72+
73+
This class is not meant to be instantiated directly. Use a concrete
74+
subclass such as `RetryLayer` or `TimeoutLayer` and apply it with
75+
`Operator.layer` or `AsyncOperator.layer`.
76+
"""
6777

6878
@final
6979
class MimeGuessLayer(Layer):
@@ -146,3 +156,48 @@ class RetryLayer(Layer):
146156
ConfigInvalid
147157
If ``factor``, ``max_delay``, or ``min_delay`` is out of range.
148158
"""
159+
160+
@final
161+
class TimeoutLayer(Layer):
162+
"""
163+
A layer that adds timeouts to operations.
164+
165+
Timeouts prevent slow or stalled work from hanging indefinitely, for
166+
example when a TCP connection stops emitting IO events. Control
167+
operations (such as `stat` and `delete`) and IO operations (such as
168+
`read` and `write`) are bounded by separate timeouts.
169+
170+
Notes
171+
-----
172+
A small amount of overhead is added to IO operations to implement the
173+
timeout correctly.
174+
"""
175+
176+
def __new__(
177+
cls, /, timeout: float | None = None, io_timeout: float | None = None
178+
) -> TimeoutLayer:
179+
"""
180+
Create a new TimeoutLayer.
181+
182+
Parameters
183+
----------
184+
timeout : Optional[float]
185+
Timeout (in seconds) for control operations like ``stat`` and
186+
``delete``. Must be a positive, finite number. A value of ``0``
187+
is rejected because it would make every operation time out
188+
immediately. Defaults to ``60.0``.
189+
io_timeout : Optional[float]
190+
Timeout (in seconds) for IO operations like ``read`` and
191+
``write``. Must be a positive, finite number. A value of ``0``
192+
is rejected because it would make every operation time out
193+
immediately. Defaults to ``10.0``.
194+
195+
Returns
196+
-------
197+
TimeoutLayer
198+
199+
Raises
200+
------
201+
ConfigInvalid
202+
If ``timeout`` or ``io_timeout`` is out of range.
203+
"""

‎bindings/python/src/layers/mod.rs‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,13 @@ mod capability_override;
2626
mod concurrent_limit;
2727
mod mime_guess;
2828
mod retry;
29+
mod timeout;
2930

3031
pub use capability_override::CapabilityOverrideLayer;
3132
pub use concurrent_limit::ConcurrentLimitLayer;
3233
pub use mime_guess::MimeGuessLayer;
3334
pub use retry::RetryLayer;
35+
pub use timeout::TimeoutLayer;
3436

3537
use opendal::Operator;
3638
use pyo3::prelude::*;
@@ -41,6 +43,14 @@ pub trait PythonLayer: Send + Sync {
4143
fn layer(&self, op: Operator) -> Operator;
4244
}
4345

44-
/// Layers are used to intercept the operations on the underlying storage.
46+
/// Base class for all layers.
47+
///
48+
/// A layer wraps an operator to intercept operations on the underlying
49+
/// storage, adding behavior such as retries, timeouts, concurrency limits,
50+
/// or content-type detection.
51+
///
52+
/// This class is not meant to be instantiated directly. Use a concrete
53+
/// subclass such as `RetryLayer` or `TimeoutLayer` and apply it with
54+
/// `Operator.layer` or `AsyncOperator.layer`.
4555
#[pyclass(module = "opendal.layers", subclass)]
4656
pub struct Layer(pub Box<dyn PythonLayer>);
Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
// Licensed to the Apache Software Foundation (ASF) under one
2+
// or more contributor license agreements. See the NOTICE file
3+
// distributed with this work for additional information
4+
// regarding copyright ownership. The ASF licenses this file
5+
// to you under the Apache License, Version 2.0 (the
6+
// "License"); you may not use this file except in compliance
7+
// with the License. You may obtain a copy of the License at
8+
//
9+
// http://www.apache.org/licenses/LICENSE-2.0
10+
//
11+
// Unless required by applicable law or agreed to in writing,
12+
// software distributed under the License is distributed on an
13+
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
// KIND, either express or implied. See the License for the
15+
// specific language governing permissions and limitations
16+
// under the License.
17+
18+
use std::time::Duration;
19+
20+
use super::Layer;
21+
use super::PythonLayer;
22+
use crate::*;
23+
use opendal::Operator;
24+
25+
/// Parse a timeout given in seconds into a [`Duration`].
26+
///
27+
/// Rejects non-positive, non-finite, or out-of-range values. A zero timeout
28+
/// is rejected because it would make every operation time out immediately.
29+
fn parse_timeout_secs(name: &str, secs: f64) -> PyResult<Duration> {
30+
if !secs.is_finite() || secs <= 0.0 {
31+
return Err(ConfigInvalid::new_err(format!(
32+
"{name} must be a positive, finite number of seconds"
33+
)));
34+
}
35+
Duration::try_from_secs_f64(secs).map_err(|_| {
36+
ConfigInvalid::new_err(format!(
37+
"{name} must be a positive, finite number of seconds"
38+
))
39+
})
40+
}
41+
42+
/// A layer that adds timeouts to operations.
43+
///
44+
/// Timeouts prevent slow or stalled work from hanging indefinitely, for
45+
/// example when a TCP connection stops emitting IO events. Control
46+
/// operations (such as `stat` and `delete`) and IO operations (such as
47+
/// `read` and `write`) are bounded by separate timeouts.
48+
///
49+
/// Notes
50+
/// -----
51+
/// A small amount of overhead is added to IO operations to implement the
52+
/// timeout correctly.
53+
#[pyclass(module = "opendal.layers", extends = Layer, skip_from_py_object)]
54+
#[derive(Clone)]
55+
pub struct TimeoutLayer(ocore::layers::TimeoutLayer);
56+
57+
impl PythonLayer for TimeoutLayer {
58+
fn layer(&self, op: Operator) -> Operator {
59+
op.layer(self.0.clone())
60+
}
61+
}
62+
#[pymethods]
63+
impl TimeoutLayer {
64+
/// Create a new TimeoutLayer.
65+
///
66+
/// Parameters
67+
/// ----------
68+
/// timeout : Optional[float]
69+
/// Timeout (in seconds) for control operations like ``stat`` and
70+
/// ``delete``. Must be a positive, finite number. A value of ``0``
71+
/// is rejected because it would make every operation time out
72+
/// immediately. Defaults to ``60.0``.
73+
/// io_timeout : Optional[float]
74+
/// Timeout (in seconds) for IO operations like ``read`` and
75+
/// ``write``. Must be a positive, finite number. A value of ``0``
76+
/// is rejected because it would make every operation time out
77+
/// immediately. Defaults to ``10.0``.
78+
///
79+
/// Returns
80+
/// -------
81+
/// TimeoutLayer
82+
///
83+
/// Raises
84+
/// ------
85+
/// ConfigInvalid
86+
/// If ``timeout`` or ``io_timeout`` is out of range.
87+
#[new]
88+
#[pyo3(signature = (timeout = None, io_timeout = None))]
89+
fn new(timeout: Option<f64>, io_timeout: Option<f64>) -> PyResult<PyClassInitializer<Self>> {
90+
let mut timeout_layer = ocore::layers::TimeoutLayer::default();
91+
if let Some(timeout) = timeout {
92+
let timeout = parse_timeout_secs("timeout", timeout)?;
93+
timeout_layer = timeout_layer.with_timeout(timeout);
94+
}
95+
if let Some(io_timeout) = io_timeout {
96+
let io_timeout = parse_timeout_secs("io_timeout", io_timeout)?;
97+
timeout_layer = timeout_layer.with_io_timeout(io_timeout);
98+
}
99+
100+
let timeout_layer = Self(timeout_layer);
101+
let class = PyClassInitializer::from(Layer(Box::new(timeout_layer.clone())))
102+
.add_subclass(timeout_layer);
103+
104+
Ok(class)
105+
}
106+
}

‎bindings/python/src/lib.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@ mod _opendal {
8686
#[pymodule_export]
8787
use crate::{
8888
CapabilityOverrideLayer, ConcurrentLimitLayer, Layer, MimeGuessLayer, RetryLayer,
89+
TimeoutLayer,
8990
};
9091
}
9192

0 commit comments

Comments
 (0)