Raw docstring (leading r) defeats form feed \f truncation

[jamesbraza]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to FastAPI but to Pydantic.
• I already checked if it is not related to FastAPI but to Swagger UI.
• I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from fastapi import FastAPI

app = FastAPI()


@app.post("/lof")
def foo(arg: int = 5) -> int:
    """
    Some function.
    
    \f
    
    Args:
        arg: Some argument

    Returns:
        Some integer.
    """
    return arg

Description

Running ruff==0.1.3 on this, D301 will autofix to make the docstring be a raw string (lead by r).

@app.post("/lof")
def foo(arg: int = 5) -> int:
    r"""
    Some function.
    
    \f
    
    Args:
        arg: Some argument

    Returns:
        Some integer.
    """
    return arg

However, this breaks the form feed \f truncation from working, per https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#advanced-description-from-docstring

I think form feed \f truncation should still work even if the docstring is a raw string.

Operating System

macOS

Operating System Details

n/a

FastAPI Version

0.104.0

Pydantic Version

2.4.2

Python Version

3.11.5

Additional Context

No response

[White-Mask]

Hello @jamesbraza,

Indeed, when using raw single quotes, FastAPI will not consider the character '\f,' resulting in the documentation not being truncated. According to the ruff documentation, the use of raw triple double quotes in Python docstrings is recommended in many cases, especially when you need to maintain characters that include backslashes literally. However, in the context of FastAPI, a solution can be found that allows the character '\f' to work as expected by using triple double quotes. This is clearly demonstrated in FastAPI's documentation link to FastAPI documentation.

Here's an example of how to achieve this:

from fastapi import FastAPI

app = FastAPI()


@app.post("/lof")
def foo(arg: int = 5) -> int:
    """
    Some function.
    
    \f
    
    Args:
        arg: Some argument

    Returns:
        Some integer.
    """
    return arg

In this example, you'll notice that triple single quotes are used, and the '\f' character is correctly truncated in the documentation generated by FastAPI. To prevent ruff from interfering and marking the code as a syntax error, you can add the following configuration to your pyproject.toml file:

[tool.ruff]
select = ["D301"]

FastAPI offers various ways to write documentation without being affected by this issue. One of them is using the openapi_extra parameter while keeping the docstring with raw triple double quotes:

from fastapi import FastAPI

app = FastAPI()


@app.post("/lof", openapi_extra={
    "tags": ["Tag for example routes"],
    "summary": "Summary for the route",
    "description": "Write the description of the route without characters that include backslashes, as they will not be considered when writing the OpenAPI documentation."
})
def foo(arg: int = 5) -> int:
    r"""
    Some function.
    
    \f
    
    Args:
        arg: Some argument

    Returns:
        Some integer.
    """
    return arg

Another option is to write the documentation in another file (as a constant) and add it to the route decorator in this way:

# In another file named docs.py
MY_DOC = {
    "tags": ["Tag for example routes"],
    "summary": "Summary for the route",
    "description": "For this example, you can use characters that include backslashes, as when using this method, they will be taken into account when writing the OpenAPI documentation\f.This text will not be considered."
}

# In your main file
from fastapi import FastAPI
from my_constants import MY_DOC

app = FastAPI()


@app.post("/lof", **MY_DOC)
def foo(arg: int = 5) -> int:
    r"""
    Some function.
    
    \f
    
    Args:
        arg: Some argument

    Returns:
        Some integer.
    """
    return arg

You can also add parameters directly to the route decorator, such as description, summary, tag, and others, while maintaining the docstring with raw triple double quotes:

from fastapi import FastAPI

app = FastAPI()


@app.post(
    "/",
    tags=["Tag for example routes"],
    summary="Summary for the route",
    description="For this example, you can use characters that include backslashes, as when using this method, they will be taken into account when writing the OpenAPI documentation\f.This text will not be considered."
)
def foo(arg: int = 5) -> int:
    """
    Some function.
    
    \f
    
    Args:
        arg: Some argument

    Returns:
        Some integer.
    """
    return arg

These are the solutions I've found to address this issue. Another option would be to ask @tiangolo to allow us to create an issue to request the consideration of supporting raw triple double quotes in the documentation.
Regards.

[jamesbraza]

Thank you @White-Mask ! I agree with your thoughts on the matter.

Imo the form feed \f truncation should also work for raw triple quoted strings, as raw strings are recommended by PEP 257 here. It would be good to fix this, as ruff adoption is increasing.

[Kludex]

I've created this issue: #10998