scikit_build_core.settings package¶

Submodules¶

scikit_build_core.settings.auto_cmake_version module¶

scikit_build_core.settings.auto_cmake_version.find_min_cmake_version(cmake_content)[source]¶

Locate the minimum required version. Return None if not found.

Return type:: str | None

scikit_build_core.settings.auto_requires module¶

scikit_build_core.settings.auto_requires.get_min_requires(package, reqlist)[source]¶

Read the build requirements from a pyproject.toml file and return the minimum version required for the given package. Returns None if no minimum version is discovered.

Return type:: Version | None

scikit_build_core.settings.documentation module¶

scikit_build_core.settings.documentation.pull_docs(dc)[source]¶

Pulls documentation from a dataclass.

Return type:: dict[str, str]

scikit_build_core.settings.json_schema module¶

exception scikit_build_core.settings.json_schema.FailedConversionError[source]¶: Bases: TypeError

scikit_build_core.settings.json_schema.convert_type(t, *, normalize_keys)[source]¶

Return type:: dict[str, Any]

scikit_build_core.settings.json_schema.to_json_schema(dclass, *, normalize_keys)[source]¶

Return type:: dict[str, Any]

scikit_build_core.settings.skbuild_docs_readme module¶

scikit_build_core.settings.skbuild_docs_readme.mk_skbuild_docs()[source]¶

Makes documentation for the skbuild model.

Return type:: str

scikit_build_core.settings.skbuild_docs_sphinx module¶

Make documentation for the skbuild model in sphinx format.

scikit_build_core.settings.skbuild_docs_sphinx.mk_skbuild_docs()[source]¶

Return type:: str

scikit_build_core.settings.skbuild_model module¶

class scikit_build_core.settings.skbuild_model.BackportSettings(find_python=<Version('3.26.1')>)[source]¶

Bases: object

find_python: Version = <Version('3.26.1')>¶

If CMake is less than this value, backport a copy of FindPython.

Set to 0 or an empty string to disable this.

class scikit_build_core.settings.skbuild_model.BuildSettings(tool_args=<factory>, targets=<factory>, verbose=False, requires=<factory>)[source]¶

Bases: object

requires: List[str]¶

Additional build-system.requires.

Intended to be used in combination with overrides.

targets: List[str]¶

The build targets to use when building the project.

If not specified or an empty list, the default target is used.

tool_args: List[str]¶: Extra args to pass directly to the builder in the build step.

verbose: bool = False¶

Verbose printout when building.

Equivalent to CMAKE_VERBOSE_MAKEFILE.

class scikit_build_core.settings.skbuild_model.CMakeSettings(minimum_version=None, version=None, args=<factory>, define=<factory>, verbose=None, build_type='Release', source_dir=PosixPath('.'), targets=None, toolchain_file=None, python_hints=True)[source]¶

Bases: object

args: List[str]¶

A list of args to pass to CMake when configuring the project.

Setting this in config or envvar will override toml.

See also

cmake.define

build_type: str = 'Release'¶

The build type to use when building the project.

Pre-defined CMake options are: Debug, Release, RelWithDebInfo, MinSizeRel

Custom values can also be used.

define: Annotated[Dict[str, CMakeSettingsDefine], 'EnvVar']¶: A table of defines to pass to CMake when configuring the project. Additive.

minimum_version: Version | None = None¶: DEPRECATED in 0.8; use version instead.

python_hints: bool = True¶: Do not pass the current environment’s python hints such as Python_EXECUTABLE. Primarily used for cross-compilation where the CMAKE_TOOLCHAIN_FILE should handle it instead.

source_dir: Path = PosixPath('.')¶

The source directory to use when building the project.

Currently only affects the native builder (not the setuptools plugin).

targets: List[str] | None = None¶: DEPRECATED in 0.10; use build.targets instead.

toolchain_file: Path | None = None¶

The CMAKE_TOOLCHAIN_FILE / –toolchain used for cross-compilation.

This is only allowed in overrides or config-settings.

verbose: bool | None = None¶: DEPRECATED in 0.10, use build.verbose instead.

