What a Session Remembers

In Python in Practice you sent one requests.get with a timeout, called raise_for_status(), and decoded the JSON. Each call like that stands alone. In Chapter 7 you needed more for two requests in a row: a login and a /me that knew about it. You built make_cookie_opener, an opener with a cookie jar, and sent both requests through it in login_and_me. In Chapter 9 you wrote fetch_many so that several requests could share one connection.

A requests.Session is that opener, done properly. It is one object you send every request through, and it carries what one request leaves behind for the next. This chapter goes back to requests, and later httpx, now that you can name the mechanism behind each feature.

import requests

with requests.Session() as session:
    session.post("http://books.test/login", auth=("ana", "correct horse"), timeout=(1.0, 2.0))
    reply = session.get("http://books.test/me", timeout=(1.0, 2.0))

session.post and session.get take the same arguments as requests.post and requests.get. There is also session.request("POST", url, ...), which takes the method as text. auth=(user, password) writes the Authorization: Basic line for you; Lesson 2 looks at how.

What a session keeps

Three things a session keeps matter here, and each carries over from one call to the next.

Cookies. session.cookies is the jar. Its class, RequestsCookieJar, is a subclass of the http.cookiejar.CookieJar you used in Chapter 7, and it follows the same rules: it reads every Set-Cookie line in a reply and sends the cookies that match the host and path with each later request. You never copy a cookie by hand.

Default headers. session.headers holds the headers sent with every request. A new session already has four, which requests adds unasked:

User-Agent: python-requests/VERSION
Accept-Encoding: gzip, deflate, zstd
Accept: */*
Connection: keep-alive

VERSION stands for the version of requests installed here. The zstd is there because the Python these lessons were checked on, 3.14, can decode that compression; on an older Python the line ends at deflate. You add to them like a dictionary: session.headers["accept"] = "application/json". The names ignore case, as header names do, so that line replaces Accept: */*. Lesson 5 says what the four are for. Assigning a new dict to session.headers throws the four away; change the one you have.

Connections. A session keeps a pool of open connections, one per server. Your server speaks HTTP/1.1, so after a reply the connection stays open, and the session’s next request to the same server goes out on it. That is Chapter 9’s keep-alive, done for you.

What a session does not keep

A timeout. Session has no timeout setting at all, and the obvious guess fails quietly: session.timeout = 2 stores an attribute that requests never reads, and the next call can wait without limit. The only way to bound a call is timeout= on that call, every time.

This course passes TIMEOUT = (1.0, 2.0), a pair, as in Python in Practice: at most 1 second to connect, then at most 2 seconds for each read. Both learner files define it at the top. A function that takes a timeout argument passes it on with timeout=timeout.

Close it

A session holds connections, so close it when you are done, with the same with statement you use for files and sockets: with make_session() as session: closes the session when the block ends.

One detail of the library versions this course runs: closing the session ends a connection only once your program no longer holds any response that came over it. A response kept in a variable, or an HTTPError that carries one, keeps its connection open until it is gone, or until your server’s 2-second idle limit from Chapter 9 ends it. pl_http closes its sessions’ connections itself, so its runs never wait for that.

Your task

Two functions, in two files.

1. In reading_client.py, make_session() returns a new requests.Session() whose default headers also say accept: application/json. Lesson 6 builds the command-line client on it.

2. In side_by_side.py, who_am_i(base_url, user, password, *, session, timeout=TIMEOUT) logs in and asks who you are, on the session it is given:

   • POST base_url + "/login" with auth=(user, password) and timeout=timeout;

   • response.raise_for_status(), so a refused login raises HTTPError before anything else is sent;

   • GET base_url + "/me" with timeout=timeout;

   • return response.json()["user"].

Use the session you are given for both requests. Do not make another, and do not call requests.post directly: the cookie from the login lives in that session’s jar, and only that session sends it back.

Then run the helper:

python pl_http.py requests-session

pl_http starts your server and gives who_am_i a session of its own. That session sends to your server on this machine through a handler pl_http mounts on it, so the name books.test is never looked up. Before you write anything, each call ends in raised NotImplementedError: not written yet: Lesson 1. After:

--- requests and replies ---
request 1  POST /login  ->  200 OK  (connection 1)
request 2  GET /me  (with a cookie line)  ->  200 OK  (connection 1)
--- your who_am_i() on pl_http's session ---
value: 'ana'
--- requests and replies ---
request 1  POST /login  ->  401 Unauthorized  (connection 2)
--- your who_am_i() on a second session, with a wrong password ---
raised HTTPError: 401 Client Error: Unauthorized for url: http://books.test/login
--- requests and replies ---
--- the cookies in the first session's jar ---
session: 'domain books.test, path /, HttpOnly'

Read it top to bottom. The /me request carried a cookie line you never wrote; the jar shows the cookie your server set, with the attributes from Chapter 7. Both requests of the first session went out on connection 1. The second session, with a wrong password, opened connection 2, got 401, and raise_for_status() turned that into an HTTPError, so /me was never asked. The result block ends with serve() returned after 2 connections; the server is closed.

Press Check my work. Lesson 2 maps the rest of requests’ features to the code you wrote by hand, and finds one place where auth= and your own Basic header disagree.