cattrs Structuring — ELI5

Imagine you arrive at an airport with a pile of papers — your passport in one language, boarding pass in another format, and hotel confirmation printed sideways. The check-in agent somehow reads all of it, understands what each piece means, and enters everything neatly into the computer system. Going home, the process reverses: the system spits out clean, standardized documents from your organized record.

cattrs does this for Python data. When your program receives raw data — a dictionary from a JSON API, a row from a database, or a message from a queue — cattrs takes that messy pile and converts it into proper Python objects with the right types. This process is called “structuring.” The reverse — taking Python objects and turning them back into plain dictionaries or JSON — is called “unstructuring.”

What makes cattrs clever is that it figures out how to do the conversion automatically by looking at your class definitions. If your class says it has a name (string), an age (number), and a list of hobbies (list of strings), cattrs knows exactly how to build that object from a dictionary and how to break it back down.

cattrs works especially well with the attrs library, but it also handles dataclasses, typed dictionaries, and even standard Python types like lists and tuples with type hints. You describe your data once in your class, and cattrs handles the translation in both directions.

One thing to remember: cattrs is an automatic translator between raw data (dictionaries and lists) and typed Python objects — it reads your class definitions and figures out the conversion for you.