pyo3/conversions/std/
osstr.rs

1use crate::conversion::IntoPyObject;
2use crate::ffi_ptr_ext::FfiPtrExt;
3use crate::instance::Bound;
4use crate::types::any::PyAnyMethods;
5use crate::types::PyString;
6use crate::{ffi, FromPyObject, PyAny, PyResult, Python};
7use std::borrow::Cow;
8use std::convert::Infallible;
9use std::ffi::{OsStr, OsString};
10
11impl<'py> IntoPyObject<'py> for &OsStr {
12    type Target = PyString;
13    type Output = Bound<'py, Self::Target>;
14    type Error = Infallible;
15
16    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
17        // If the string is UTF-8, take the quick and easy shortcut
18        if let Some(valid_utf8_path) = self.to_str() {
19            return valid_utf8_path.into_pyobject(py);
20        }
21
22        // All targets besides windows support the std::os::unix::ffi::OsStrExt API:
23        // https://doc.rust-lang.org/src/std/sys_common/mod.rs.html#59
24        #[cfg(not(windows))]
25        {
26            #[cfg(target_os = "wasi")]
27            let bytes = std::os::wasi::ffi::OsStrExt::as_bytes(self);
28            #[cfg(not(target_os = "wasi"))]
29            let bytes = std::os::unix::ffi::OsStrExt::as_bytes(self);
30
31            let ptr = bytes.as_ptr().cast();
32            let len = bytes.len() as ffi::Py_ssize_t;
33            unsafe {
34                // DecodeFSDefault automatically chooses an appropriate decoding mechanism to
35                // parse os strings losslessly (i.e. surrogateescape most of the time)
36                Ok(ffi::PyUnicode_DecodeFSDefaultAndSize(ptr, len)
37                    .assume_owned(py)
38                    .downcast_into_unchecked::<PyString>())
39            }
40        }
41
42        #[cfg(windows)]
43        {
44            let wstr: Vec<u16> = std::os::windows::ffi::OsStrExt::encode_wide(self).collect();
45
46            unsafe {
47                // This will not panic because the data from encode_wide is well-formed Windows
48                // string data
49
50                Ok(
51                    ffi::PyUnicode_FromWideChar(wstr.as_ptr(), wstr.len() as ffi::Py_ssize_t)
52                        .assume_owned(py)
53                        .downcast_into_unchecked::<PyString>(),
54                )
55            }
56        }
57    }
58}
59
60impl<'py> IntoPyObject<'py> for &&OsStr {
61    type Target = PyString;
62    type Output = Bound<'py, Self::Target>;
63    type Error = Infallible;
64
65    #[inline]
66    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
67        (*self).into_pyobject(py)
68    }
69}
70
71// There's no FromPyObject implementation for &OsStr because albeit possible on Unix, this would
72// be impossible to implement on Windows. Hence it's omitted entirely
73
74impl FromPyObject<'_> for OsString {
75    fn extract_bound(ob: &Bound<'_, PyAny>) -> PyResult<Self> {
76        let pystring = ob.downcast::<PyString>()?;
77
78        #[cfg(not(windows))]
79        {
80            // Decode from Python's lossless bytes string representation back into raw bytes
81            let fs_encoded_bytes = unsafe {
82                crate::Py::<crate::types::PyBytes>::from_owned_ptr(
83                    ob.py(),
84                    ffi::PyUnicode_EncodeFSDefault(pystring.as_ptr()),
85                )
86            };
87
88            // Create an OsStr view into the raw bytes from Python
89            #[cfg(target_os = "wasi")]
90            let os_str: &OsStr =
91                std::os::wasi::ffi::OsStrExt::from_bytes(fs_encoded_bytes.as_bytes(ob.py()));
92            #[cfg(not(target_os = "wasi"))]
93            let os_str: &OsStr =
94                std::os::unix::ffi::OsStrExt::from_bytes(fs_encoded_bytes.as_bytes(ob.py()));
95
96            Ok(os_str.to_os_string())
97        }
98
99        #[cfg(windows)]
100        {
101            use crate::types::string::PyStringMethods;
102
103            // Take the quick and easy shortcut if UTF-8
104            if let Ok(utf8_string) = pystring.to_cow() {
105                return Ok(utf8_string.into_owned().into());
106            }
107
108            // Get an owned allocated wide char buffer from PyString, which we have to deallocate
109            // ourselves
110            let size =
111                unsafe { ffi::PyUnicode_AsWideChar(pystring.as_ptr(), std::ptr::null_mut(), 0) };
112            crate::err::error_on_minusone(ob.py(), size)?;
113
114            let mut buffer = vec![0; size as usize];
115            let bytes_read =
116                unsafe { ffi::PyUnicode_AsWideChar(pystring.as_ptr(), buffer.as_mut_ptr(), size) };
117            assert_eq!(bytes_read, size);
118
119            // Copy wide char buffer into OsString
120            let os_string = std::os::windows::ffi::OsStringExt::from_wide(&buffer);
121
122            Ok(os_string)
123        }
124    }
125}
126
127impl<'py> IntoPyObject<'py> for Cow<'_, OsStr> {
128    type Target = PyString;
129    type Output = Bound<'py, Self::Target>;
130    type Error = Infallible;
131
132    #[inline]
133    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
134        (*self).into_pyobject(py)
135    }
136}
137
138impl<'py> IntoPyObject<'py> for &Cow<'_, OsStr> {
139    type Target = PyString;
140    type Output = Bound<'py, Self::Target>;
141    type Error = Infallible;
142
143    #[inline]
144    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
145        (&**self).into_pyobject(py)
146    }
147}
148
149impl<'py> IntoPyObject<'py> for OsString {
150    type Target = PyString;
151    type Output = Bound<'py, Self::Target>;
152    type Error = Infallible;
153
154    #[inline]
155    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
156        self.as_os_str().into_pyobject(py)
157    }
158}
159
160impl<'py> IntoPyObject<'py> for &OsString {
161    type Target = PyString;
162    type Output = Bound<'py, Self::Target>;
163    type Error = Infallible;
164
165    #[inline]
166    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
167        self.as_os_str().into_pyobject(py)
168    }
169}
170
171#[cfg(test)]
172mod tests {
173    use crate::types::{PyAnyMethods, PyString, PyStringMethods};
174    use crate::{BoundObject, IntoPyObject, Python};
175    use std::fmt::Debug;
176    use std::{
177        borrow::Cow,
178        ffi::{OsStr, OsString},
179    };
180
181    #[test]
182    #[cfg(not(windows))]
183    fn test_non_utf8_conversion() {
184        Python::with_gil(|py| {
185            #[cfg(not(target_os = "wasi"))]
186            use std::os::unix::ffi::OsStrExt;
187            #[cfg(target_os = "wasi")]
188            use std::os::wasi::ffi::OsStrExt;
189
190            // this is not valid UTF-8
191            let payload = &[250, 251, 252, 253, 254, 255, 0, 255];
192            let os_str = OsStr::from_bytes(payload);
193
194            // do a roundtrip into Pythonland and back and compare
195            let py_str = os_str.into_pyobject(py).unwrap();
196            let os_str_2: OsString = py_str.extract().unwrap();
197            assert_eq!(os_str, os_str_2);
198        });
199    }
200
201    #[test]
202    fn test_intopyobject_roundtrip() {
203        Python::with_gil(|py| {
204            fn test_roundtrip<'py, T>(py: Python<'py>, obj: T)
205            where
206                T: IntoPyObject<'py> + AsRef<OsStr> + Debug + Clone,
207                T::Error: Debug,
208            {
209                let pyobject = obj.clone().into_pyobject(py).unwrap().into_any();
210                let pystring = pyobject.as_borrowed().downcast::<PyString>().unwrap();
211                assert_eq!(pystring.to_string_lossy(), obj.as_ref().to_string_lossy());
212                let roundtripped_obj: OsString = pystring.extract().unwrap();
213                assert_eq!(obj.as_ref(), roundtripped_obj.as_os_str());
214            }
215            let os_str = OsStr::new("Hello\0\n🐍");
216            test_roundtrip::<&OsStr>(py, os_str);
217            test_roundtrip::<Cow<'_, OsStr>>(py, Cow::Borrowed(os_str));
218            test_roundtrip::<Cow<'_, OsStr>>(py, Cow::Owned(os_str.to_os_string()));
219            test_roundtrip::<OsString>(py, os_str.to_os_string());
220        });
221    }
222}
pyo3/conversions/std/osstr.rs

pyo3/conversions/std/
osstr.rs
