Issues in the English docs

[nilslindemann]

Found while working on the German translation.

I list this here, in order to not forget it. When done with the translation, I will take a look at these issues. This is a bit delayed currently, as I am in School for two years now (Retraining as an IT specialist, Umschulung Fachinformatiker)

I will fix easy issues, like e.g. broken links, right now, in both documents, but will push the changes to the English documents to my workbranch only. Will create a PR for these fixes when done with the translation (done).

(Self note: Backlinks: 1)

---

tutorial/query-params-str-validations.md (and later)

The VS Code type checker complains a few times in examples before the chapter tutorial/schema-extra-example.md. The first time here:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/")
async def read_items(q: str | None = None):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

These examples can be explained to the type checker, by replacing results = ... with results:dict = ....

[nilslindemann]

tutorial/response-model.md

This chapter has two info boxes which say:

FastAPI uses Pydantic model's .dict() with its exclude_unset parameter to achieve this.

and

You can also use:
response_model_exclude_defaults=True
response_model_exclude_none=True
as described in the Pydantic docs for exclude_defaults and exclude_none.

These broken links point to a v1.10 location, which is now here.

The closest related information in the current docs, which I have found, is dict(model) and iteration, where they now say, that one can simply do dict(ThePydanticModel).

I have decided to just point to the new location of the v1.10 version and otherwise keep the boxes.

---

Edit: But Body - Updates indicates that .dict() is still needed, e.g. item.dict(exclude_unset=True).

[nilslindemann]

tutorial/extra-models.md

Like above. It mentions <PydanticModel>.dict(), now one can also do dict(<PydanticModel>).

---

Edit: But Body - Updates indicates that .dict() is still needed, e.g. item.dict(exclude_unset=True).

[nilslindemann]

Idea: Shorten Annotated

After a few chapters, when the reader is used to it, the code examples could import Annotated as a:

from typing import Annotated as a

from fastapi import FastAPI, File, Form, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(
    file: a[bytes, File()],
    fileb: a[UploadFile, File()],
    token: a[str, Form()],
):
   # ...

[nilslindemann]

tutorial/request-files.md

Why is form field and form data inside ""?

I removed the "" in the last two cases.

[nilslindemann]

tutorial/dependencies/dependencies-with-yield.md

Sub-dependencies with yield:

And you could have a single dependency that requires several other dependencies with yield, etc.

Ambiguous. Does it mean:

And you could have a single dependency that requires several other dependencies which use yield, etc.

or does it mean

And you could have a single dependency that requires several other yielded dependencies, etc.

Translated with:

Und Sie könnten eine einzelne Abhängigkeit haben, die auf mehreren geyieldeten Abhängigkeiten basiert, usw.

---

Dependencies with yield and HTTPException:

If you raise any exception, it will be passed to the dependencies with yield, including HTTPException, and then again to the exception handlers.

Also ambiguous. Does it mean:

If you raise any exception, it will be passed to the dependencies with yield, including HTTPException, and to the exception handlers (from the same location).

or does it mean:

If you raise any exception, it will be passed to the dependencies with yield, including HTTPException, and from there to the exception handlers.

Translated with:

Wenn Sie eine Exception auslösen, wird diese mit yield an die Abhängigkeiten übergeben, einschließlich HTTPException, und dann erneut an die Exceptionhandler.

[nilslindemann]

tutorial/security/index.md

OpenAPI:

bearer: a header Authorization with a value of Bearer plus a token. This is inherited from OAuth2.

What is inherited, the header, the token or the whole mechanism?

[nilslindemann]

tutorial/security/oauth2-jwt.md

The VS Code type checker nags about the example, here is a possible fix:

from datetime import datetime, timedelta
from typing import Annotated

from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from jose import JWTError, jwt
from passlib.context import CryptContext
from pydantic import BaseModel

# to get a string like this run:
# openssl rand -hex 32
SECRET_KEY = "09d25e094faa6ca2556c818166b7a9563b93f7099f6f0f4caa6cf63b88e8d3e7"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30


fake_users_db = {
    "johndoe": {
        "username": "johndoe",
        "full_name": "John Doe",
        "email": "[email protected]",
        "hashed_password": "$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW",
        "disabled": False,
    }
}


class Token(BaseModel):
    access_token: str
    token_type: str


class TokenData(BaseModel):
    username: str | None = None


class User(BaseModel):
    username: str
    email: str | None = None
    full_name: str | None = None
    disabled: bool | None = None


class UserInDB(User):
    hashed_password: str


pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

app = FastAPI()


def verify_password(plain_password, hashed_password):
    return pwd_context.verify(plain_password, hashed_password)


def get_password_hash(password):
    return pwd_context.hash(password)


def get_user(db, username: str | None):
    if username and username in db:
        user_dict = db[username]
        return UserInDB(**user_dict)


def authenticate_user(fake_db, username: str, password: str):
    user = get_user(fake_db, username)
    if not user:
        return False
    if not verify_password(password, user.hashed_password):
        return False
    return user


def create_access_token(data: dict, expires_delta: timedelta | None = None):
    to_encode = data.copy()
    if expires_delta:
        expire = datetime.utcnow() + expires_delta
    else:
        expire = datetime.utcnow() + timedelta(minutes=15)
    to_encode.update({"exp": expire})
    encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
    return encoded_jwt


async def get_current_user(token: Annotated[str, Depends(oauth2_scheme)]):
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Could not validate credentials",
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username = payload.get("sub")
        if username is None:
            raise credentials_exception
        token_data = TokenData(username=username)
    except JWTError:
        raise credentials_exception
    user = get_user(fake_users_db, username=token_data.username)
    if user is None:
        raise credentials_exception
    return user


async def get_current_active_user(
    current_user: Annotated[User, Depends(get_current_user)]
):
    if current_user.disabled:
        raise HTTPException(status_code=400, detail="Inactive user")
    return current_user


@app.post("/token", response_model=Token)
async def login_for_access_token(
    form_data: Annotated[OAuth2PasswordRequestForm, Depends()]
):
    user = authenticate_user(fake_users_db, form_data.username, form_data.password)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect username or password",
            headers={"WWW-Authenticate": "Bearer"},
        )
    access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    access_token = create_access_token(
        data={"sub": user.username}, expires_delta=access_token_expires
    )
    return {"access_token": access_token, "token_type": "bearer"}


@app.get("/users/me/", response_model=User)
async def read_users_me(
    current_user: Annotated[User, Depends(get_current_active_user)]
):
    return current_user


@app.get("/users/me/items/")
async def read_own_items(
    current_user: Annotated[User, Depends(get_current_active_user)]
):
    return [{"item_id": "Foo", "owner": current_user.username}]

[nilslindemann]

advanced/async-tests.md

Remember to instantiate objects that need an event loop only within async functions

What the heck is an object that needs an event loop only within an async function? I do not even know what an object is that needs an event loop. Actually, I don't even know what an event loop is, despite having read the sauce more than once.