I don't think this is the behavior we want to introduce. We should still allow users to override with an explicit value for "description" in __schema__. A really easy way to achieve that should be to move the implementation from __modify_schema__ to __schema__ where you can literally just do {..., "description": cls.__doc__}.

But I don't think that it will have the intended effect. Consider:

class FancyScore(float, Closed, low=0, high=10):
    """My fancy description"""

Now if I call schema() on a model using it, as I understand, the chain would go:

• FancyScore.__modify_schema__() (which is SchemaField.__modify_schema__)
• uses FancyScore.__schema__()
• which inherits Closed.__schema__() <- provides a default description overriding what follows below
• which uses super().__schema__() (possibly through a few superclasses)
• which uses SchemaField.__schema__() <- where you propose to add the docstring

(if FancyScore would also define __schema__, it would not change that general logic and problem)

If you think that __schema__ should have priority over the docstring, then a different approach is needed - in that case we need to recognize where the description came from - was it overridden in the same class inside __schema__, or was it inherited from a base class? If it was inherited, the docstring of the current class should provide the default.

Without changing the general machinery, this would only be achievable ad-hoc by modifying all __schema__ methods. Actually, not sure how this could be done most elegantly without sandwiching some other method into the cascade or introducing metaclass magic (like: check __schema__ of the base class and the new class, compare description - if it changed/was not present before, then it was overriden. If it was not overridden, use docstring)

Ah, thanks for the detailed description of the problem, I didn't have all the pieces in my head. I'll have to tinker with it a bit to see if I can come up with something. Otherwise I'll probably be reluctant to introduce this feature, unfortunately.

Sure, no problem! I think the Meta class approach could work, in principle.

When a new class is subclassed:

• no docstring -> all good
• docstring, no defined schema method -> generate schema method with docstring as description
• docstring, defines schema method -> call both inherited and new method to see if description (if any) is "new", if not there or not new, wrap method to add the docstring to the result.

That way it would have the desired behavior, but it's up to you to decide if this is an acceptable solution. The last case is "ugly", but still it's a check needed only once during class creation, and it could (I actually expect it to) be a rare case that both things are present.

Sorry for the long wait here, I have now looked closer and your assessment is probably correct, however, that makes me not want to introduce this feature as-is.

I think an alternative, if you think it's worth pursuing, would be introduce a class parameter. This is what I think the spec should be:

class Base(str, Phantom):
    @classmethod
    def __schema__(cls) -> Schema:
        return super().__schema__() | {"description": "base description"}

class A(Base):
    """docstring"""

    @classmethod
    def __schema__(cls) -> Schema:
        return super().__schema__() | {"description": "explicit override"}

class B(Base, docstring_description=True):
    """docstring"""

    @classmethod
    def __schema__(cls) -> Schema:
        return super().__schema__() | {"description": "explicit override"}

class C(Base):
    """docstring"""

class Base2(str, Phantom, docstring_description=True):
    """base docstring"""

class D(Base2):
    """docstring"""
    
class DataModel(pydantic.BaseModel):
    a: A
    b: B
    c: C
    d: D

assert DataModel.schema()["properties"]["a"]["description"] == "explicit override"
assert DataModel.schema()["properties"]["b"]["description"] == "docstring"
assert DataModel.schema()["properties"]["c"]["description"] == "base description"
assert DataModel.schema()["properties"]["d"]["description"] == "base docstring"

What do you think? use_docstring might be a better name for the parameter.

So your modification (over what I proposed) is: instead of introducing the complicated checks and comparisons, to ask the user to opt-in explicitly, which would make the class docstring override any inherited or provided schema description, right?

I would be fine with that, especially if it's called use_docstring - it would still reduce a lot of boilerplate :)

issue: I don't think we should add this check, any arguments falling through will be handled by the super call.

Well I personally added it after wasting 10 minutes trying to understand why my keyword argument was not taken and it turned out that I had a typo - because the default error by the super call is absolutely not helpful and says (.... takes no keword arguments...) needlessly confusing me.

As the immediate super class does not have an init_subclass method, I decided to put it where it is to prevent passing unknown keywords to the default implementaion and getting that error.

I personally believe that such a check improves ergonomy over relying on some method upstream choke on it, but this is my personal preference and opinion. If you strongly disagree, I can remove it.

question: Can we move this to __schema__? I'd like to avoid adding logic here.

I believe we can't. If the docstring is to take precedence over what overrides of __schema__ do, it must happen at the call site of __schema__, i.e. __modify_schema__, which is what we already discussed in the initial version I pushed.

Even worse, you still might want to change other fields and thus define __schema__ to set eg another title or add examples, but the description should come from the docstring, patched over it. So it must be outside.

In your example C, I might still want docstring c as description but add other things in __schema__. If I put this into the default implementation, this whole thing cannot work. Basically see my call stack explanation above.