Your Handler as Path Operations

Here is the part of your Chapter 9 handle that answers /books/{id}, from the reading_server.py in this chapter’s files, with the write branches left out:

elif len(segments) == 2 and segments[0] == "books":
    book_id = book_id_from(segments[1])
    ...
    elif book_id is None or book_id not in state["books"]:
        response = json_error(404, "no book has that id")
    elif method == "GET" or method == "HEAD":
        response = add_validators(json_response(200, state["books"][book_id]))
    ...
    else:
        response = not_allowed("GET, HEAD, PUT, DELETE")
...
if method == "HEAD":
    response["body"] = b""

Read it as two kinds of line. A few lines decide something about the reading list: an id names a book only when the state holds it, an unknown book is a 404, and a found book is the answer. The rest is plumbing. path_segments split and decoded the target before this branch, and the comparisons on segments routed the request here. book_id_from turns text into an int. json_response encodes the dict as UTF-8 JSON and counts its bytes into content-length. not_allowed refuses other methods with a 405 and an allow list, and the last lines drop the body of a reply to HEAD. You wrote every one of them, so you know what a reply contains.

A framework takes the plumbing and leaves you the decisions. This chapter rewrites the reading list with FastAPI, a widely used Python web framework, in a new file, reading_app.py. Your Chapter 9 server stays beside it, unchanged, for comparison. The app keeps the five routes of Chapter 5: GET and POST on /books, and GET, PUT and DELETE on /books/{id}. Login, tokens, redirects and ETags stay with your own server.

Reading the decorator

Open reading_app.py. Near the top, app = FastAPI() makes the application object. Lower down are five functions whose bodies only raise NotImplementedError, each with a line above it that starts with @:

@app.get("/books/{book_id}")
def get_book(book_id: int):
    """Return one book, or raise HTTPException with status 404."""

@app.get("/books/{book_id}") registers the function below it with the app, for GET requests whose path matches /books/{book_id}. When such a request arrives, FastAPI calls get_book. Registering calls nothing, and the function itself stays an ordinary function: once you have written it, reading_app.get_book(1) works when you call it yourself, with no request anywhere.

A line that starts with @ above a def is a decorator. Python Fundamentals II teaches decorators, classes, and annotations in full. This course never asks you to write any of them: every @app line the chapter needs is already in the file, and you write function bodies only.

Annotations FastAPI reads

The {book_id} in the path names a part of the URL, and book_id: int in the def line connects it to the parameter. In Lesson 4.1, the annotation request: dict was a note that Python ignores. FastAPI reads this one: it takes the path segment, turns it into an int before calling your function, and answers 422 itself when it cannot. So inside get_book, book_id is always an int. Your server answered 404 for /books/abc, because book_id_from returned None; this app answers 422.

The same file holds a model, a class that describes data:

class BookIn(BaseModel):
    """The JSON object a POST or PUT body must be."""

    title: str = Field(pattern=r"\S")
    author: str = Field(pattern=r"\S")

It describes the JSON object a POST or PUT body must be: an object whose title and author are strings with at least one character that is not a space. FastAPI checks every body against it before your function runs. You use it in Lesson 3. list_books also has an annotated parameter, limit, which Lesson 5 uses; leave it alone for now.

What your function returns

A function registered this way is called a path operation, and it answers by returning a value. Return a dict, a list, a number, or None, and FastAPI encodes it as JSON (None becomes null), sets content-type: application/json and a content-length that counts the bytes, and sends status 200. For GET /books, return {"books": [...]} with the books in id order, the shape your server sent.

For an unknown id, the function raises an exception that FastAPI turns into a reply:

raise HTTPException(status_code=404, detail="no such book")

FastAPI sends a 404 whose JSON body is {"detail":"no such book"}. Your server said error where FastAPI says detail. FastAPI also writes JSON without spaces after : and ,, so the same books take fewer bytes than your server sent. Lesson 4 shows those bytes.

Where the books live

get_book(book_id) has no state parameter, because FastAPI passes a function only the parts of the request it asks for. The books live in a dictionary at the top of the module, STATE, with the shape of your server’s state: STATE["books"] maps ids to books, and STATE["next_id"] is the next id. reset_state(state) replaces its contents with the state you pass, or with the two sample books, and every test calls it first, so no test sees books another test added.

What disappeared

Your two functions will be about four lines each. Gone from your code:

• path_segments and the comparisons on segments: the paths in the @app.get lines route each request.

• book_id_from: book_id: int converts the id.

• json_response and its byte count: FastAPI encodes the dict and sets content-length.

• the not_allowed branches: FastAPI answers 405 itself when no route for a path accepts the method.

• the HEAD rule: nothing in the app mentions HEAD. Lesson 2 asks the app what it does with one.

The decisions stayed with you: what the list holds, when an id is unknown, and which status says so.

Something still has to accept connections and turn bytes into requests: uvicorn, a server program that runs apps like this one. The interface between such a server and an app is called ASGI; the name is all you need.

Your task

Write the bodies of list_books and get_book in reading_app.py:

1. list_books returns {"books": [...]}: every book in STATE["books"], in id order.

2. get_book(book_id) returns the book, or raises HTTPException(status_code=404, detail="no such book") when STATE["books"] has no such id. HTTPException is already imported.

There is no way yet to send the app a request; Lesson 2 adds one. A decorated function is still a function, so call one in the Shell tab:

python -c "import reading_app; print(reading_app.get_book(1))"

It prints {'id': 1, 'title': 'Kindred', 'author': 'Octavia E. Butler'}, the dict as Python prints it, not JSON. Then press Check my work. Lesson 2 sends the app real requests without opening a port.