Allow constructing PyTraceback (#5857)

* Allow constructing `PyTraceback`

* use `classinfo_object`

* Clarify order of frames

* changelog

* Do not panic when there are no frames

* Return `None` when there are no frames

* One less generic parameter

* `cast_into_unchecked`

* Remove `PyTraceback::from_frames`

* Add test & docs for `PyFrameMethods`

* Add private `PyCode::empty`

* Update changelog

Author: bschoenmaeckers

newsfragments/5857.added.md

@@ -0,0 +1 @@
+Add `PyFrame::new`, `PyTraceBack::new`, and `PyFrameMethods::line_number`.

src/sealed.rs

@@ -1,4 +1,6 @@
 use crate::impl_::pyfunction::PyFunctionDef;
+#[cfg(all(not(Py_LIMITED_API), not(PyPy), not(GraalPy)))]
+use crate::types::PyFrame;
 use crate::types::{
     PyBool, PyByteArray, PyBytes, PyCapsule, PyComplex, PyDict, PyFloat, PyFrozenSet, PyList,
     PyMapping, PyMappingProxy, PyModule, PyRange, PySequence, PySet, PySlice, PyString,
@@ -42,6 +44,8 @@ impl Sealed for Bound<'_, PySet> {}
 impl Sealed for Bound<'_, PySlice> {}
 impl Sealed for Bound<'_, PyString> {}
 impl Sealed for Bound<'_, PyTraceback> {}
+#[cfg(all(not(Py_LIMITED_API), not(PyPy), not(GraalPy)))]
+impl Sealed for Bound<'_, PyFrame> {}
 impl Sealed for Bound<'_, PyTuple> {}
 impl Sealed for Bound<'_, PyType> {}
 impl Sealed for Bound<'_, PyWeakref> {}

src/types/code.rs

@@ -68,6 +68,21 @@ impl PyCode {
                 .cast_into_unchecked()
         }
     }
+
+    #[cfg(not(any(Py_LIMITED_API, PyPy, GraalPy)))]
+    pub(crate) fn empty<'py>(
+        py: Python<'py>,
+        file_name: &CStr,
+        func_name: &CStr,
+        first_line_number: i32,
+    ) -> Bound<'py, PyCode> {
+        unsafe {
+            ffi::PyCode_NewEmpty(file_name.as_ptr(), func_name.as_ptr(), first_line_number)
+                .cast::<ffi::PyObject>()
+                .assume_owned(py)
+                .cast_into_unchecked()
+        }
+    }
 }
 
 /// Implementation of functionality for [`PyCode`].

src/types/frame.rs

@@ -1,5 +1,10 @@
-use crate::ffi;
+use crate::ffi_ptr_ext::FfiPtrExt;
+use crate::sealed::Sealed;
+use crate::types::{PyCode, PyDict};
 use crate::PyAny;
+use crate::{ffi, Bound, PyResult, Python};
+use pyo3_ffi::PyObject;
+use std::ffi::CStr;
 
 /// Represents a Python frame.
 ///
@@ -15,3 +20,61 @@ pyobject_native_type_core!(
     "FrameType",
     #checkfunction=ffi::PyFrame_Check
 );
+
+impl PyFrame {
+    /// Creates a new frame object.
+    pub fn new<'py>(
+        py: Python<'py>,
+        file_name: &CStr,
+        func_name: &CStr,
+        line_number: i32,
+    ) -> PyResult<Bound<'py, PyFrame>> {
+        // Safety: Thread is attached because we have a python token
+        let state = unsafe { ffi::compat::PyThreadState_GetUnchecked() };
+        let code = PyCode::empty(py, file_name, func_name, line_number);
+        let globals = PyDict::new(py);
+        let locals = PyDict::new(py);
+
+        unsafe {
+            Ok(ffi::PyFrame_New(
+                state,
+                code.into_ptr().cast(),
+                globals.as_ptr(),
+                locals.as_ptr(),
+            )
+            .cast::<PyObject>()
+            .assume_owned_or_err(py)?
+            .cast_into_unchecked::<PyFrame>())
+        }
+    }
+}
+
+/// Implementation of functionality for [`PyFrame`].
+///
+/// These methods are defined for the `Bound<'py, PyFrame>` smart pointer, so to use method call
+/// syntax these methods are separated into a trait, because stable Rust does not yet support
+/// `arbitrary_self_types`.
+#[doc(alias = "PyFrame")]
+pub trait PyFrameMethods<'py>: Sealed {
+    /// Returns the line number of the current instruction in the frame.
+    fn line_number(&self) -> i32;
+}
+
+impl<'py> PyFrameMethods<'py> for Bound<'py, PyFrame> {
+    fn line_number(&self) -> i32 {
+        unsafe { ffi::PyFrame_GetLineNumber(self.as_ptr().cast()) }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_frame_creation() {
+        Python::attach(|py| {
+            let frame = PyFrame::new(py, c"file.py", c"func", 42).unwrap();
+            assert_eq!(frame.line_number(), 42);
+        });
+    }
+}

