Options for Pants's Python support.
Config section: <span style="color: purple"><code>[python-setup]</code></span>
## Basic options
<div style="color: purple"> <h3><code>macos_big_sur_compatibility</code></h3> <code>--[no-]python-setup-macos-big-sur-compatibility</code><br> <code>PANTS_PYTHON_SETUP_MACOS_BIG_SUR_COMPATIBILITY</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>
<br>
If set, and if running on MacOS Big Sur, use macosx_10_16 as the platform when building wheels. Otherwise, the default of macosx_11_0 will be used. This may be required for pip to be able to install the resulting distribution on Big Sur.
</div> <br>
## Advanced options
<div style="color: purple"> <h3><code>interpreter_constraints</code></h3> <code>--python-setup-interpreter-constraints="[<requirement>, <requirement>, ...]"</code><br> <code>PANTS_PYTHON_SETUP_INTERPRETER_CONSTRAINTS</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <pre>[ "CPython>=3.6,<4" ]</pre></span>
<br>
The Python interpreters your codebase is compatible with.
Specify with requirement syntax, e.g. 'CPython>=2.7,<3' (A CPython interpreter with version >=2.7 AND version <3) or 'PyPy' (A pypy interpreter of any version). Multiple constraint strings will be ORed together.
These constraints are used as the default value for the `interpreter_constraints` field of Python targets.
</div> <br>
<div style="color: purple"> <h3><code>interpreter_versions_universe</code></h3> <code>--python-setup-interpreter-versions-universe="['<str>', '<str>', ...]"</code><br> <code>PANTS_PYTHON_SETUP_INTERPRETER_VERSIONS_UNIVERSE</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <pre>[ "2.7", "3.5", "3.6", "3.7", "3.8", "3.9", "3.10" ]</pre></span>
<br>
All known Python major/minor interpreter versions that may be used by either your code or tools used by your code.
This is used by Pants to robustly handle interpreter constraints, such as knowing when generating lockfiles which Python versions to check if your code is using.
This does not control which interpreter your code will use. Instead, to set your interpreter constraints, update `[python].interpreter_constraints`, the `interpreter_constraints` field, and relevant tool options like `[isort].interpreter_constraints` to tell Pants which interpreters your code actually uses. See [Interpreter compatibility](🔗).
All elements must be the minor and major Python version, e.g. '2.7' or '3.10'. Do not include the patch version.
</div> <br>
<div style="color: purple"> <h3><code>requirement_constraints</code></h3> <code>--python-setup-requirement-constraints=<file_option></code><br> <code>PANTS_PYTHON_SETUP_REQUIREMENT_CONSTRAINTS</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>None</code></span>
<br>
When resolving third-party requirements for your own code (vs. tools you run), use this constraints file to determine which versions to use.
This only applies when resolving user requirements, rather than tools you run like Black and Pytest. To constrain tools, set `[tool].lockfile`, e.g. `[black].lockfile`.
See https://pip.pypa.io/en/stable/user_guide/#constraints-files for more information on the format of constraint files and how constraints are applied in Pex and pip.
Mutually exclusive with `[python].experimental_lockfile`.
</div> <br>
<div style="color: purple"> <h3><code>resolve_all_constraints</code></h3> <code>--[no-]python-setup-resolve-all-constraints</code><br> <code>PANTS_PYTHON_SETUP_RESOLVE_ALL_CONSTRAINTS</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>True</code></span>
<br>
If enabled, when resolving requirements, Pants will first resolve your entire constraints file as a single global resolve. Then, if the code uses a subset of your constraints file, Pants will extract the relevant requirements from that global resolve so that only what's actually needed gets used. If disabled, Pants will not use a global resolve and will resolve each subset of your requirements independently.
Usually this option should be enabled because it can result in far fewer resolves.
Requires [python].requirement_constraints to be set.
</div> <br>
<div style="color: purple"> <h3><code>experimental_lockfile</code></h3> <code>--python-setup-experimental-lockfile=<file></code><br> <code>PANTS_PYTHON_SETUP_EXPERIMENTAL_LOCKFILE</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>None</code></span>
<br>
The lockfile to use when resolving requirements for your own code (vs. tools you run).
This is highly experimental and will change, including adding support for multiple lockfiles. This option's behavior may change without the normal deprecation cycle.
To generate a lockfile, activate the backend `pants.backend.experimental.python`and run `./pants generate-user-lockfile ::`.
Mutually exclusive with `[python].requirement_constraints`.
</div> <br>
<div style="color: purple"> <h3><code>experimental_resolves_to_lockfiles</code></h3> <code>--python-setup-experimental-resolves-to-lockfiles="{'key1': val1, 'key2': val2, ...}"</code><br> <code>PANTS_PYTHON_SETUP_EXPERIMENTAL_RESOLVES_TO_LOCKFILES</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>{}</code></span>
<br>
A mapping of logical names to lockfile paths used in your project, e.g. `{ default = '3rdparty/default_lockfile.txt', py2 = '3rdparty/py2.txt' }`.
To generate a lockfile, run `./pants generate-lockfiles --resolve=<name>` or `./pants generate-lockfiles` to generate for all resolves (including tool lockfiles).
This is highly experimental and will likely change.
</div> <br>
<div style="color: purple"> <h3><code>invalid_lockfile_behavior</code></h3> <code>--python-setup-invalid-lockfile-behavior=<InvalidLockfileBehavior></code><br> <code>PANTS_PYTHON_SETUP_INVALID_LOCKFILE_BEHAVIOR</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">one of: <code>error, ignore, warn</code></span><br> <span style="color: green">default: <code>error</code></span>
<br>
The behavior when a lockfile has requirements or interpreter constraints that are not compatible with what the current build is using.
We recommend keeping the default of `error` for CI builds.
</div> <br>
<div style="color: purple"> <h3><code>interpreter_search_paths</code></h3> <code>--python-setup-interpreter-search-paths="[<binary-paths>, <binary-paths>, ...]"</code><br> <code>PANTS_PYTHON_SETUP_INTERPRETER_SEARCH_PATHS</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <pre>[ "<PYENV>", "<PATH>" ]</pre></span>
<br>
A list of paths to search for Python interpreters that match your project's interpreter constraints.
You can specify absolute paths to interpreter binaries and/or to directories containing interpreter binaries. The order of entries does not matter.
The following special strings are supported:
`
<PATH>`, the contents of the PATH env var`
<ASDF>`, all Python versions currently configured by ASDF `(asdf shell, ${HOME}/.tool-versions)`, with a fallback to all installed versions`
<ASDF_LOCAL>`, the ASDF interpreter with the version in BUILD_ROOT/.tool-versions`
<PYENV>`, all Python versions under $(pyenv root)/versions`
<PYENV_LOCAL>`, the Pyenv interpreter with the version in BUILD_ROOT/.python-version`
<PEXRC>`, paths in the PEX_PYTHON_PATH variable in /etc/pexrc or ~/.pexrc</div> <br>
<div style="color: purple"> <h3><code>resolver_manylinux</code></h3> <code>--python-setup-resolver-manylinux=<str></code><br> <code>PANTS_PYTHON_SETUP_RESOLVER_MANYLINUX</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>manylinux2014</code></span>
<br>
Whether to allow resolution of manylinux wheels when resolving requirements for foreign linux platforms. The value should be a manylinux platform upper bound, e.g.: 'manylinux2010', or else the string 'no' to disallow.
</div> <br>
<div style="color: purple"> <h3><code>resolver_jobs</code></h3> <code>--python-setup-resolver-jobs=<int></code><br> <code>PANTS_PYTHON_SETUP_RESOLVER_JOBS</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>#cores/2</code></span>
<br>
The maximum number of concurrent jobs to build wheels with.
Because Pants can run multiple subprocesses in parallel, the maximum total parallelism will be `--process-execution-{local,remote}-parallelism x --python-resolver-jobs`.
Setting this option higher may result in better parallelism, but, if set too high, may result in starvation and Out of Memory errors.
</div> <br>
<div style="color: purple"> <h3><code>tailor_ignore_solitary_init_files</code></h3> <code>--[no-]python-setup-tailor-ignore-solitary-init-files</code><br> <code>PANTS_PYTHON_SETUP_TAILOR_IGNORE_SOLITARY_INIT_FILES</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>True</code></span>
<br>
Don't tailor `python_sources` targets for solitary `__init__.py` files, as those usually exist as import scaffolding rather than true library code.
Set to False if you commonly have packages containing real code in `__init__.py` and there are no other .py files in the package.
</div> <br>
<div style="color: purple"> <h3><code>tailor_requirements_targets</code></h3> <code>--[no-]python-setup-tailor-requirements-targets</code><br> <code>PANTS_PYTHON_SETUP_TAILOR_REQUIREMENTS_TARGETS</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>True</code></span>
<br>
Tailor python_requirements() targets for requirements files.
</div> <br>
<div style="color: purple"> <h3><code>tailor_pex_binary_targets</code></h3> <code>--[no-]python-setup-tailor-pex-binary-targets</code><br> <code>PANTS_PYTHON_SETUP_TAILOR_PEX_BINARY_TARGETS</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>True</code></span>
<br>
Tailor pex_binary() targets for Python entry point files.
</div> <br>
## Deprecated options
None