feat: add --config-json (#916)

Co-authored-by: Bernát Gábor <bgabor8@bloomberg.net>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

README.md

@@ -36,6 +36,7 @@ available via the command line as `pyproject-build` once installed.
 - `--sdist` (`-s`): Produce just an SDist
 - `--wheel` (`-w`): Produce just a wheel
 - `-C<option>=<value>`: A Config-setting, the PEP 517 way of passing options to a backend. Can be passed multiple times. Matching options will make a list. Note that setuptools has very limited support.
+- `--config-json=<value>`: An alternative way to pass in complex config settings as JSON strings. Can't be used with `-C`.
 - `--installer`: Pick an installer for the isolated build (`pip` or `uv`).
 - `--no-isolation` (`-n`): Disable build isolation.
 - `--skip-dependency-check` (`-x`): Disable dependency checking when not isolated; this should be done if some requirements or version ranges are not required for non-isolated builds.
@@ -75,14 +76,7 @@ $ uvx --from build pyproject-build --installer uv
 
 #### cibuildwheel
 
-If you are using [cibuildwheel][], build is integrated and can be use with either (in your `pyproject.toml`):
-
-```toml
-[tool.cibuildwheel]
-build-frontend = "build"
-```
-
-or
+If you are using [cibuildwheel][], build is integrated and the default builder in 3.0+. If you want to use `uv` as the installer, you can use:
 
 ```toml
 [tool.cibuildwheel]

src/build/__main__.py

@@ -5,6 +5,7 @@
 import argparse
 import contextlib
 import contextvars
+import json
 import os
 import platform
 import shutil
@@ -385,7 +386,8 @@ def main_parser() -> argparse.ArgumentParser:
         choices=_env.INSTALLERS,
         help='Python package installer to use (defaults to pip)',
     )
-    parser.add_argument(
+    config_group = parser.add_mutually_exclusive_group()
+    config_group.add_argument(
         '--config-setting',
         '-C',
         dest='config_settings',
@@ -395,6 +397,15 @@ def main_parser() -> argparse.ArgumentParser:
         'by a space character; use ``--config-setting=--my-setting -C--my-other-setting``',
         metavar='KEY[=VALUE]',
     )
+    config_group.add_argument(
+        '--config-json',
+        dest='config_json',
+        help='settings to pass to the backend as a JSON object. '
+        'This is an alternative to --config-setting that allows complex nested structures. '
+        'Cannot be used together with --config-setting',
+        metavar='JSON_STRING',
+    )
+
     return parser
 
 
@@ -414,7 +425,17 @@ def main(cli_args: Sequence[str], prog: str | None = None) -> None:
 
     config_settings = {}
 
-    if args.config_settings:
+    # Handle --config-json
+    if args.config_json:
+        try:
+            config_settings = json.loads(args.config_json)
+            if not isinstance(config_settings, dict):
+                _error('--config-json must contain a JSON object (dict), not a list or primitive value')
+        except json.JSONDecodeError as e:
+            _error(f'Invalid JSON in --config-json: {e}')
+
+    # Handle --config-setting (original logic)
+    elif args.config_settings:
         for arg in args.config_settings:
             setting, _, value = arg.partition('=')
             if setting not in config_settings:

tests/test_main.py

@@ -93,6 +93,21 @@
             [cwd, out, ['wheel'], {'--flag1': 'value', '--flag2': ['other_value', 'extra_value']}, True, False, None],
             'build_package_via_sdist',
         ),
+        (
+            ['--config-json={"one": 1, "two": [2, 3], "three": {"in": "out"}}'],
+            [cwd, out, ['wheel'], {'one': 1, 'two': [2, 3], 'three': {'in': 'out'}}, True, False, None],
+            'build_package_via_sdist',
+        ),
+        (
+            ['--config-json', '{"outer": {"inner": {"deeper": 2}}}'],
+            [cwd, out, ['wheel'], {'outer': {'inner': {'deeper': 2}}}, True, False, None],
+            'build_package_via_sdist',
+        ),
+        (
+            ['--config-json', '{}'],
+            [cwd, out, ['wheel'], {}, True, False, None],
+            'build_package_via_sdist',
+        ),
     ],
 )
 def test_parse_args(mocker, cli_args, build_args, hook):
@@ -177,6 +192,22 @@ def test_build_no_isolation_with_check_deps(mocker, package_test_flit, missing_d
     error.assert_called_with('Missing dependencies:' + output)
 
 
+@pytest.mark.parametrize(
+    ['cli_args', 'err_msg'],
+    [
+        (['-Cone=1', '--config-json={"two": 2}'], 'not allowed with argument'),
+        (['--config-json={"two": 2'], 'Invalid JSON in --config-json'),
+        (['--config-json=[1]'], '--config-json must contain a JSON object'),
+    ],
+)
+def test_config_json_errors(cli_args, err_msg, capsys):
+    with pytest.raises(SystemExit):
+        build.__main__.main(cli_args)
+
+    outerr = capsys.readouterr()
+    assert err_msg in outerr.out or err_msg in outerr.err
+
+
 @pytest.mark.isolated
 def test_build_raises_build_exception(mocker, package_test_flit):
     mocker.patch('build.ProjectBuilder.get_requires_for_build', side_effect=build.BuildException)