diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index d2eb5d62ab4..a0a6ab363d9 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -687,8 +687,10 @@ peps/pep-0808.rst @FFY00 peps/pep-0809.rst @zooba peps/pep-0810.rst @pablogsal @DinoV @Yhg1s peps/pep-0811.rst @sethmlarson @gpshead +# ... peps/pep-0814.rst @vstinner @corona10 peps/pep-0815.rst @emmatyping +peps/pep-0816.rst @brettcannon # ... peps/pep-2026.rst @hugovk # ... diff --git a/peps/pep-0816.rst b/peps/pep-0816.rst new file mode 100644 index 00000000000..333cc0f6f95 --- /dev/null +++ b/peps/pep-0816.rst @@ -0,0 +1,172 @@ +PEP: 816 +Title: WASI Support +Author: Brett Cannon +Discussions-To: Pending +Status: Draft +Type: Informational +Created: 05-Nov-2025 +Post-History: Pending + + +Abstract +======== + +This PEP outlines the expected support for WASI_ by CPython. It contains enough +details to know what WASI and WASI SDK version is expected to be supported for +any release of CPython while official WASI support is specified in :pep:`11`. + + +Motivation +========== + +CPython has supported WASI according to :pep:`11` since Python 3.11. As part of +this support, CPython needs to target two different things: the WASI_ version +and the `WASI SDK`_ version (both of whose development is driven by the +`Bytecode Alliance`_). The former is the specification of WASI itself while the +latter is a version of clang_ with a specific version of wasi-libc_ as the +sysroot that allows for compiling CPython to WASI. There is roughly an annual +release cadence for new WASI versions while there's no set release cadence for +WASI SDK. + +Agreeing on which WASI and WASI SDK versions to support allows for clear +targeting of the CPython code base towards those versions. This also lets the +community set appropriate expectations as to what will (not) be considered a +bug if it only manifests itself under a certain WASI or WASI SDK version. It +also provides the community an overall target for WASI and WASI SDK for any +specific Python version when building other software like libraries. This is +important as WASI SDK is NOT forwards- or backwards-compatible due to the ABI +of wasi-libc not making any compatibility guarantees, making broad coordination +important so code works together. + +This coordination and recording around version targets can be important in +situations where the selected version is non-obvious. For example, WASI SDK 26 +and 27 have a `bug `__ +which cause CPython to hang in certain situations (including exiting the REPL). +Because the bug is in thread support code it wouldn't necessarily be obvious to +others in the community that CPython will not target those versions and thus +3rd-party code should also avoid those versions. + + +Rationale +========= + +While technically separate, CPython cannot support a version of WASI until WASI +SDK supports it. WASI versions are considered backwards-compatible with each +other, but WASI SDK is NOT compatible forwards or backwards thanks to wasi-libc +not having ABI compatibility guarantees. As such, it's important to set support +expectations for a specific WASI SDK version in CPython. Historically, the +support difference between WASI SDK versions for CPython have involved settings +in the ``config.site`` file that is maintained for WASI. Support issues have +come up due to bugs in WASI SDK itself. Finally, new features being supported +by WASI SDK can also cause code that wasn't previously used in a WASI build to +suddenly be run which can require code updates to pass tests. + +As for WASI version support, that typically translates into what stdlib modules +are (potentially) usable with a WASI build. For example, WASI 0.2 added socket +support and WASI 0.3.1 is scheduled to have some form of threading support. +Knowing what WASI version is supported sets expectations for what stdlib +modules should be supported. + +Interpreter feature availability can be dependent on the WASI version. For +instance, until there is threading support there can't be free-threading +support in WASI. Once again, this helps set expectations of what should be +working based on the target WASI version. + + +Specification +============= + +The WASI and WASI SDK version supported by a CPython version in CI or its +stable Buildbot builder when b1 is released MUST be the version to be supported +for the lifetime of that Python version after this PEP is accepted. If there is +a discrepancy between CI and the Buildbot builder for some reason, the WASI +maintainers as specified by :pep:`11` will choose which sets of versions will +be designated as the versions to support. + +The WASI version and WASI SDK version supported for a Python version MUST be +recorded in :pep:`11` as an official record. + +If for some reason a supported WASI SDK version needs to change after being +recorded, a note will be made in :pep:`11` as to when and why the change was +made. Such a change is at the discretion of the maintainers of WASI support as +listed in :pep:`11` and does not require steering council approval. The +expectation, though, is that such a change SHOULD NOT occur. + +Changing the WASI version after it has been recorded MUST NOT occur UNLESS the +steering council approves it. This is due to the increased support burden for +new WASI versions and the shift in expectations of what CPython would support +when support expectations have already been set. + +Any updates to :pep:`11` to reflect the appropriate WASI version for the target +triple for the main branch MUST be made as needed, but it does NOT require +steering council approval to update. The steering council is spared needing to +approve such an update as it does not constitute a new platform and is more in +line with a new OS release which currently does not require steering council +approval. + + +Designated Support +================== + +Note that while WASI SDK in some places lists both a major and minor version, +in actuality the minor version has never been set to anything other than ``0`` +and there's an expectation that +`any minor version will be ABI compatible with the overall major version `__. +As well, the WASI community only refers to WASI SDK versions by their major +version due to there having never been a minor release. Subsequently, this PEP +only records the major version of WASI SDK until such time that there's a need +to record a minor version. + +====== ==== ======== +Python WASI WASI SDK +====== ==== ======== +3.14 0.1 24 +3.13 0.1 24 +3.12 0.1 16 +3.11 0.1 16 +====== ==== ======== + + +Notes +----- + +All versions prior to Python 3.15 predate this PEP. The version support for +those versions is based on what was supported when this PEP was written. + +WASI was a tier 3 platform according to :pep:`11` for Python 3.11 and 3.12. +WASI became a tier 2 platform starting with Python 3.13. + +WASI 0.2 support has been skipped due to lack of time, to the point that it was +deemed better to go straight to WASI 0.3 instead. This is based on a +recommendation from the `Bytecode Alliance`_. + +WASI SDK 26 and 27 have a +`bug `__ which causes +CPython to hang in certain situations, and so they have been skipped. + + +Acknowledgements +================ + +Thanks to Joel Dice and Ben Brandt of the Python +`sub-group `__ +of the +`guest languages SIG `__ +of the `Bytecode Alliance`_ for discussing the specification of this PEP. + + +Footnotes +========= + +.. _WASI: https://wasi.dev +.. _WASI SDK: https://github.com/WebAssembly/wasi-sdk +.. _wasi-libc: https://github.com/WebAssembly/wasi-libc +.. _clang: https://clang.llvm.org +.. _Bytecode Alliance: https://bytecodealliance.org + + +Copyright +========= + +This document is placed in the public domain or under the +CC0-1.0-Universal license, whichever is more permissive.