pyo3/conversions/std/
path.rs

1// TODO https://github.com/PyO3/pyo3/issues/5487
2#![allow(clippy::undocumented_unsafe_blocks)]
3
4use crate::conversion::IntoPyObject;
5use crate::ffi_ptr_ext::FfiPtrExt;
6#[cfg(feature = "experimental-inspect")]
7use crate::inspect::{type_hint_identifier, type_hint_subscript, type_hint_union, PyStaticExpr};
8use crate::sync::PyOnceLock;
9use crate::types::any::PyAnyMethods;
10use crate::{ffi, Borrowed, Bound, FromPyObject, Py, PyAny, PyErr, Python};
11use alloc::borrow::Cow;
12use std::ffi::OsString;
13use std::path::{Path, PathBuf};
14
15impl FromPyObject<'_, '_> for PathBuf {
16    type Error = PyErr;
17
18    #[cfg(feature = "experimental-inspect")]
19    const INPUT_TYPE: PyStaticExpr = type_hint_union!(
20        OsString::INPUT_TYPE,
21        type_hint_subscript!(
22            type_hint_identifier!("os", "PathLike"),
23            OsString::INPUT_TYPE
24        )
25    );
26
27    fn extract(ob: Borrowed<'_, '_, PyAny>) -> Result<Self, Self::Error> {
28        // We use os.fspath to get the underlying path as bytes or str
29        let path = unsafe { ffi::PyOS_FSPath(ob.as_ptr()).assume_owned_or_err(ob.py())? };
30        Ok(path.extract::<OsString>()?.into())
31    }
32}
33
34impl<'py> IntoPyObject<'py> for &Path {
35    type Target = PyAny;
36    type Output = Bound<'py, Self::Target>;
37    type Error = PyErr;
38
39    #[cfg(feature = "experimental-inspect")]
40    const OUTPUT_TYPE: PyStaticExpr = type_hint_identifier!("pathlib", "Path");
41
42    #[inline]
43    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
44        static PY_PATH: PyOnceLock<Py<PyAny>> = PyOnceLock::new();
45        PY_PATH
46            .import(py, "pathlib", "Path")?
47            .call((self.as_os_str(),), None)
48    }
49}
50
51impl<'py> IntoPyObject<'py> for &&Path {
52    type Target = PyAny;
53    type Output = Bound<'py, Self::Target>;
54    type Error = PyErr;
55
56    #[cfg(feature = "experimental-inspect")]
57    const OUTPUT_TYPE: PyStaticExpr = <&Path>::OUTPUT_TYPE;
58
59    #[inline]
60    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
61        (*self).into_pyobject(py)
62    }
63}
64
65impl<'py> IntoPyObject<'py> for Cow<'_, Path> {
66    type Target = PyAny;
67    type Output = Bound<'py, Self::Target>;
68    type Error = PyErr;
69
70    #[cfg(feature = "experimental-inspect")]
71    const OUTPUT_TYPE: PyStaticExpr = <&Path>::OUTPUT_TYPE;
72
73    #[inline]
74    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
75        (*self).into_pyobject(py)
76    }
77}
78
79impl<'py> IntoPyObject<'py> for &Cow<'_, Path> {
80    type Target = PyAny;
81    type Output = Bound<'py, Self::Target>;
82    type Error = PyErr;
83
84    #[cfg(feature = "experimental-inspect")]
85    const OUTPUT_TYPE: PyStaticExpr = <&Path>::OUTPUT_TYPE;
86
87    #[inline]
88    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
89        (&**self).into_pyobject(py)
90    }
91}
92
93impl<'a> FromPyObject<'a, '_> for Cow<'a, Path> {
94    type Error = PyErr;
95
96    #[cfg(feature = "experimental-inspect")]
97    const INPUT_TYPE: PyStaticExpr = PathBuf::INPUT_TYPE;
98
99    fn extract(obj: Borrowed<'a, '_, PyAny>) -> Result<Self, Self::Error> {
100        #[cfg(any(Py_3_10, not(Py_LIMITED_API)))]
101        if let Ok(s) = obj.extract::<&str>() {
102            return Ok(Cow::Borrowed(s.as_ref()));
103        }
104
105        obj.extract::<PathBuf>().map(Cow::Owned)
106    }
107}
108
109impl<'py> IntoPyObject<'py> for PathBuf {
110    type Target = PyAny;
111    type Output = Bound<'py, Self::Target>;
112    type Error = PyErr;
113
114    #[cfg(feature = "experimental-inspect")]
115    const OUTPUT_TYPE: PyStaticExpr = <&Path>::OUTPUT_TYPE;
116
117    #[inline]
118    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
119        (&self).into_pyobject(py)
120    }
121}
122
123impl<'py> IntoPyObject<'py> for &PathBuf {
124    type Target = PyAny;
125    type Output = Bound<'py, Self::Target>;
126    type Error = PyErr;
127
128    #[cfg(feature = "experimental-inspect")]
129    const OUTPUT_TYPE: PyStaticExpr = <&Path>::OUTPUT_TYPE;
130
131    #[inline]
132    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
133        (&**self).into_pyobject(py)
134    }
135}
136
137#[cfg(test)]
138mod tests {
139    use super::*;
140    use crate::{
141        types::{PyAnyMethods, PyString},
142        IntoPyObjectExt,
143    };
144    use core::fmt::Debug;
145    #[cfg(not(target_os = "wasi"))]
146    use std::ffi::OsStr;
147    #[cfg(any(unix, target_os = "emscripten"))]
148    use std::os::unix::ffi::OsStringExt;
149    #[cfg(windows)]
150    use std::os::windows::ffi::OsStringExt;
151
152    #[test]
153    #[cfg(any(unix, target_os = "emscripten"))]
154    fn test_non_utf8_conversion() {
155        Python::attach(|py| {
156            use std::os::unix::ffi::OsStrExt;
157
158            // this is not valid UTF-8
159            let payload = &[250, 251, 252, 253, 254, 255, 0, 255];
160            let path = Path::new(OsStr::from_bytes(payload));
161
162            // do a roundtrip into Pythonland and back and compare
163            let py_str = path.into_pyobject(py).unwrap();
164            let path_2: PathBuf = py_str.extract().unwrap();
165            assert_eq!(path, path_2);
166        });
167    }
168
169    #[test]
170    fn test_intopyobject_roundtrip() {
171        Python::attach(|py| {
172            fn test_roundtrip<'py, T>(py: Python<'py>, obj: T)
173            where
174                T: IntoPyObject<'py> + AsRef<Path> + Debug + Clone,
175                T::Error: Debug,
176            {
177                let pyobject = obj.clone().into_bound_py_any(py).unwrap();
178                let roundtripped_obj: PathBuf = pyobject.extract().unwrap();
179                assert_eq!(obj.as_ref(), roundtripped_obj.as_path());
180            }
181            let path = Path::new("Hello\0\n🐍");
182            test_roundtrip::<&Path>(py, path);
183            test_roundtrip::<Cow<'_, Path>>(py, Cow::Borrowed(path));
184            test_roundtrip::<Cow<'_, Path>>(py, Cow::Owned(path.to_path_buf()));
185            test_roundtrip::<PathBuf>(py, path.to_path_buf());
186        });
187    }
188
189    #[test]
190    fn test_from_pystring() {
191        Python::attach(|py| {
192            let path = "Hello\0\n🐍";
193            let pystring = PyString::new(py, path);
194            let roundtrip: PathBuf = pystring.extract().unwrap();
195            assert_eq!(roundtrip, Path::new(path));
196        });
197    }
198
199    #[test]
200    fn test_extract_cow() {
201        Python::attach(|py| {
202            fn test_extract<'py, T>(py: Python<'py>, path: &T, is_borrowed: bool)
203            where
204                for<'a> &'a T: IntoPyObject<'py, Output = Bound<'py, PyString>>,
205                for<'a> <&'a T as IntoPyObject<'py>>::Error: Debug,
206                T: AsRef<Path> + ?Sized,
207            {
208                let pystring = path.into_pyobject(py).unwrap();
209                let cow: Cow<'_, Path> = pystring.extract().unwrap();
210                assert_eq!(cow, path.as_ref());
211                assert_eq!(is_borrowed, matches!(cow, Cow::Borrowed(_)));
212            }
213
214            // On Python 3.10+ or when not using the limited API, we can borrow strings from python
215            let can_borrow_str = cfg!(any(Py_3_10, not(Py_LIMITED_API)));
216            // This can be borrowed because it is valid UTF-8
217            test_extract::<str>(py, "Hello\0\n🐍", can_borrow_str);
218            test_extract::<str>(py, "Hello, world!", can_borrow_str);
219
220            #[cfg(windows)]
221            let os_str = {
222                // 'A', unpaired surrogate, 'B'
223                OsString::from_wide(&['A' as u16, 0xD800, 'B' as u16])
224            };
225
226            #[cfg(any(unix, target_os = "emscripten"))]
227            let os_str = { OsString::from_vec(vec![250, 251, 252, 253, 254, 255, 0, 255]) };
228
229            // This cannot be borrowed because it is not valid UTF-8
230            #[cfg(any(unix, windows, target_os = "emscripten"))]
231            test_extract::<OsStr>(py, &os_str, false);
232        });
233    }
234}
pyo3/conversions/std/path.rs

pyo3/conversions/std/
path.rs
