Should we use textwrap.dedent on descriptions?

[patrick91]

Let's say we have this code:

@strawberry.type(description="A connection to a list of items.")
class VehicleFilmsConnection:
    page_info: PageInfo = strawberry.field(
        description="Information to aid in pagination."
    )
    edges: list[VehicleFilmsEdge | None] | None = strawberry.field(
        description="A list of edges."
    )
    total_count: int | None = strawberry.field(
        description="""
A count of the total number of objects in this connection, ignoring pagination.
This allows a client to fetch the first five objects by passing "5" as the
argument to "first", then fetch the total count so it could display "5 of 83",
for example.
"""
    )
    films: list[Film | None] | None = strawberry.field(
        description="""
A list of all of the objects returned in the connection. This is a convenience
field provided for quickly exploring the API; rather than querying for
"{ edges { node } }" when no edge data is needed, this field can be be used
instead. Note that when clients like Relay need to fetch the "cursor" field on
the edge to enable efficient pagination, this shortcut cannot be used, and the
full "{ edges { node } }" version should be used instead.
"""
    )

We could allow users to actually write this:

@strawberry.type(description="A connection to a list of items.")
class VehicleFilmsConnection:
    page_info: PageInfo = strawberry.field(
        description="Information to aid in pagination."
    )
    edges: list[VehicleFilmsEdge | None] | None = strawberry.field(
        description="A list of edges."
    )
    total_count: int | None = strawberry.field(
        description="""
            A count of the total number of objects in this connection, ignoring pagination.
            This allows a client to fetch the first five objects by passing "5" as the
            argument to "first", then fetch the total count so it could display "5 of 83",
            for example.
        """
    )
    films: list[Film | None] | None = strawberry.field(
        description="""
            A list of all of the objects returned in the connection. This is a convenience
            field provided for quickly exploring the API; rather than querying for
            "{ edges { node } }" when no edge data is needed, this field can be be used
            instead. Note that when clients like Relay need to fetch the "cursor" field on
            the edge to enable efficient pagination, this shortcut cannot be used, and the
            full "{ edges { node } }" version should be used instead.
        """
    )

which is quite nicer than what we had before, but it would include the spaces in the outputted schema, but we could run textwrap.dedent (plus strip to fix this), what do you think?

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• We receive the funding once the issue is completed & confirmed by you.
• Thank you in advance for helping prioritize & fund our backlog.

[patrick91]

we could also revisit the PR to add support for descriptions like this:

@strawberry.type
class VehicleFilmsConnection:
    """A connection to a list of items."""

    page_info: PageInfo
    "Information to aid in pagination."

    edges: list[VehicleFilmsEdge | None] | None
    "A list of edges."

    total_count: int | None
    """
    A count of the total number of objects in this connection, ignoring pagination.
    This allows a client to fetch the first five objects by passing "5" as the
    argument to "first", then fetch the total count so it could display "5 of 83",
    for example.
    """

    films: list[Film | None] | None
    """
    A list of all of the objects returned in the connection. This is a convenience
    field provided for quickly exploring the API; rather than querying for
    "{ edges { node } }" when no edge data is needed, this field can be be used
    instead. Note that when clients like Relay need to fetch the "cursor" field on
    the edge to enable efficient pagination, this shortcut cannot be used, and the
    full "{ edges { node } }" version should be used instead.
    """

but we would still need to dedent (and support passing description to strawberry.field/type)