version: SpecifierSet | None = None¶

The versions of CMake to allow as a python-compatible specifier.

If CMake is not present on the system or does not pass this specifier, it will be downloaded via PyPI if possible with the equivalent specifier used.

An empty string will disable this check.

Special cases:

On scikit-build-core 0.10+ CMakeLists.txt is the default value otherwise it’s >=3.15.
If CMakeLists.txt is passed, the cmake_minimum_required is read from the CMakeLists.txt file, using that as the minimum specifier. If the file fails to read, >=3.15 is used instead.

See also

ninja.version

class scikit_build_core.settings.skbuild_model.CMakeSettingsDefine(raw: str | bool | List[str])[source]¶

Bases: str

A str subtype for automatically normalizing bool and list values to the CMake representation in the cmake.define settings key.

json_schema = str | bool | typing.List[str]¶

class scikit_build_core.settings.skbuild_model.EditableSettings(mode='redirect', verbose=True, rebuild=False)[source]¶

Bases: object

mode: Literal['redirect', 'inplace'] = 'redirect'¶: Select the editable mode to use. Can be “redirect” (default) or “inplace”.

rebuild: bool = False¶

Rebuild the project when the package is imported.

build-dir must be set.

verbose: bool = True¶: Turn on verbose output for the editable mode rebuilds.

class scikit_build_core.settings.skbuild_model.GenerateSettings(path, template='', template_path=None, location='install')[source]¶

Bases: object

location: Literal['install', 'build', 'source'] = 'install'¶

The place to put the generated file.

The build directory is useful for CMake files, and the install directory is useful for Python files, usually. You can also write directly to the source directory, will overwrite existing files & remember to gitignore the file.

path: Path¶: The path (relative to platlib) for the file to generate.

template: str = ''¶

The template string to use for the file.

Template style placeholders are available for all the metadata.

Either this or generate[].template-path must be set.

See also

generate[].template-path

template_path: Path | None = None¶

The path to the template file. If empty, a template must be set.

Either this or generate[].template must be set.

See also

generate[].template

class scikit_build_core.settings.skbuild_model.InstallSettings(components=<factory>, strip=None)[source]¶

Bases: object

components: List[str]¶

The components to install.

If not specified or an empty list, all default components are installed.

strip: bool | None = None¶

Whether to strip the binaries.

Equivalent to --strip in cmake install.

True for release builds (Release or MinSizeRel) on scikit-build-core 0.5+.

Note

0.5-0.10.5 also incorrectly set this for debug builds.

class scikit_build_core.settings.skbuild_model.LoggingSettings(level='WARNING')[source]¶

Bases: object

