Why does tomllib.load require a file opened in binary mode ('rb')?

## Where `tomllib` came from Python 3.11 added `tomllib` to the standard library (PEP 680), after TOML had already become the default shape of Python tool configuration. It is deliberately small: `tomllib.loads(s)` parses a `str`, `tomllib.load(fp)` parses a **binary** file object, and that is the whole public surface apart from `tomllib.TOMLDecodeError`. Before 3.11 you needed a third-party parser for the same job. ## The encoding is a property of the format, not of your machine TOML's specification states that a TOML document is a valid UTF-8 encoded Unicode document. The encoding is not a per-file choice and not a platform detail — it is fixed by the format. `tomllib` therefore takes responsibility for decoding rather than letting the caller do it. `load` calls `fp.read()`, expects `bytes` back, and decodes them as UTF-8. Passing a text-mode file breaks that contract in two ways. The quiet failure is that Python has *already* decoded the file for you using the locale encoding (`locale.getencoding()`), which is UTF-8 on most Linux systems but historically something else on Windows. A config file containing a non-ASCII character then parses on your laptop and produces mojibake — or a `UnicodeDecodeError` — on a colleague's. The loud failure is what actually happens today: `load` tries to call `.decode()` on what it read, `str` has no such method, and the `AttributeError` is turned into `TypeError: File must be opened in binary mode, e.g. use `open('foo.toml', 'rb')``. The error message *is* the documentation. Note also that you cannot compromise by passing an encoding to a binary open: `open(path, 'rb', encoding='utf-8')` raises `ValueError`, because binary mode takes no encoding argument. Binary really means binary; the parser owns the decode. ```python import tomllib with open("settings.toml", "rb") as handle: # 'rb', never 'r' settings = tomllib.load(handle) ``` If you already have the text — from a network response, a test fixture, or a heredoc — use `loads`. If you want a `load`-shaped call in a test without touching the filesystem, wrap the bytes in `io.BytesIO`. ## What comes back A plain `dict`. Keys are always `str`; values map from TOML types to Python ones: string to `str`, integer to `int`, float to `float`, boolean to `bool`, array to `list`, table to `dict`, and the date-time types to `datetime.datetime`, `datetime.date` and `datetime.time`. An offset date-time carries a `tzinfo`; a local one does not. Nested tables are nested dicts, so a `[tool.section]` header becomes `data["tool"]["section"]`. Two hooks matter in practice. `parse_float` lets you swap the float constructor — passing `decimal.Decimal` keeps exact decimal values instead of binary floats. And because the result is an ordinary dict, nothing validates it: `tomllib` guarantees the document is well-formed TOML, not that it contains the keys your program needs. That validation is yours to write. ## Read-only, on purpose There is no `dump` or `dumps` in `tomllib`, and none is coming from PEP 680, which scoped the addition to reading. The reason is that writing TOML *well* is a round-tripping problem: preserving comments, key ordering, table style and quoting is a design space with more than one right answer, and the standard library declined to pick one. The practical consequence is architectural: with the standard library alone, your program reads configuration and never edits it. A "save my settings" feature needs a different format — or a third-party writer. This is the sharpest contrast with `configparser`, which does have a `write` method and can round-trip an INI file (losing comments). ## Errors `tomllib.TOMLDecodeError` subclasses `ValueError`, so a broad `except ValueError` around configuration loading catches both a malformed document and a downstream conversion failure. In 3.14 that exception carries structured detail — the message, the document, and the position of the problem — instead of only free-form text, which makes it far easier to point a user at the offending line. ## What good practice looks like Open with `open(path, "rb")` inside a `with` block; do not pass `encoding=`; catch `tomllib.TOMLDecodeError` at the boundary and report the file name alongside it; and treat the returned dict as untyped input to be validated, not as your settings object.