7. Chapter review

'rb' reads raw bytes without UTF-8 decoding. Text mode ('r') corrupts any non-text file because it tries to interpret arbitrary bytes as characters; on Windows it also rewrites \r\n line endings, which mangles binary files. Using binary mode universally means the same code works for images, PDFs, and text without a per-file decision -- and the only cost is that you read bytes instead of str, which requests wants anyway for the multipart body.

A single HTTP request can have only one Content-Type header. files= switches the request to multipart/form-data; json= wants application/json. The two are mutually exclusive, so the server sees something other than what you intended (typically the multipart body without the metadata you expected), and you get a confusing 400 back. Fix: move the metadata into data=metadata. The fields then ride along as multipart form parts inside the same request.

f.read() loads the entire file into memory before requests sends a single byte. On a Hobby-plan or free-tier deployment with around 512MB of RAM, the kernel's OOM killer terminates the Python process before the upload finishes -- which is why "the upload disappears": the process is gone, so there is no error to return. Streaming via a generator (or any iterable that yields chunks) keeps memory pinned at the chunk size (8KB by default). The same code path handles a 1KB receipt and a 5GB video without changing behaviour.

With stream=True, requests fetches the response headers and leaves the body unread until you call iter_content(). That gap lets you inspect status_code, Content-Type, and Content-Length and decide whether to keep going. For untrusted URLs, this is the difference between catching a content-type mismatch (server says JPEG, sends HTML error page) at the header stage and writing several gigabytes of garbage to disk before noticing.

The bottleneck for upload-bound work is not your CPU; it is the upstream API's rate limit. Most APIs allow somewhere between 3 and 20 concurrent requests per client; once you exceed that, the server starts returning 429 and you get slower, not faster, because of the retries you now have to do. The right size is one or two below the documented concurrent limit (or empirically, the largest max_workers that does not produce 429s under load). The sequential floor (max_workers=1) is also fine for background scripts where total time does not matter; the win from concurrency is real but bounded.

"helloworld" is OCR.space's shared demo key, throttled across every developer trying the API for the first time. The most likely failure on a first reader run is an "Auth failure" or "request throttled" response from the API -- the chapter's code catches it as an IsErroredOnProcessing branch and surfaces the message. The fix is one form away: register for a free OCR.space key (around 25,000 requests per month at time of writing) and set OCRSPACE_API_KEY in your .env. The class picks it up via os.environ.get() with no code change.

The regex assumes a clean line with the literal word Total or Amount, an optional dollar sign, and exactly two decimal places. Real receipts break it in many ways: a German receipt with Gesamt or Summe instead of Total; a UK receipt where the same field is labelled Amount Due with a leading pound sign; a receipt with multiple Total lines (subtotal, tax, total) where the regex catches the first match instead of the right one; a handwritten or low-resolution receipt where OCR returns "Tota1" or "T0tal." Production receipt parsing leans on layout-aware specialist APIs (Mindee, Veryfi, AWS Textract) that combine OCR with field detection rather than free-text regex.