Astral is building a package manager by the name of uv, which has come heavily into the spotlight recently due to how well it performs with Python package management.
uv embraces the toml file format with pyproject.toml. This file allows us to define a single source of truth for environment configurations, project metadata, and tool configuration.
» Related reading for uv projects: installing dependencies in-line with uv, using requirements.txt for your uv build
However, this file format isn’t only scoped to uv - a large portion of the Python ecosystem is also using the TOML file format.
What is TOML? Why is it useful?
Tom’s Obvious Minimal Language, or TOML, serves a broader usage beyond packaging. Traditionally, you’d use a file format like json or yaml, but there’s a few caveats to this:
JSON doesn’t allow for comments
YAML allows for comments, but is whitespace sensitive.
TOML fixes both of these issues these file types presents.
What is the tomllib library?
The tomllib module is part of Python’s standard library introduced in Python 3.11. It’s a library that flies under many developers radar (mine included) despite being used by major tools such as pip, pytest, mypy, Black, and many more.
In fact, it’s a library that was driven by community adoption. Prior to Python 3.11, a third-party library called tomli had become essential to the ecosystem. PEP 680 had formalized what the community had already decided: TOML belonged in the standard library.
The PEP even cited flake8's reason for not adopting TOML configuration - they were waiting on standard library support.
When are some scenarios where I’d use this module?
The module is very simple and minimal to use: it provides two functions, both of which return a Python dictionary:
tomllib.load(): reads from a file objecttomllib.loads(): reads from a string
If you have configuration files that are in TOML, this library might be of use to you:
import tomllib
with open("config.toml", "rb") as f:
config = tomllib.load(f)
db_host = config["database"]["host"]
debug_mode = config.get("debug", False)Another use case might be when you want to read your own pyproject.toml for a CLI tool - you can treat the file as a source of truth for the project’s version and dependencies:
import tomllib
from pathlib import Path
import click
def get_version():
pyproject = Path(__file__).parent.parent / "pyproject.toml"
with open(pyproject, "rb") as f:
data = tomllib.load(f)
return data["project"]["version"]
@click.group()
def cli():
pass
@cli.command()
def version():
click.echo(get_version())
if __name__ == "__main__":
cli()» Related reading: Click vs argparse: which CLI package is better?
Happy coding!
📧 Join the Python Snacks Newsletter! 🐍
Want even more Python-related content that’s useful? Here’s 3 reasons why you should subscribe the Python Snacks newsletter:
Get Ahead in Python with bite-sized Python tips and tricks delivered straight to your inbox, like the one above.
Exclusive Subscriber Perks: Receive a curated selection of up to 6 high-impact Python resources, tips, and exclusive insights with each email.
Get Smarter with Python in under 5 minutes. Your next Python breakthrough could just an email away.
You can unsubscribe at any time.
Interested in starting a newsletter or a blog?
Do you have a wealth of knowledge and insights to share with the world? Starting your own newsletter or blog is an excellent way to establish yourself as an authority in your field, connect with a like-minded community, and open up new opportunities.
If TikTok, Twitter, Facebook, or other social media platforms were to get banned, you’d lose all your followers. This is why you should start a newsletter: you own your audience.
This article may contain affiliate links. Affiliate links come at no cost to you and support the costs of this blog. Should you purchase a product/service from an affiliate link, it will come at no additional cost to you.
