Implement deleters

Adds a #[deleter] macro

When deleter is set, the `PyGetSetDef.setter` function calls the setter or deleter depending on if the value is `NULL` or not

Issue #5686

Author: Tpt

guide/src/class.md

@@ -14,6 +14,7 @@ Below is a list of links to the relevant section of this chapter for each:
   - [`#[new]`](#constructor)
   - [`#[getter]`](#object-properties-using-getter-and-setter)
   - [`#[setter]`](#object-properties-using-getter-and-setter)
+  - [`#[deleter]`](#object-properties-using-getter-and-setter)
   - [`#[staticmethod]`](#static-methods)
   - [`#[classmethod]`](#class-methods)
   - [`#[classattr]`](#class-attributes)
@@ -620,7 +621,7 @@ Here, the `args` and `kwargs` allow creating instances of the subclass passing i
 PyO3 supports two ways to add properties to your `#[pyclass]`:
 
 - For simple struct fields with no side effects, a `#[pyo3(get, set)]` attribute can be added directly to the field definition in the `#[pyclass]`.
-- For properties which require computation you can define `#[getter]` and `#[setter]` functions in the [`#[pymethods]`](#instance-methods) block.
+- For properties which require computation you can define `#[getter]`, `#[setter]` and `#[deleter]` functions in the [`#[pymethods]`](#instance-methods) block.
 
 We'll cover each of these in the following sections.
 
@@ -670,13 +671,43 @@ impl MyClass {
     fn num(&self) -> PyResult<i32> {
         Ok(self.num)
     }
+
+    #[setter]
+    fn set_num(&mut self, num: i32) {
+        self.num = num;
+    }
+}
+```
+
+The `#[deleter]` attribute is also available to delete the property.
+This corresponds to the `del my_object.my_property` python operation.
+
+```rust
+# use pyo3::prelude::*;
+# use pyo3::exceptions::PyAttributeError;
+#[pyclass]
+struct MyClass {
+    num: Option<i32>,
+}
+
+#[pymethods]
+impl MyClass {
+    #[getter]
+    fn num(&self) -> PyResult<i32> {
+        self.num.ok_or_else(|| PyAttributeError::new_err("num has been deleted"))
+    }
+
+    #[deleter]
+    fn delete_num(&mut self) {
+        self.num = None;
+    }
 }
 ```
 
-A getter or setter's function name is used as the property name by default.
+A getter, setter or deleters's function name is used as the property name by default.
 There are several ways how to override the name.
 
-If a function name starts with `get_` or `set_` for getter or setter respectively, the descriptor name becomes the function name with this prefix removed.
+If a function name starts with `get_`, `set_` or `delete_` for getter, setter or deleter, respectively, the descriptor name becomes the function name with this prefix removed.
 This is also useful in case of Rust keywords like `type` ([raw identifiers](https://doc.rust-lang.org/edition-guide/rust-2018/module-system/raw-identifiers.html) can be used since Rust 2018).
 
 ```rust
@@ -702,7 +733,7 @@ impl MyClass {
 
 In this case, a property `num` is defined and available from Python code as `self.num`.
 
-Both the `#[getter]` and `#[setter]` attributes accept one parameter.
+The `#[getter]`, `#[setter]` and `#[deleter]` attributes accept one parameter.
 If this parameter is specified, it is used as the property name, i.e.
 
 ```rust
@@ -728,9 +759,6 @@ impl MyClass {
 
 In this case, the property `number` is defined and available from Python code as `self.number`.
 
-Attributes defined by `#[setter]` or `#[pyo3(set)]` will always raise `AttributeError` on `del` operations.
-Support for defining custom `del` behavior is tracked in [#1778](https://github.com/PyO3/pyo3/issues/1778).
-
 ## Instance methods
 
 To define a Python compatible method, an `impl` block for your struct has to be annotated with the `#[pymethods]` attribute.

newsfragments/5699.added.md

@@ -0,0 +1 @@
+`#[deleter]` attribute to implement property deleters

pyo3-macros-backend/src/method.rs

@@ -220,6 +220,8 @@ pub enum FnType {
     Getter(SelfType),
     /// Represents a pymethod annotated with `#[setter]`
     Setter(SelfType),
+    /// Represents a pymethod annotated with `#[deleter]`
+    Deleter(SelfType),
     /// Represents a regular pymethod
     Fn(SelfType),
     /// Represents a pymethod annotated with `#[classmethod]`, like a `@classmethod`
@@ -237,6 +239,7 @@ impl FnType {
         match self {
             FnType::Getter(_)
             | FnType::Setter(_)
+            | FnType::Deleter(_)
             | FnType::Fn(_)
             | FnType::FnClass(_)
             | FnType::FnModule(_) => true,
@@ -247,9 +250,11 @@ impl FnType {
     pub fn signature_attribute_allowed(&self) -> bool {
         match self {
             FnType::Fn(_) | FnType::FnStatic | FnType::FnClass(_) | FnType::FnModule(_) => true,
-            // Setter, Getter and ClassAttribute all have fixed signatures (either take 0 or 1
+            // Getter, Setter and Deleter and ClassAttribute all have fixed signatures (either take 0 or 1
             // arguments) so cannot have a `signature = (...)` attribute.
-            FnType::Getter(_) | FnType::Setter(_) | FnType::ClassAttribute => false,
+            FnType::Getter(_) | FnType::Setter(_) | FnType::Deleter(_) | FnType::ClassAttribute => {
+                false
+            }
         }
     }
 
@@ -262,12 +267,14 @@ impl FnType {
     ) -> Option<TokenStream> {
         let Ctx { pyo3_path, .. } = ctx;
         match self {
-            FnType::Getter(st) | FnType::Setter(st) | FnType::Fn(st) => Some(st.receiver(
-                cls.expect("no class given for Fn with a \"self\" receiver"),
-                error_mode,
-                holders,
-                ctx,
-            )),
+            FnType::Getter(st) | FnType::Setter(st) | FnType::Deleter(st) | FnType::Fn(st) => {
+                Some(st.receiver(
+                    cls.expect("no class given for Fn with a \"self\" receiver"),
+                    error_mode,
+                    holders,
+                    ctx,
+                ))
+            }
             FnType::FnClass(span) => {
                 let py = syn::Ident::new("py", Span::call_site());
                 let slf: Ident = syn::Ident::new("_slf", Span::call_site());
@@ -592,6 +599,19 @@ impl<'a> FnSpec<'a> {
 
                 FnType::Setter(parse_receiver("expected receiver for `#[setter]`")?)
             }
+            [MethodTypeAttribute::Deleter(_, name)] => {
+                if let Some(name) = name.take() {
+                    ensure_spanned!(
+                        python_name.replace(name).is_none(),
+                        python_name.span() => "`name` may only be specified once"
+                    );
+                } else if python_name.is_none() {
+                    // Strip off "delete_" prefix if needed
+                    *python_name = strip_fn_name("delete_");
+                }
+
+                FnType::Deleter(parse_receiver("expected receiver for `#[deleter]`")?)
+            }
             [first, rest @ .., last] => {
                 // Join as many of the spans together as possible
                 let span = rest
@@ -872,8 +892,10 @@ impl<'a> FnSpec<'a> {
     /// and/or attributes. Prepend the callable name to make a complete `__text_signature__`.
     pub fn text_signature_call_signature(&self) -> Option<String> {
         let self_argument = match &self.tp {
-            // Getters / Setters / ClassAttribute are not callables on the Python side
-            FnType::Getter(_) | FnType::Setter(_) | FnType::ClassAttribute => return None,
+            // Getters / Setters / deleter / ClassAttribute are not callables on the Python side
+            FnType::Getter(_) | FnType::Setter(_) | FnType::Deleter(_) | FnType::ClassAttribute => {
+                return None
+            }
             FnType::Fn(_) => Some("self"),
             FnType::FnModule(_) => Some("module"),
             FnType::FnClass(_) => Some("cls"),
@@ -894,6 +916,7 @@ enum MethodTypeAttribute {
     StaticMethod(Span),
     Getter(Span, Option<Ident>),
     Setter(Span, Option<Ident>),
+    Deleter(Span, Option<Ident>),
     ClassAttribute(Span),
 }
 
@@ -905,6 +928,7 @@ impl MethodTypeAttribute {
             | MethodTypeAttribute::StaticMethod(span)
             | MethodTypeAttribute::Getter(span, _)
             | MethodTypeAttribute::Setter(span, _)
+            | MethodTypeAttribute::Deleter(span, _)
             | MethodTypeAttribute::ClassAttribute(span) => *span,
         }
     }
@@ -973,6 +997,9 @@ impl MethodTypeAttribute {
         } else if path.is_ident("setter") {
             let name = extract_name(meta, "setter")?;
             Ok(Some(MethodTypeAttribute::Setter(path.span(), name)))
+        } else if path.is_ident("deleter") {
+            let name = extract_name(meta, "deleter")?;
+            Ok(Some(MethodTypeAttribute::Deleter(path.span(), name)))
         } else {
             Ok(None)
         }
@@ -981,14 +1008,15 @@ impl MethodTypeAttribute {
 
 impl Display for MethodTypeAttribute {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            MethodTypeAttribute::New(_) => "#[new]".fmt(f),
-            MethodTypeAttribute::ClassMethod(_) => "#[classmethod]".fmt(f),
-            MethodTypeAttribute::StaticMethod(_) => "#[staticmethod]".fmt(f),
-            MethodTypeAttribute::Getter(_, _) => "#[getter]".fmt(f),
-            MethodTypeAttribute::Setter(_, _) => "#[setter]".fmt(f),
-            MethodTypeAttribute::ClassAttribute(_) => "#[classattr]".fmt(f),
-        }
+        f.write_str(match self {
+            MethodTypeAttribute::New(_) => "#[new]",
+            MethodTypeAttribute::ClassMethod(_) => "#[classmethod]",
+            MethodTypeAttribute::StaticMethod(_) => "#[staticmethod]",
+            MethodTypeAttribute::Getter(_, _) => "#[getter]",
+            MethodTypeAttribute::Setter(_, _) => "#[setter]",
+            MethodTypeAttribute::Deleter(_, _) => "#[deleter]",
+            MethodTypeAttribute::ClassAttribute(_) => "#[classattr]",
+        })
     }
 }
 
@@ -1028,6 +1056,10 @@ fn ensure_signatures_on_valid_method(
                 debug_assert!(!fn_type.signature_attribute_allowed());
                 bail_spanned!(signature.kw.span() => "`signature` not allowed with `setter`")
             }
+            FnType::Deleter(_) => {
+                debug_assert!(!fn_type.signature_attribute_allowed());
+                bail_spanned!(signature.kw.span() => "`signature` not allowed with `deleter`")
+            }
             FnType::ClassAttribute => {
                 debug_assert!(!fn_type.signature_attribute_allowed());
                 bail_spanned!(signature.kw.span() => "`signature` not allowed with `classattr`")
@@ -1043,6 +1075,9 @@ fn ensure_signatures_on_valid_method(
             FnType::Setter(_) => {
                 bail_spanned!(text_signature.kw.span() => "`text_signature` not allowed with `setter`")
             }
+            FnType::Deleter(_) => {
+                bail_spanned!(text_signature.kw.span() => "`text_signature` not allowed with `deleter`")
+            }
             FnType::ClassAttribute => {
                 bail_spanned!(text_signature.kw.span() => "`text_signature` not allowed with `classattr`")
             }

pyo3-macros-backend/src/pyimpl.rs

@@ -407,6 +407,10 @@ fn method_introspection_code(spec: &FnSpec<'_>, parent: &syn::Type, ctx: &Ctx) -
             first_argument = Some("self");
             decorators.push(PythonTypeHint::local(format!("{name}.setter")));
         }
+        FnType::Deleter(_) => {
+            first_argument = Some("self");
+            decorators.push(PythonTypeHint::local(format!("{name}.deleter")));
+        }
         FnType::Fn(_) => {
             first_argument = Some("self");
         }

pyo3-macros-backend/src/pymethod.rs

@@ -282,6 +282,13 @@ pub fn gen_py_method(
             },
             ctx,
         )?),
+        (_, FnType::Deleter(self_type)) => GeneratedPyMethod::Method(impl_py_deleter_def(
+            cls,
+            self_type,
+            spec,
+            spec.get_doc(meth_attrs, ctx)?,
+            ctx,
+        )?),
         (_, FnType::FnModule(_)) => {
             unreachable!("methods cannot be FnModule")
         }
@@ -695,10 +702,7 @@ pub fn impl_py_setter_def(
             _value: *mut #pyo3_path::ffi::PyObject,
         ) -> #pyo3_path::PyResult<::std::ffi::c_int> {
             use ::std::convert::Into;
-            let _value = #pyo3_path::impl_::pymethods::BoundRef::ref_from_ptr_or_opt(py, &_value)
-                .ok_or_else(|| {
-                    #pyo3_path::exceptions::PyAttributeError::new_err("can't delete attribute")
-                })?;
+            let _value = #pyo3_path::impl_::pymethods::BoundRef::ref_from_ptr(py, &_value);
             #init_holders
             #extract
             #warnings
@@ -854,6 +858,74 @@ pub fn impl_py_getter_def(
     }
 }
 
+pub fn impl_py_deleter_def(
+    cls: &syn::Type,
+    self_type: &SelfType,
+    spec: &FnSpec<'_>,
+    doc: PythonDoc,
+    ctx: &Ctx,
+) -> Result<MethodAndMethodDef> {
+    let Ctx { pyo3_path, .. } = ctx;
+    let python_name = spec.null_terminated_python_name();
+    let mut holders = Holders::new();
+    let deleter_impl = impl_call_deleter(cls, spec, self_type, &mut holders, ctx)?;
+    let wrapper_ident = format_ident!("__pymethod_delete_{}__", spec.name);
+    let warnings = spec.warnings.build_py_warning(ctx);
+    let init_holders = holders.init_holders(ctx);
+    let associated_method = quote! {
+        unsafe fn #wrapper_ident(
+            py: #pyo3_path::Python<'_>,
+            _slf: *mut #pyo3_path::ffi::PyObject,
+        ) -> #pyo3_path::PyResult<::std::ffi::c_int> {
+            #init_holders
+            #warnings
+            let result = #deleter_impl;
+            #pyo3_path::impl_::callback::convert(py, result)
+        }
+    };
+
+    let method_def = quote! {
+        #pyo3_path::impl_::pymethods::PyMethodDefType::Deleter(
+            #pyo3_path::impl_::pymethods::PyDeleterDef::new(
+                #python_name,
+                #cls::#wrapper_ident,
+                #doc
+            )
+        )
+    };
+
+    Ok(MethodAndMethodDef {
+        associated_method,
+        method_def,
+    })
+}
+
+fn impl_call_deleter(
+    cls: &syn::Type,
+    spec: &FnSpec<'_>,
+    self_type: &SelfType,
+    holders: &mut Holders,
+    ctx: &Ctx,
+) -> Result<TokenStream> {
+    let (py_arg, args) = split_off_python_arg(&spec.signature.arguments);
+    let slf = self_type.receiver(cls, ExtractErrorMode::Raise, holders, ctx);
+
+    if !args.is_empty() {
+        bail_spanned!(spec.name.span() =>
+            "deleter function can have at most one argument ([pyo3::Python,])"
+        );
+    }
+
+    let name = &spec.name;
+    let fncall = if py_arg.is_some() {
+        quote!(#cls::#name(#slf, py))
+    } else {
+        quote!(#cls::#name(#slf))
+    };
+
+    Ok(fncall)
+}
+
 /// Split an argument of pyo3::Python from the front of the arg list, if present
 fn split_off_python_arg<'a, 'b>(args: &'a [FnArg<'b>]) -> (Option<&'a PyArg<'b>>, &'a [FnArg<'b>]) {
     match args {
@@ -865,7 +937,7 @@ fn split_off_python_arg<'a, 'b>(args: &'a [FnArg<'b>]) -> (Option<&'a PyArg<'b>>
 pub enum PropertyType<'a> {
     Descriptor {
         field_index: usize,
-        field: &'a syn::Field,
+        field: &'a Field,
         python_name: Option<&'a NameAttribute>,
         renaming_rule: Option<RenamingRule>,
     },