Implement parsing of default command configuration from `pyproject.toml` by max-moser · Pull Request #1290 · python-babel/babel

max-moser · 2026-07-07T13:36:38Z

I believe this should close #777

This PR adds support of pyproject.toml as a source for default configuration values for the various CLI commands (compile, extract, init, update).
The configuration will be read from pyproject.toml, under the [tool.babel.<command_name>] table, where <command_name> is one of compile_catalog, extract_messages, init_catalog, update_catalog (taken from frontend_setuptools).

The motivation for this PR here is that I've recently migrated most of the inveniosoftware packages from setuptools to hatchling and we included the old configuration from setup.cfg in pyproject.toml, only to find that pybabel doesn't actually read any command config from pyproject.toml 😅
(Luckily for us that was only a minor issue in one package that we fixed otherwise)

The mechanism for finding pyproject.toml is similar to that used in other tools, like isort.
I could also imagine adding a global CLI flag for disabling reading pyproject.toml altogether, or for letting users specify another TOML config file instead.

The parsed values are inserted as default values for the optparse parser, so user-provided CLI flags should still take precedence.

Please let me know if this goes in an acceptable direction, then I can polish up the implementation a bit 🙂

akx

This would require tests -- oh and what happens if this finds a pyproject.toml that doesn't have tool.babel?

max-moser · 2026-10-30T09:54:17Z

Thanks for the review, I'll spruce up the PR a bit. 🙂

max-moser

I've touched up the PR a bit to address your feedback (especially the case when the section is missing from pyproject.toml) and generally touched up the implementation a little bit (with type hints and such).

There's now a test case for the config parsing itself, and one for the extract_messages CLI command that basically emulates what another test did, but with the config coming from pyproject.toml instead of CLI args.

akx

Thanks! Some comments -- this is looking pretty good.

I think we might want a BABEL_NO_PYPROJECT_TOML escape hatch for now?

akx · 2026-11-04T06:32:43Z

+    """
+    Fixture to create ``${data_dir}/pyproject.toml`` and clean it after the test.
+    """
+    pyproject_toml = (pathlib.Path(data_dir) / "pyproject.toml")
+    pyproject_toml.touch()
+    yield pyproject_toml
+    pyproject_toml.unlink()


This will cause race conditions when tests are being run in parallel with e.g. pytest-xdist.

See e.g. the pot_file fixture that uses tmp_path - could we do something like that here?

Hmm... Yeah, I haven't considered running multiple test suites in parallel, only sequentially.
With the current "simply search up the FS hierarchy" strategy as is, I think we're out of luck since any test run would pick up the pyproject.toml.

I'll investigate a mechanism to specify an pyproject.toml file explicitly for pybabel to use; that should then make use of the tmp_path simple.
Maybe that could be combined with your suggestion of BABEL_NO_PYPROJECT_TOML, slightly renamed?

E.g. as an environment variable BABEL_PYPROJECT_TOML that lets the user specify the file to use explicitly, and bails out e.g. if set to 0 or similar?

It's fine for now, I think. You can just add a # TODO: this will not work in pytest-xdist so we remember it later.

Ehh, I went ahead and just implemented the combined "alternative search path"/escape hatch via an env var for now.

An alternative would be to add a new optparse option in CommandLineInterface.run()?
It looks like the first bunch of argument parsing happens before we ever touch the pyproject.toml config, and could thus use it to skip it?

The benefit here would be that basically it's documented for free.
The downside is that it's harder to remove later on because that's a much more prominent spot that people may come to rely on.

WDYT?

akx · 2026-11-04T06:34:17Z