src/types/mod.rs

@@ -16,7 +16,7 @@ pub use self::dict::{PyDictItems, PyDictKeys, PyDictValues};
 pub use self::ellipsis::PyEllipsis;
 pub use self::float::{PyFloat, PyFloatMethods};
 #[cfg(all(not(Py_LIMITED_API), not(PyPy), not(GraalPy)))]
-pub use self::frame::PyFrame;
+pub use self::frame::{PyFrame, PyFrameMethods};
 pub use self::frozenset::{PyFrozenSet, PyFrozenSetBuilder, PyFrozenSetMethods};
 pub use self::function::PyCFunction;
 #[cfg(not(Py_LIMITED_API))]

src/types/traceback.rs

@@ -1,6 +1,8 @@
 use crate::err::{error_on_minusone, PyResult};
 use crate::types::{any::PyAnyMethods, string::PyStringMethods, PyString};
 use crate::{ffi, Bound, PyAny};
+#[cfg(all(not(Py_LIMITED_API), not(PyPy), not(GraalPy)))]
+use crate::{types::PyFrame, PyTypeCheck, Python};
 
 /// Represents a Python traceback.
 ///
@@ -20,6 +22,27 @@ pyobject_native_type_core!(
     #checkfunction=ffi::PyTraceBack_Check
 );
 
+impl PyTraceback {
+    /// Creates a new traceback object from the given frame.
+    ///
+    /// The `next` is the next traceback in the direction of where the exception was raised
+    /// or `None` if this is the last frame in the traceback.
+    #[cfg(all(not(Py_LIMITED_API), not(PyPy), not(GraalPy)))]
+    pub fn new<'py>(
+        py: Python<'py>,
+        next: Option<Bound<'py, PyTraceback>>,
+        frame: Bound<'py, PyFrame>,
+        instruction_index: i32,
+        line_number: i32,
+    ) -> PyResult<Bound<'py, PyTraceback>> {
+        unsafe {
+            Ok(PyTraceback::classinfo_object(py)
+                .call1((next, frame, instruction_index, line_number))?
+                .cast_into_unchecked())
+        }
+    }
+}
+
 /// Implementation of functionality for [`PyTraceback`].
 ///
 /// These methods are defined for the `Bound<'py, PyTraceback>` smart pointer, so to use method call
@@ -82,9 +105,10 @@ impl<'py> PyTracebackMethods<'py> for Bound<'py, PyTraceback> {
 
 #[cfg(test)]
 mod tests {
+    use super::*;
     use crate::IntoPyObject;
     use crate::{
-        types::{any::PyAnyMethods, dict::PyDictMethods, traceback::PyTracebackMethods, PyDict},
+        types::{dict::PyDictMethods, PyDict},
         PyErr, Python,
     };
 
@@ -146,4 +170,30 @@ def f():
             assert!(err_object.getattr("__traceback__").unwrap().is(&traceback));
         })
     }
+
+    #[test]
+    #[cfg(all(not(Py_LIMITED_API), not(PyPy), not(GraalPy)))]
+    fn test_create_traceback() {
+        Python::attach(|py| {
+            let traceback = PyTraceback::new(
+                py,
+                None,
+                PyFrame::new(py, c"file2.py", c"func2", 20).unwrap(),
+                0,
+                20,
+            )
+            .unwrap();
+            let traceback = PyTraceback::new(
+                py,
+                Some(traceback),
+                PyFrame::new(py, c"file1.py", c"func1", 10).unwrap(),
+                0,
+                10,
+            )
+            .unwrap();
+            assert_eq!(
+                traceback.format().unwrap(), "Traceback (most recent call last):\n  File \"file1.py\", line 10, in func1\n  File \"file2.py\", line 20, in func2\n"
+            );
+        })
+    }
 }