Is `config_settings` supposed to be constant between all PEP 517 hook calls?

As mentioned in _build_in_isolated_env fails to pass in config_settings to builder.get_dependencies · Issue #264 · pypa/build · GitHub, setuptools treats config_settings arguments to the various hooks differently.

PEP 517 says

The common config_settings argument is described after the individual hooks.

Does this mean config_settings should be common between all hooks as in it should stay the same, or as all hooks have it?

If it is okay for it to change, then it becomes incredibly hard for build frontends to come up with a usable user interface to interact with this parameter.
Right now, pypa/build will only pass config_settings to the build_wheel, build_sdist and prepare_metadata_for_build_wheel hooks, and not get_requires_for_build_*.

I think this argument should be at least the same between the build_* and equivalent get_requires_for_build_wheel_* hooks.

cc @jaraco

1 Like

I’d read “common” in the quoted part of the PEP as “all hooks have this parameter”.

Having said that, I agree that a backend which expects tailored config settings for each call is going to be difficult, if not impossible, to use.

In reality, I don’t think anyone has done anything much with config settings at this point - I know pip hasn’t. I’m not sure the setuptools model is particularly good here - it’s basically just a PEP 517 shim over the old command line options. The truth is no-one seems to care much about config_settings - neither from the front end or the back end perspective.

It will need a real-world use case (not just “preserve legacy behaviour”) to give enough context to properly design how front ends and back ends use the feature, and no-one has yet come up with one as far as I know.


I agree with what Paul is saying. If config settings are implementation-specific, then users will need to be implementation-aware when passing settings, something that PEP 517 aims to abstract. I could imagine the backends could solicit backend-specific config through namespaces, such as setuptools.use_distutils=local, but the real value in config settings will come if the different backends honor some corpora of shared settings, like install.prefix or compiler.optimize=3.

I can push in Setuptools to attempt to solicit implementation-specific settings in a namespace and to solicit other settings in a generalizable form, but better would be for someone to evaluate the types of config settings users might want/expect and to establish a home where these settings can be discussed and documented (packaging docs, maybe?).

1 Like

I’m not entirely sure if you agreed with the bit of what I said that I suspect @FFY00 is most interested in.

While I don’t think the spec says this, I think that backends should accept the same set of parameters for all hooks. Some hooks may ignore certain parameters, but they should not raise errors. The reason for this is that I’d expect most front ends to create a config dictionary and pass it unchanged to any hook that it called. I definitely wouldn’t expect front ends to have to design a UI that allows/requires the user to specify hook-by-hook config items.

I suspect that you read my comment as “back ends may require different config for each hook and front ends must provide hook-specific config if needed”, where what I was trying to say was “front ends may provide different config, but back ends must be prepared for the front end to provide the same config to all hooks”.

But either way, I don’t think the PEP takes a stance on the matter. The closest it comes is where it says "For example, they might support some syntax like --package-config CC=gcc" which to me suggests a single set of settings for all hooks.

To give another data point, while pip still hasn’t implemented PEP 517 config settings support (I don’t believe we pass config_settings at all), when it does, I expect it to take the form of letting the user specify key:value pairs, which pip will then put in a single config dictionary which it will pass to all backend hooks (i.e., the basic model suggested in the PEP).

1 Like

(sorry for the delay)


Would it make sense to amend the PEP so that it asks for this? Or at least encourages it?
From the pypa/build side I am likely just gonna tell users that want to do this to use the Python API instead of the CLI, but I would like to prevent backends to start implementing hooks in this way.

I think it would make sense, but it would be a change to the PEP, so it would need at least a formal proposal and discussion before we could make the change. In particular, it would be a change that makes the current setuptools in violation of the revised PEP, so there would be knock-on effects, with tools only working with newer setuptools versions.

So I think any discussion would need to cover backward compatibility and breakages - the PEP 517 interface isn’t versioned, so we can’t easily implement a gradual migration. It may even be that this change is significant enough that it’ll be the trigger that means we need to add versioning to the API.


So perhaps I should draft a PEP adding a new version to the interface? This version would:

  • Add a mechanism to identify the version
  • Mandate that config_settings must be constant between all hook calls

Then build frontends can implement version compatibility as they wish, possibly supporting multiple version.