level: Literal['NOTSET', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = 'WARNING'¶: The logging level to display.

class scikit_build_core.settings.skbuild_model.MessagesSettings(after_failure='', after_success='')[source]¶

Bases: object

Settings for messages.

after_failure: str = ''¶: A message to print after a build failure.

after_success: str = ''¶: A message to print after a successful build.

class scikit_build_core.settings.skbuild_model.NinjaSettings(minimum_version=None, version=<SpecifierSet('>=1.5')>, make_fallback=True)[source]¶

Bases: object

make_fallback: bool = True¶

Use Make as a fallback if a suitable Ninja executable is not found.

If Make is also not available on the system, a ninja dependency is added to the build-system.requires according to ninja.version.

See also

ninja.version

minimum_version: Version | None = None¶: DEPRECATED in 0.8; use version instead.

version: SpecifierSet = <SpecifierSet('>=1.5')>¶

The versions of Ninja to allow.

If Ninja is not present on the system or does not pass this specifier, it will be downloaded via PyPI if possible with the equivalent specifier used.

An empty string will disable this check.

See also

class scikit_build_core.settings.skbuild_model.SDistSettings(include=<factory>, exclude=<factory>, inclusion_mode=None, reproducible=True, cmake=False)[source]¶

Bases: object

cmake: bool = False¶: If set to True, CMake will be run before building the SDist.

exclude: List[str]¶: Files to exclude from the SDist even if they are included by default. Supports gitignore syntax.

See also

sdist.include

include: List[str]¶

Files to include in the SDist even if they are skipped by default. Supports gitignore syntax.

Always takes precedence over sdist.exclude

See also

sdist.exclude

inclusion_mode: Literal['classic', 'default', 'manual'] | None = None¶

Method to use to compute the files to include and exclude.

The methods are:

“default”: Process the git ignore files. Shortcuts on ignored directories.
“classic”: The behavior before 0.12, like “default” but does not shortcut directories.
“manual”: No extra logic, based on include/exclude only.

If you don’t set this, it will be “default” unless you set the minimum version below 0.12, in which case it will be “classic”.

reproducible: bool = True¶

Try to build a reproducible distribution.

Unix and Python 3.9+ recommended.

SOURCE_DATE_EPOCH will be used for timestamps, or a fixed value if not set.

class scikit_build_core.settings.skbuild_model.ScikitBuildSettings(cmake=<factory>, ninja=<factory>, logging=<factory>, sdist=<factory>, wheel=<factory>, backport=<factory>, editable=<factory>, build=<factory>, install=<factory>, generate=<factory>, messages=<factory>, search=<factory>, metadata=<factory>, strict_config=True, experimental=False, minimum_version=None, build_dir='', fail=None)[source]¶

Bases: object

backport: BackportSettings¶

build: BuildSettings¶

build_dir: str = ''¶

The CMake build directory. Defaults to a unique temporary directory.

This can be set to reuse the build directory from previous runs.

cmake: CMakeSettings¶

editable: EditableSettings¶

experimental: bool = False¶: Enable early previews of features not finalized yet.

fail: bool | None = None¶: Immediately fail the build. This is only allowed in overrides or config-settings.

generate: List[GenerateSettings]¶

install: InstallSettings¶

logging: LoggingSettings¶

messages: MessagesSettings¶

metadata: Dict[str, Dict[str, Any]]¶: List dynamic metadata fields and hook locations in this table.

minimum_version: Version | None = None¶: If set, this will provide a method for backward compatibility.

ninja: NinjaSettings¶

sdist: SDistSettings¶

search: SearchSettings¶

strict_config: bool = True¶

Strictly check all config options.

If False, warnings will be printed for unknown options.

If True, an error will be raised.

wheel: WheelSettings¶

class scikit_build_core.settings.skbuild_model.SearchSettings(site_packages=True)[source]¶

Bases: object

site_packages: bool = True¶: Add the python build environment site_packages folder to the CMake prefix paths.

class scikit_build_core.settings.skbuild_model.SettingsFieldMetadata[source]¶

Bases: TypedDict

deprecated: bool¶

display_default: str | None¶

override_only: bool¶: Do not allow the field to be a top-level table.

class scikit_build_core.settings.skbuild_model.WheelSettings(packages=None, py_api='', expand_macos_universal_tags=False, install_dir='', license_files=None, cmake=True, platlib=None, exclude=<factory>, build_tag='', tags=None)[source]¶

Bases: object

build_tag: str = ''¶: The build tag to use for the wheel. If empty, no build tag is used.

cmake: bool = True¶: Run CMake as part of building the wheel.

exclude: List[str]¶

A set of patterns to exclude from the wheel.

This is additive to the SDist exclude patterns. This applies to the final paths in the wheel, and can exclude files from CMake output as well. Editable installs may not respect this exclusion.

expand_macos_universal_tags: bool = False¶

Fill out extra tags that are not required.

This adds “x86_64” and “arm64” to the list of platforms when “universal2” is used, which helps older Pip’s (before 21.0.1) find the correct wheel.

install_dir: str = ''¶

The CMake install prefix relative to the platlib wheel path.

You might set this to the package name to install everything under the package namespace in a pythonic design.

The original dir is still at SKBUILD_PLATLIB_DIR (also SKBUILD_DATA_DIR, etc. are available).

Warning

EXPERIMENTAL An absolute path will be one level higher than the platlib root, giving access to “/platlib”, “/data”, “/headers”, and “/scripts”.

license_files: List[str] | None = None¶

A list of license files to include in the wheel. Supports glob patterns.

The default is ["LICEN[CS]E*", "COPYING*", "NOTICE*", "AUTHORS*"].

Warning

Must not be set if project.license-files is set.

packages: List[str] | Dict[str, str] | None = None¶

A list of packages to auto-copy into the wheel.

If this is not set, it will default to the first of src/<package>, python/<package>, or <package> if they exist. The prefix(s) will be stripped from the package name inside the wheel.

If a dict, provides a mapping of package name to source directory.

platlib: bool | None = None¶

Target the platlib or the purelib.

If not set, the default is to target the platlib if wheel.cmake is true, and the purelib otherwise.

py_api: str = ''¶

The Python version tag used in the wheel file.

The default (empty string) will use the default Python version.

You can also set this to “cp38” to enable the CPython 3.8+ Stable ABI / Limited API (only on CPython and if the version is sufficient, otherwise this has no effect). Or you can set it to “py3” or “py2.py3” to ignore Python ABI compatibility. The ABI tag is inferred from this tag.

This value is used to construct SKBUILD_SABI_COMPONENT CMake variable.

tags: List[str] | None = None¶

Wheel tags to manually force, {interpreter}-{abi}-{platform} format.

Manually specify the wheel tags to use, ignoring other inputs such as wheel.py-api. Each tag must be of the format {interpreter}-{abi}-{platform}. If not specified, these tags are automatically calculated. This is only allowed in overrides or config-settings.

scikit_build_core.settings.skbuild_overrides module¶

class scikit_build_core.settings.skbuild_overrides.OverrideRecord(key, original_value, value, passed_all, passed_any)[source]¶

Bases: object

Record of the override action.

Saves the original and final values, and the override reasons.

key: str¶: Settings key that is overridden.

original_value: Any | None¶

Original value in the pyproject table.

If the pyproject table did not have the key, this is a None.

passed_all: dict[str, str] | None¶: All if statements that passed (except the effective match_any).

passed_any: dict[str, str] | None¶: All if.any statements that passed.

value: Any¶: Final value.

scikit_build_core.settings.skbuild_overrides.process_overrides(tool_skb, *, state, retry, env=None)[source]¶

Process overrides into the main dictionary if they match. Modifies the input dictionary. Must be run from the package directory.

Return type:: tuple[set[str], dict[str, OverrideRecord]]
Returns:: A tuple of the set of matching overrides and a dict of changed keys and override record

scikit_build_core.settings.skbuild_overrides.regex_match(value, match)[source]¶

Returns a non-empty string if a value matches a regex.

Return type:: str

scikit_build_core.settings.skbuild_read_settings module¶

class scikit_build_core.settings.skbuild_read_settings.SettingsReader(pyproject, config_settings, *, state, extra_settings=None, verify_conf=True, env=None, retry=False)[source]¶

Bases: object

classmethod from_file(pyproject_path, config_settings=None, *, state='sdist', verify_conf=True, extra_settings=None, env=None, retry=False)[source]¶

Return type:: SettingsReader

print_suggestions()[source]¶

Return type:: None

suggestions(index)[source]¶

Return type:: dict[str, list[str]]

unrecognized_options()[source]¶

Return type:: Generator[str, None, None]

validate_may_exit()[source]¶

Return type:: None

scikit_build_core.settings.skbuild_schema module¶

scikit_build_core.settings.skbuild_schema.generate_skbuild_schema(tool_name='scikit-build')[source]¶

Generate the complete schema for scikit-build settings.

Return type:: dict[str, Any]

scikit_build_core.settings.skbuild_schema.get_skbuild_schema(tool_name='scikit-build')[source]¶

Get the stored complete schema for scikit-build settings.

Return type:: dict[str, Any]

scikit_build_core.settings.sources module¶

This is the configuration tooling for scikit-build-core. This is build around the Source Protocol. Sources are created with some input (like a toml file for the TOMLSource). Sources also usually have some prefix (like tool.scikit-build) as well. The SourceChain holds a collection of Sources, and is the primary way to use them.

An end user interacts with SourceChain via .convert_target, which takes a Dataclass class and returns an instance with fields populated.

Example of usage:

sources = SourceChain(TOMLSource("tool", "mypackage", settings=pyproject_dict), ...)
settings = sources.convert_target(SomeSettingsModel)

unrecognized_options = list(source.unrecognized_options(SomeSettingsModel)

Naming conventions:

model is the complete Dataclass.
target is the type to convert a single item to.
settings is the input data source (unless it already has a name, like env).
options are the names of the items in the model, formatted in the style of the current Source.
fields are the tuple of strings describing a nested field in the model.

When setting up your dataclasses, these types are handled:

str: A string type, nothing special.
bool: Supports bool in TOML, not handled in envvar/config (so only useful in a Union)
Any callable (Path, Version): Passed the string input.
Optional[T]: Treated like T. Default should be None, since no input format supports None’s.
Union[str, ...]: Supports other input types in TOML form (bool currently). Otherwise a string.
List[T]: A list of items. ; separated supported in EnvVar/config forms. T can be a dataclass (TOML only).
Dict[str, T]: A table of items. TOML supports a layer of nesting. Any is supported as an item type.
Union[list[T], Dict[str, T]] (TOML only): A list or dict of items.
Literal[...]: A list of strings, the result must be in the list.
Annotated[Dict[...], "EnvVar"]: A dict of items, where each item can be a string or a dict with “env” and “default” keys.

These are supported for JSON schema generation for the TOML, as well.

Integers/floats would be easy to add, but haven’t been needed yet.

class scikit_build_core.settings.sources.ConfSource(*prefixes, settings, verify=True)[source]¶

Bases: object

This is a source for the PEP 517 configuration settings. You should initialize it with a dict from PEP 517. a.b will be treated as nested dicts. “verify” is a boolean that determines whether unrecognized options should be checked for. Only set this to false if this might be sharing config options at the same level.

While most mechanisms (pip, uv, build) only support text, gpep517 allows an arbitrary json input, so this currently also handles bools.

all_option_names(target)[source]¶

Return type:: Iterator[str]

classmethod convert(item, target)[source]¶

Return type:: object

get_item(*fields, is_dict)[source]¶

Return type:: str | list[str] | dict[str, str] | bool

has_item(*fields, is_dict)[source]¶

Return type:: bool

unrecognized_options(options)[source]¶

Return type:: Generator[str, None, None]

class scikit_build_core.settings.sources.EnvSource(prefix, *, env=None)[source]¶

Bases: object

This is a source using environment variables.

all_option_names(target)[source]¶

Return type:: Iterator[str]

classmethod convert(item, target)[source]¶

Convert an item from the environment (always a string) into a target type.

Return type:: object

get_item(*fields, is_dict)[source]¶

Return type:: str | dict[str, str]

has_item(*fields, is_dict)[source]¶

Return type:: bool

static unrecognized_options(options)[source]¶

Return type:: Generator[str, None, None]

class scikit_build_core.settings.sources.Source(*args, **kwargs)[source]¶

Bases: Protocol

all_option_names(target)[source]¶

Given a model, produce a list of all possible names (used for producing suggestions).

Return type:: Iterator[str]

classmethod convert(item, target)[source]¶

Convert an item from the base representation of the source’s source into a target type. Raises TypeError if the conversion fails.

Return type:: object

get_item(*fields, is_dict)[source]¶

Select an item from a chain of fields. Raises KeyError if the there is no item. is_dict should be set if it can be nested.

Return type:: Any

has_item(*fields, is_dict)[source]¶

Check if the source contains a chain of fields. For example, fields = [Field(name="a"), Field(name="b")] will check if the source contains the key “a.b”. is_dict should be set if it can be nested.

Return type:: bool

unrecognized_options(options)[source]¶

Given a model, produce an iterator of all unrecognized option names. Empty iterator if this can’t be computed for the source (like for environment variables).