Python favors readable names, dictionaries, classes, exceptions, None, imports, and duck typing. Musi keeps the readable domain-first style, but asks more facts to be written down: records/data for shape, classes/instances for promised behavior, Option for expected absence, and effects for work that Python often hides behind a call that may raise.
Use this guide as a translation journal for Python code. Start with the familiar habit, then ask which Musi construct owns the same promise. A page is successful when it tells you which old instinct to keep and which old shortcut to drop.
Start from the habit that hurts
- Values, Functions, and Final Expressions - values habits get translated once, then the Musi Book owns the details.
- Blocks, Control Flow, and Repetition - blocks habits get translated once, then the Musi Book owns the details.
- Names, Mutation, and Fresh Values - mutation habits get translated once, then the Musi Book owns the details.
- Records, Objects, and Dictionaries - records habits get translated once, then the Musi Book owns the details.
- Collections and Pipelines - arrays habits get translated once, then the Musi Book owns the details.
- None, Option, and Result - absence and failure stop being side channels.
- Exceptions, Results, and Effects - outside work becomes a named request.
- Data Variants and Pattern Matching - patterns habits get translated once, then the Musi Book owns the details.
- Types, Generics, and Protocols - generics habits get translated once, then the Musi Book owns the details.
- Modules and Packages - package boundaries replace compatibility-era habits.
- Testing and Tooling - testing habits get translated once, then the Musi Book owns the details.
- Native Boundaries, Unsafe, and FFI - native edges stay narrow enough to audit.
Habits that still help
- Keep the Python habit of naming the real-world thing first.
- Drop implicit duck-typing and None sentinels when the Musi type can say the branch upfront.
- Keep examples tied to ordinary work: receipts, routes, files, animals, people, rooms, and services.
First false friend
Musi class is closer to an explicit protocol/typeclass than a Python class with attributes and methods. If you need a person, car, invoice, or package, start with records or data. If you need any type that can compare, show, encode, or step, use a class with instances.
When to switch to the Musi Book
Stay in this guide while a Python habit is getting in the way. Switch to Values and let, Records, Patterns, Generics, Classes, and Effects when you need the source-of-truth rule.