+
+def test_parse_pyproject_toml_config_without_pyproject_toml_file(tmp_path):
+    """
+    Test that trying to parse the config from a missing ``pyproject.toml`` doesn't crash.


This too could fail in the esoteric case that someone has a stray pyproject.toml somewhere in their tmp hierarchy... but maybe we'll take that chance.

akx

Some comments -- not sure if you're still actively pushing here rn :)

max-moser · 2026-11-05T13:57:50Z

Done pushing now :)

akx

Non-exhaustive review, some notes.. 😅

akx · 2026-11-09T09:49:40Z

+            except ConfigurationError:
+                self.log.error("Unable to parse configuration from pyproject.toml!")


Suggested change

except ConfigurationError:

self.log.error("Unable to parse configuration from pyproject.toml!")

except ConfigurationError as ce:

self.log.error("Unable to parse configuration: %s", ce)

would probably be more useful for users.

Ah yeah right, I mixed up error() with exception() regarding the exception being printed:

In [6]: try: ...: raise Exception("asdf") ...: except Exception as e: ...: logging.exception("hello") ...: ERROR:root:hello Traceback (most recent call last): File "<ipython-input-6-0b066f494d6a>", line 2, in <module> raise Exception("asdf") Exception: asdf In [7]: try: ...: raise Exception("asdf") ...: except Exception as e: ...: logging.error("hello") ...: ERROR:root:hello

Possibly exception() with the printing of the stack trace would be even handier for tracking down the issue, though likely scarier for non-tech users.
Going with the formatted string in error() for now.

akx · 2026-11-09T09:54:39Z

            print(f"  {name:<{cmd_width}} {description}")

+    def _parse_pyproject_toml_config(self, cmdinst) -> dict:
+        pyproject_toml_path_override = os.getenv("BABEL_PYPROJECT_TOML", None)


Is this meant to be the TOML filename, or the directory? I think we're handling it as a directory right now.

Yes right, if somebody specifies a file then it won't be matched in the first iteration of the search.
If the desired file is called pyproject.toml, it will still be found (effectively checking the path.parent / "pyproject.toml"), but if it has a different name (e.g. anothername.toml), that won't be picked up:

In [3]: find_pyproject_toml(Path("..")) In [4]: find_pyproject_toml(Path(".")) Out[4]: PosixPath('/home/mmoser/git/babel/pyproject.toml') In [5]: find_pyproject_toml(Path("pyproject.toml")) Out[5]: PosixPath('/home/mmoser/git/babel/pyproject.toml') In [6]: find_pyproject_toml(Path("anothername.toml")) Out[6]: PosixPath('/home/mmoser/git/babel/pyproject.toml')

Given that the filename for pyproject.toml is kind of fixed here, I don't think that latter case matters, though.
Would you prefer another name for the env var?

As a side note, checking this, I actually found that a path.resolve() was missing to make path.parent work as expected:

In [7]: Path(".").parent Out[7]: PosixPath('.') In [8]: Path(".").parent.parent Out[8]: PosixPath('.') In [9]: Path(".").resolve().parent.parent Out[9]: PosixPath('/home/mmoser')

akx · 2026-11-09T09:55:10Z

            name = long.strip("=")
-            default = getattr(cmdinst, name.replace("-", "_"))
+            normalized_name = name.replace("-", "_")
+            default = toml_config.get(normalized_name) or getattr(cmdinst, normalized_name)


I don't think this update happened?

If present, use a "pyproject.toml" file for default configuration of `pybabel` commands. Co-authored-by: Aarni Koskela <akx@iki.fi>

The environment variable `BABEL_PYPROJECT_TOML` can be used to set an alternative search path for a "pyproject.toml" file for configuration parsing by setting it to a path. If set to "skip" or "none", the config parsing from pyproject.toml will be disabled altogether. Co-authored-by: Aarni Koskela <akx@iki.fi>

If the user explicitly specified a path for searching pyproject.toml, we assume that they know what they're doing, and we crash loudly.

max-moser force-pushed the mm/pyproject-config branch from 65a5cdb to ceb1f4b Compare July 7, 2026 14:34

akx self-assigned this Jul 7, 2026

akx added the feature label Jul 7, 2026

max-moser force-pushed the mm/pyproject-config branch from ceb1f4b to 511f10d Compare July 11, 2026 08:47

akx added this to the Babel 2.19 milestone Aug 14, 2026

akx force-pushed the mm/pyproject-config branch from 511f10d to da57261 Compare October 30, 2026 09:11

akx requested changes Oct 30, 2026

View reviewed changes

max-moser force-pushed the mm/pyproject-config branch 2 times, most recently from a39395c to af58d33 Compare October 30, 2026 11:07

max-moser commented Oct 30, 2026

View reviewed changes

Comment thread babel/messages/frontend.py Resolved

akx requested changes Nov 4, 2026

View reviewed changes

max-moser force-pushed the mm/pyproject-config branch 7 times, most recently from 2ed7648 to f3ffa42 Compare November 5, 2026 13:28

akx requested changes Nov 5, 2026

View reviewed changes

Comment thread tests/messages/frontend/test_cli.py Resolved

Comment thread tests/messages/frontend/test_cli.py Resolved

Comment thread babel/messages/frontend.py Resolved

max-moser force-pushed the mm/pyproject-config branch from 6d4fc79 to 326d912 Compare November 5, 2026 13:49

max-moser commented Nov 5, 2026

View reviewed changes

Comment thread babel/messages/frontend.py Resolved

max-moser force-pushed the mm/pyproject-config branch from 326d912 to 44946e2 Compare November 5, 2026 13:57

max-moser force-pushed the mm/pyproject-config branch from b2df682 to 247344d Compare November 5, 2026 15:24

max-moser requested a review from akx November 5, 2026 15:25

akx requested changes Nov 9, 2026

View reviewed changes

max-moser and others added 3 commits November 9, 2026 23:59

Implement parsing of command configuration from pyproject.toml

6f1d5c3

If present, use a "pyproject.toml" file for default configuration of `pybabel` commands. Co-authored-by: Aarni Koskela <akx@iki.fi>

Handle pyproject.toml ConfigurationErrors more gracefully by default

0476dce

If the user explicitly specified a path for searching pyproject.toml, we assume that they know what they're doing, and we crash loudly.

max-moser force-pushed the mm/pyproject-config branch from 247344d to 0476dce Compare November 9, 2026 22:59

		except ConfigurationError:
		self.log.error("Unable to parse configuration from pyproject.toml!")

Conversation

max-moser commented Jul 7, 2026

Uh oh!

akx left a comment

Choose a reason for hiding this comment

Uh oh!

max-moser commented Oct 30, 2026

Uh oh!

max-moser left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

akx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

akx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

max-moser commented Nov 5, 2026

Uh oh!

akx left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

max-moser Nov 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

max-moser Nov 9, 2026 •

edited

Loading