Lesson 23 of 26
The crates you'll meet everywhere
Python ships json and argparse in the standard library. Rust's standard library is small on
purpose, so almost every real project adds the same few crates to Cargo.toml (lesson 17). Once you can read
these, most real Rust code looks familiar:
- serde and serde_json: turn structs into JSON and back. Like
jsonplusdataclasses, and in practice closest to pydantic, because it checks the data while it reads it. - anyhow: one error type that can hold any error, with messages that say what you were doing. Like catching
Exceptionandraise ... from e. - thiserror: your own error enum (lesson 12) with less typing. Like a family of exception classes.
- clap: command-line arguments from a struct. Like
argparse.
All of them lean on #[derive(...)] (lesson 14): you describe the data, and the crate writes the boring
code at compile time.
serde: a struct to JSON and back
#[derive(Serialize, Deserialize)] teaches serde how to write and read a User. Then
serde_json::to_string is json.dumps, and serde_json::from_str is
json.loads that builds a User directly instead of a dict. serde writes compact JSON with no
spaces, so the Python passes separators to match it.
import json
from dataclasses import asdict, dataclass
@dataclass
class User:
name: str
age: int
user = User("ada", 36)
text = json.dumps(asdict(user), separators=(",", ":"))
print(text)
back = User(**json.loads('{"name": "bob", "age": 41}'))
print(f"{back.name} is {back.age}")use serde::{Deserialize, Serialize};
#[derive(Serialize, Deserialize)]
struct User {
name: String,
age: u32,
}
fn main() {
let user = User { name: String::from("ada"), age: 36 };
let text = serde_json::to_string(&user).unwrap();
println!("{text}");
let back: User = serde_json::from_str(r#"{"name": "bob", "age": 41}"#).unwrap();
println!("{} is {}", back.name, back.age);
}{"name":"ada","age":36}
bob is 41Renamed keys, defaults, and bad input
json.loads gives you a dict, and checking its shape is your job (or pydantic's). serde checks
while it reads: if the JSON doesn't fit the struct, from_str returns an Err that says what was
wrong and where. Attributes like #[serde(rename = ...)] and #[serde(default)] adjust how a
field maps to JSON. The error texts differ, so the outputs are shown separately.
import json
from dataclasses import dataclass, field
@dataclass
class Config:
user_name: str
tags: list[str] = field(default_factory=list)
def load(text):
data = json.loads(text)
if not isinstance(data.get("userName"), str):
raise ValueError("userName must be a string")
return Config(data["userName"], data.get("tags", []))
for text in ['{"userName": "ada"}', '{"userName": 42}']:
try:
c = load(text)
print(f"{c.user_name}, {len(c.tags)} tags")
except ValueError as e:
print(f"error: {e}")use serde::Deserialize;
#[derive(Deserialize)]
struct Config {
#[serde(rename = "userName")]
user_name: String,
#[serde(default)]
tags: Vec<String>,
}
fn main() {
for text in [r#"{"userName": "ada"}"#, r#"{"userName": 42}"#] {
match serde_json::from_str::<Config>(text) {
Ok(c) => println!("{}, {} tags", c.user_name, c.tags.len()),
Err(e) => println!("error: {e}"),
}
}
}ada, 0 tags
error: invalid type: integer `42`, expected a string at line 1 column 15anyhow: any error, with context
In an application you mostly want to stop and print a good message. anyhow::Result<T> is a
Result whose error can be any error type, so ? works on all of them. .context(...)
wraps an error with a sentence about what you were doing, like raise RuntimeError(...) from e. The
original errors are worded differently in the two languages, so the outputs are shown separately.
def parse_port(text):
try:
return int(text)
except ValueError as e:
raise RuntimeError(f"bad port {text!r}") from e
for text in ["8080", "eighty"]:
try:
print(f"port {parse_port(text)}")
except RuntimeError as e:
print(f"error: {e}: {e.__cause__}")use anyhow::{Context, Result};
fn parse_port(text: &str) -> Result<u16> {
let port = text.parse::<u16>().context(format!("bad port '{text}'"))?;
Ok(port)
}
fn main() {
for text in ["8080", "eighty"] {
match parse_port(text) {
Ok(port) => println!("port {port}"),
Err(e) => println!("error: {e:#}"),
}
}
}port 8080
error: bad port 'eighty': invalid digit found in stringthiserror: an error enum instead of exception classes
A library usually wants callers to tell errors apart, so it defines its own error enum (lesson 12).
thiserror writes the boring parts: #[error("...")] is the message (the Display impl),
and #[from] lets ? convert another error into yours. A common rule of thumb: thiserror in
libraries, anyhow in applications.
class ShopError(Exception):
pass
class NotFound(ShopError):
def __init__(self, item):
super().__init__(f"no item called {item}")
class BadQuantity(ShopError):
def __init__(self):
super().__init__("bad quantity")
def order(item, qty_text):
if item != "apple":
raise NotFound(item)
try:
qty = int(qty_text)
except ValueError as e:
raise BadQuantity() from e
return f"{qty} x {item}"
for item, qty in [("apple", "3"), ("pear", "1"), ("apple", "lots")]:
try:
print(order(item, qty))
except ShopError as e:
print(f"error: {e}")use std::num::ParseIntError;
use thiserror::Error;
#[derive(Debug, Error)]
enum ShopError {
#[error("no item called {0}")]
NotFound(String),
#[error("bad quantity")]
BadQuantity(#[from] ParseIntError),
}
fn order(item: &str, qty_text: &str) -> Result<String, ShopError> {
if item != "apple" {
return Err(ShopError::NotFound(String::from(item)));
}
let qty: u32 = qty_text.parse()?;
Ok(format!("{qty} x {item}"))
}
fn main() {
for (item, qty) in [("apple", "3"), ("pear", "1"), ("apple", "lots")] {
match order(item, qty) {
Ok(text) => println!("{text}"),
Err(e) => println!("error: {e}"),
}
}
}3 x apple
error: no item called pear
error: bad quantityclap: argparse from a struct
With clap you write a struct, and #[derive(Parser)] turns it into a parser. Field names become
argument names, field types do the conversion and checking, and --help is generated for you. A bad
argument prints a usage message and exits with code 2, as with argparse.
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("name")
parser.add_argument("--times", type=int, default=1)
parser.add_argument("--shout", action="store_true")
args = parser.parse_args()
text = f"hello, {args.name}"
if args.shout:
text = text.upper()
for _ in range(args.times):
print(text)use clap::Parser;
#[derive(Parser)]
struct Args {
name: String,
#[arg(long, default_value_t = 1)]
times: u32,
#[arg(long)]
shout: bool,
}
fn main() {
let args = Args::parse();
let mut text = format!("hello, {}", args.name);
if args.shout {
text = text.to_uppercase();
}
for _ in 0..args.times {
println!("{text}");
}
}HELLO, ADA
HELLO, ADAWhere the Python analogy breaks
- serde checks the shape while it reads.
json.loadsgives you a plain dict and leaves the checking to you, or to pydantic. Reading into a struct withserde_json::from_strfails with a message such as "missing field" or "invalid type", plus a line and column. - Unknown keys are ignored by default. A JSON key with no matching field is skipped without an error, as in a default
pydantic model. Add
#[serde(deny_unknown_fields)]to the struct to make it an error. - serde writes compact JSON:
serde_json::to_stringgives{"a":1}, whilejson.dumpsgives{"a": 1}. Useto_string_prettyfor indented output. - Errors are values, not a class hierarchy. A family of exception subclasses becomes one enum, and
except NotFoundbecomes amatcharm. There is no "catch this class and all its children", but ananyhow::Errorcan hold any error. - These crates are not built in. Python ships
jsonandargparse; in Rust you add serde, anyhow, thiserror and clap toCargo.tomlwithcargo add(lesson 17). Nearly every project does.
Cheat card
| Python | Rust |
|---|---|
json.dumps(obj, separators=(",", ":")) | serde_json::to_string(&obj)? |
json.dumps(obj, indent=2) | serde_json::to_string_pretty(&obj)? |
User(**json.loads(text)) | let user: User = serde_json::from_str(text)?; |
@dataclass # or a pydantic model | #[derive(Serialize, Deserialize)] |
Field(alias="userName") # pydantic | #[serde(rename = "userName")] |
tags: list = field(default_factory=list) | #[serde(default)] |
raise RuntimeError("...") from e | result.context("...")? // anyhow |
except Exception as e: | fn main() -> anyhow::Result<()> |
class NotFound(ShopError): ... | #[derive(Debug, Error)] enum ShopError { #[error("...")] NotFound } |
raise BadQuantity() from e | BadQuantity(#[from] ParseIntError) // then ? converts |
argparse.ArgumentParser() | #[derive(Parser)] struct Args { ... } |
parser.add_argument("--times", type=int, default=1) | #[arg(long, default_value_t = 1)] times: u32 |
parser.add_argument("--shout", action="store_true") | #[arg(long)] shout: bool |
args = parser.parse_args() | let args = Args::parse(); |