House-move inventory: Invoices, photos and HEIC - Part 7
~8 min read
A list of items tells customs what. An invoice tells them how much, and that it's real. And a photo of the item, or of the box before it was packed, answers every "which sofa was that?" argument. Both are files, and files don't belong in a SQLite database. This post covers where they went, and one surprisingly fiddly format.
Bytes outside the DB
Attachment bytes live on disk, next to the database, in <db dir>/attachments/ (override with $INVENTORY_ATTACHMENTS_DIR). The database stores metadata - filename, content type, size - and the file is named by an opaque id.
The code reaches the disk through a FileStore protocol with a LocalFileStore implementation, injected into InventoryService - the same pattern as the repository and the clock. Tests use a temp directory; nothing in core.py knows about paths.
That protocol creates a few obligations, which are the sort of thing that's easy to forget, so they're written down:
delete_box,remove_itemandremove_attachmentmust delete the files, not just the rows. Otherwise the attachments directory silently accumulates orphans.clone_boxcopies them, so a cloned box's invoices are independent.- Missing files are skipped, not fatal: if a file has gone from disk, the sheet that would have appended it just doesn't.
Uploads are PDF or image, with a limit. max_upload_mb started life as an environment variable and became a persisted setting (1-100) editable on the Settings page, with the env var as its default.
Three kinds of picture
It took three phases to learn that "an image of something" is several different concepts:
- Attachments (Phase 3.14): documents on an item - invoices, receipts. A PDF or an image. Many per item.
- Box photo (3.29): one optional photo per box, taken before it's packed - what it looked like, where it lived.
box_idis the primary key, so at most one; a re-upload replaces it and deletes the old file. Not copied byclone_box, because it's a photo of a specific physical box. - Item photo (3.32): one optional photo per item - what it looks like, as distinct from an invoice. Same shape and replace rule. Unlike the box photo, this one is copied by
clone_box, since it documents the kind of item.
I'd originally treated item photos as "just an image attachment". It isn't: an attachment is evidence, a photo is identification, and they show up in different places on the printed output (invoices are appended, photos lead a section). Giving them separate tables meant each could have its own rules.
On the front end, the box photo's upload/thumbnail/modal/replace/remove logic was extracted into a generic PhotoPanel once the item version needed it, so ItemPhotoPanel is a ~20-line wrapper rather than a second copy. And the file input carries capture="environment", so on a phone it can open the camera directly.
The iPhone problem
Photos taken on an iPhone are HEIC by default. Most browsers can't display HEIC, and reportlab can't embed it in a PDF. Nobody can see the photo, and the print pipeline can't use it.
Commit 541669a ("add full heic support", 28 October) fixed it at the door: inventory/images.py converts HEIC/HEIF to JPEG before it reaches the file store, for box photos, item photos and image attachments alike. The stored filename becomes *.jpg, the content type image/jpeg.
with Image.open(io.BytesIO(content)) as img:
img = ImageOps.exif_transpose(img).convert("RGB")
out = io.BytesIO()
img.save(out, format="JPEG", quality=JPEG_QUALITY)
Two details are the point of the module:
- Rotation. A HEIC file carries its orientation as metadata. The converted JPEG drops the container's rotation, so
ImageOps.exif_transposeapplies it to the pixels first. Skip that and every portrait photo comes out sideways. - Failure is a validation error. An undecodable file is a corrupt upload, not a server fault. It raises the domain
ValidationErrorand the user gets a 422 with "could not read the HEIC image".
The decoder is pillow-heif, imported lazily inside the function so the project still works without it for anyone not uploading HEIC. Converting once on upload means everything downstream - browser display, PDF embedding, caching - only ever sees JPEG and PNG. That's a pattern worth stealing: normalise at the boundary, not at every consumer.
Where it all ends up
Photos and invoices exist so they can be printed. A box sheet can lead with the box's photo and its items' photos (?photo=true) and can append every invoice (?invoices=true) - PDFs spliced in as-is, images drawn onto a page, anything unreadable replaced by a placeholder page, so one bad file doesn't sink the whole export. That's the next post.
Previous: ← Schema migrations with PRAGMA user_version · Next: Sheets, labels and French →
