scikit_build_core.settings package¶
Submodules¶
scikit_build_core.settings.documentation module¶
scikit_build_core.settings.json_schema module¶
scikit_build_core.settings.skbuild_docs module¶
scikit_build_core.settings.skbuild_model module¶
- class scikit_build_core.settings.skbuild_model.BackportSettings(find_python=<Version('3.26.1')>)[source]¶
Bases:
object
- class scikit_build_core.settings.skbuild_model.CMakeSettings(minimum_version=None, version=<SpecifierSet('>=3.15')>, args=<factory>, define=<factory>, verbose=False, build_type='Release', source_dir=PosixPath('.'), targets=<factory>)[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. Valid options are: “Debug”, “Release”, “RelWithDebInfo”, “MinSizeRel”, “”, etc.
-
define:
Dict
[str
,Union
[str
,bool
]]¶ A table of defines to pass to CMake when configuring the project. Additive.
-
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
]¶ The build targets to use when building the project. Empty builds the default target.
-
version:
SpecifierSet
= <SpecifierSet('>=3.15')>¶ The versions of CMake to allow. If CMake is not present on the system or does not pass this specifier, it will be downloaded via PyPI if possible. An empty string will disable this check.
-
args:
- 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”.
-
mode:
- 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.
-
location:
- class scikit_build_core.settings.skbuild_model.InstallSettings(components=<factory>, strip=None)[source]¶
Bases:
object
- class scikit_build_core.settings.skbuild_model.LoggingSettings(level='WARNING')[source]¶
Bases:
object
- 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¶ If Ninja is not present on the system or is older than required, it will be downloaded via PyPI if this is false.
-
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. An empty string will disable this check.
-
make_fallback:
- class scikit_build_core.settings.skbuild_model.SDistSettings(include=<factory>, exclude=<factory>, reproducible=True, cmake=False)[source]¶
Bases:
object
-
exclude:
List
[str
]¶ Files to exclude from the SDist even if they are included by default. Supports gitignore syntax.
-
exclude:
- class scikit_build_core.settings.skbuild_model.ScikitBuildSettings(cmake=<factory>, ninja=<factory>, logging=<factory>, sdist=<factory>, wheel=<factory>, backport=<factory>, editable=<factory>, install=<factory>, generate=<factory>, metadata=<factory>, strict_config=True, experimental=False, minimum_version=None, build_dir='')[source]¶
Bases:
object
-
backport:
BackportSettings
¶
-
cmake:
CMakeSettings
¶
-
editable:
EditableSettings
¶
-
generate:
List
[GenerateSettings
]¶
-
install:
InstallSettings
¶
-
logging:
LoggingSettings
¶
-
minimum_version:
Optional
[Version
] = None¶ If set, this will provide a method for backward compatibility.
-
ninja:
NinjaSettings
¶
-
sdist:
SDistSettings
¶
-
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
¶
-
backport:
- class scikit_build_core.settings.skbuild_model.WheelSettings(packages=None, py_api='', expand_macos_universal_tags=False, install_dir='', license_files=<factory>, cmake=True, platlib=None, exclude=<factory>, build_tag='')[source]¶
Bases:
object
-
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 install directory for the wheel. This is relative to the platlib root. You might set this to the package name. The original dir is still at SKBUILD_PLATLIB_DIR (also SKBUILD_DATA_DIR, etc. are available). EXPERIMENTAL: An absolute path will be one level higher than the platlib root, giving access to “/platlib”, “/data”, “/headers”, and “/scripts”.
-
packages:
Optional
[List
[str
]] = 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.
-
platlib:
Optional
[bool
] = 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 tags. The default (empty string) will use the default Python version. You can also set this to “cp37” to enable the CPython 3.7+ 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.
-
exclude:
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)[source]¶
Bases:
object
scikit_build_core.settings.skbuild_schema module¶
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, likeenv
).options
are the names of the items in themodel
, formatted in the style of the current Source.fields
are the tuple of strings describing a nested field in themodel
.
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.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.
- class scikit_build_core.settings.sources.EnvSource(prefix, *, env=None)[source]¶
Bases:
object
This is a source using environment variables.
- 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).
- classmethod convert(item, target)[source]¶
Convert an
item
from the base representation of the source’s source into atarget
type. Raises TypeError if the conversion fails.- Return type:
- 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:
- class scikit_build_core.settings.sources.SourceChain(*sources, prefixes=())[source]¶
Bases:
object