Build backend: Add reference docs and schema

[konstin]

Add reference documentation and schema integration for the uv build backend. The reference documentation comes with a preview note upfront.

[konstin]

I didn't find a good resource for proper ECMA script regex validation.

[zanieb]

cc @Gankra perhaps you could review this part

[Gankra]

This syntax seems to do the validation you want. You can test this out in e.g. vscode with the "even better toml" extension with the following uv.tomls.

This one errors:

"$schema" = "https://raw.githubusercontent.com/astral-sh/uv/f6e2bbdec7b53a6ce380e9ec27566e88a9144eda/uv.schema.json"

[build-backend]
module-name = "0abc"

This one passes:

"$schema" = "https://raw.githubusercontent.com/astral-sh/uv/f6e2bbdec7b53a6ce380e9ec27566e88a9144eda/uv.schema.json"

[build-backend]
module-name = "abc123"

(For local testing you can use "$schema" = "file://./uv.schema.json")

[konstin]

We had bug reports caused by this exact problem, but unfortunately it's a somewhat popular feature (scikit-learn -> sklearn, Pillow -> PIL, etc.). It also allows users to pick their preferred package name even if it is already taken on PyPI by only renaming the installation name to something free while docs and import <...> can have any name.

[konstin]

There isn't good documentation for this, the data feature is somewhat implementation defined.

[konstin]

I wouldn't know why you would use them for a pure Python project, but they exist in the spec so they exist on the build backend config:

• scripts: This feature is used to ship compiled binaries (including ruff and uv), but platform specific binaries don't match with universal wheels
• headers: Afaik only used for extension modules
• data: Writes directly into the venv root, it's better to isolate data files into the module. For communicating with other packages such as for plugin interfaces, entrypoints should be used.
• purelib and platlib: No production usage known

[Gankra]

This syntax seems to do the validation you want. You can test this out in e.g. vscode with the "even better toml" extension with the following uv.tomls.

This one errors:

"$schema" = "https://raw.githubusercontent.com/astral-sh/uv/f6e2bbdec7b53a6ce380e9ec27566e88a9144eda/uv.schema.json"

[build-backend]
module-name = "0abc"

This one passes:

"$schema" = "https://raw.githubusercontent.com/astral-sh/uv/f6e2bbdec7b53a6ce380e9ec27566e88a9144eda/uv.schema.json"

[build-backend]
module-name = "abc123"

(For local testing you can use "$schema" = "file://./uv.schema.json")

[Gankra]

Suggested change

	data = { "headers": "include/headers", "scipts": "bin" }
	data = { "headers": "include/headers", "scripts": "bin" }

[Gankra]

NB this is a future-proofing hazard for schema users (if the schema is ever out of date it will freak out about the field being missing -- I think that's fine here, especially if we make the schema in schemastore hotlinked to our github repo).

[konstin]

I'm making a bet here that wheels won't get another data field (the list has been the same since 2012) and it's more likely that users mistype one of the data names (that's why it's the only type with deny_unknown_fields in the build backend).

[cthoyt]

thank you @konstin!!