update: improved error comments, naming, and added reference to the P…

…R for additional details regarding the implementation of `str`

guide/pyclass-parameters.md

@@ -19,7 +19,7 @@
 | `rename_all = "renaming_rule"` | Applies renaming rules to every getters and setters of a struct, or every variants of an enum. Possible values are: "camelCase", "kebab-case", "lowercase", "PascalCase", "SCREAMING-KEBAB-CASE", "SCREAMING_SNAKE_CASE", "snake_case", "UPPERCASE". |
 | `sequence` |  Inform PyO3 that this class is a [`Sequence`][params-sequence], and so leave its C-API mapping length slot empty. |
 | `set_all` | Generates setters for all fields of the pyclass. |
-| `str` | Implements `__str__` using the `Display` implementation of the underlying Rust datatype or by passing an optional format string `str="<format string>"`. *Note: The optional format string is only allowed for structs.  `name` and `rename_all` are incompatible with the optional format string.* |
+| `str` | Implements `__str__` using the `Display` implementation of the underlying Rust datatype or by passing an optional format string `str="<format string>"`. *Note: The optional format string is only allowed for structs.  `name` and `rename_all` are incompatible with the optional format string.  Additional details can be found in the discussion on this [PR](https://github.com/PyO3/pyo3/pull/4233).* |
 | `subclass` | Allows other Python classes and `#[pyclass]` to inherit from this class. Enums cannot be subclassed. |
 | <span style="white-space: pre">`text_signature = "(arg1, arg2, ...)"`</span> |  Sets the text signature for the Python class' `__new__` method. |
 | `unsendable` | Required if your struct is not [`Send`][params-3]. Rather than using `unsendable`, consider implementing your struct in a threadsafe way by e.g. substituting [`Rc`][params-4] with [`Arc`][params-5]. By using `unsendable`, your class will panic when accessed by another thread. Also note the Python's GC is multi-threaded and while unsendable classes will not be traversed on foreign threads to avoid UB, this can lead to memory leaks. |

pyo3-macros-backend/src/pyclass.rs

@@ -396,10 +396,10 @@ fn impl_class(
     if let Some(str) = &args.options.str {
         if str.value.is_some() {
             // check if any renaming is present
-            let renaming_conflict = field_options.iter().all(|x| x.1.name.is_none())
+            let no_naming_conflict = field_options.iter().all(|x| x.1.name.is_none())
                 & args.options.name.is_none()
                 & args.options.rename_all.is_none();
-            ensure_spanned!(renaming_conflict, str.value.span() => "The optional string format shorthand argument to `str` is incompatible with any renaming via `name` or `rename_all`.  You should remove the string format shorthand argument and implement the `Display` trait or implement `__str__` directly.");
+            ensure_spanned!(no_naming_conflict, str.value.span() => "The format string syntax is incompatible with any renaming via `name` or `rename_all`");
         }
     }
 
@@ -836,7 +836,7 @@ fn impl_enum(
     ctx: &Ctx,
 ) -> Result<TokenStream> {
     if let Some(str_fmt) = &args.options.str {
-        ensure_spanned!(str_fmt.value.is_none(), str_fmt.value.span() => "string formatter shorthand cannot be used with enums, please implement `Display` or `__str__` directly")
+        ensure_spanned!(str_fmt.value.is_none(), str_fmt.value.span() => "The format string syntax cannot be used with enums")
     }
 
     match enum_ {

tests/ui/invalid_pyclass_args.stderr

@@ -102,25 +102,25 @@ error: invalid format string: expected `'}'`, found `'$'`
     |
     = note: if you intended to print `{`, you can escape it using `{{`
 
-error: The optional string format shorthand argument to `str` is incompatible with any renaming via `name` or `rename_all`.  You should remove the string format shorthand argument and implement the `Display` trait or implement `__str__` directly.
+error: The format string syntax is incompatible with any renaming via `name` or `rename_all`
    --> tests/ui/invalid_pyclass_args.rs:126:29
     |
 126 | #[pyclass(name = "aaa", str="unsafe: {unsafe_variable}")]
     |                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-error: The optional string format shorthand argument to `str` is incompatible with any renaming via `name` or `rename_all`.  You should remove the string format shorthand argument and implement the `Display` trait or implement `__str__` directly.
+error: The format string syntax is incompatible with any renaming via `name` or `rename_all`
    --> tests/ui/invalid_pyclass_args.rs:132:29
     |
 132 | #[pyclass(name = "aaa", str="unsafe: {unsafe_variable}")]
     |                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-error: The optional string format shorthand argument to `str` is incompatible with any renaming via `name` or `rename_all`.  You should remove the string format shorthand argument and implement the `Display` trait or implement `__str__` directly.
+error: The format string syntax is incompatible with any renaming via `name` or `rename_all`
    --> tests/ui/invalid_pyclass_args.rs:137:15
     |
 137 | #[pyclass(str="unsafe: {unsafe_variable}")]
     |               ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-error: The optional string format shorthand argument to `str` is incompatible with any renaming via `name` or `rename_all`.  You should remove the string format shorthand argument and implement the `Display` trait or implement `__str__` directly.
+error: The format string syntax is incompatible with any renaming via `name` or `rename_all`
    --> tests/ui/invalid_pyclass_args.rs:143:52
     |
 143 | #[pyclass(rename_all = "SCREAMING_SNAKE_CASE", str="{a_a}, {b_b}, {c_d_e}")]
@@ -138,7 +138,7 @@ error: No member found, you must provide a named or positionally specified membe
 157 | #[pyclass(str="{}")]
     |               ^^^^
 
-error: string formatter shorthand cannot be used with enums, please implement `Display` or `__str__` directly
+error: The format string syntax cannot be used with enums
    --> tests/ui/invalid_pyclass_args.rs:164:19
     |
 164 | #[pyclass(eq, str="Stuff...")]