Abstract

This PEP outlines the expected support forWASI by CPython. It contains enoughdetails to know what WASI and WASI SDK version is expected to be supported forany release of CPython while official WASI support is specified inPEP 11.

Motivation

CPython has supported WASI according toPEP 11 since Python 3.11. As part ofthis support, CPython needs to target two different things: theWASI versionand theWASI SDK version (both of whose development is driven by theBytecode Alliance). The former is the specification of WASI itself while thelatter is a version ofclang with a specific version ofwasi-libc as thesysroot that allows for compiling CPython to WASI. There is roughly an annualrelease cadence for new WASI versions while there’s no set release cadence forWASI SDK.

Agreeing on which WASI and WASI SDK versions to support allows for cleartargeting of the CPython code base towards those versions. This also lets thecommunity set appropriate expectations as to what will (not) be considered abug if it only manifests itself under a certain WASI or WASI SDK version. Italso provides the community an overall target for WASI and WASI SDK for anyspecific Python version when building other software like libraries. This isimportant as WASI SDK is NOT forwards- or backwards-compatible due to the ABIof wasi-libc not making any compatibility guarantees, making broad coordinationimportant so code works together.

This coordination and recording around version targets can be important insituations where the selected version is non-obvious. For example, WASI SDK 26and 27 have abugwhich 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 toothers in the community that CPython will not target those versions and thus3rd-party code should also avoid those versions.

Rationale

While technically separate, CPython cannot support a version of WASI until WASISDK supports it. WASI versions are considered backwards-compatible with eachother, but WASI SDK is NOT compatible forwards or backwards thanks to wasi-libcnot having ABI compatibility guarantees. As such, it’s important to set supportexpectations for a specific WASI SDK version in CPython. Historically, thesupport difference between WASI SDK versions for CPython have involved settingsin theconfig.site file that is maintained for WASI. Support issues havecome up due to bugs in WASI SDK itself. Finally, new features being supportedby WASI SDK can also cause code that wasn’t previously used in a WASI build tosuddenly be run which can require code updates to pass tests.

As for WASI version support, that typically translates into what stdlib modulesare (potentially) usable with a WASI build. For example, WASI 0.2 added socketsupport and WASI 0.3.1 is scheduled to have some form of threading support.Knowing what WASI version is supported sets expectations for what stdlibmodules should be supported.

Interpreter feature availability can be dependent on the WASI version. Forinstance, until there is threading support there can’t be free-threadingsupport in WASI. Once again, this helps set expectations of what should beworking based on the target WASI version.

Specification

The WASI and WASI SDK version supported by a CPython version in CI or itsstable Buildbot builder when b1 is released MUST be the version to be supportedfor the lifetime of that Python version after this PEP is accepted. If there isa discrepancy between CI and the Buildbot builder for some reason, the WASImaintainers as specified byPEP 11 will choose which sets of versions willbe designated as the versions to support.

The WASI version and WASI SDK version supported for a Python version MUST berecorded inPEP 11 as an official record.

If for some reason a supported WASI SDK version needs to change after beingrecorded, a note will be made inPEP 11 as to when and why the change wasmade. Such a change is at the discretion of the maintainers of WASI support aslisted inPEP 11 and does not require steering council approval. Theexpectation, though, is that such a change SHOULD NOT occur.

Changing the WASI version after it has been recorded MUST NOT occur UNLESS thesteering council approves it. This is due to the increased support burden fornew WASI versions and the shift in expectations of what CPython would supportwhen support expectations have already been set.

Any updates toPEP 11 to reflect the appropriate WASI version for the targettriple for the main branch MUST be made as needed, but it does NOT requiresteering council approval to update. The steering council is spared needing toapprove such an update as it does not constitute a new platform and is more inline with a new OS release which currently does not require steering councilapproval.

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 than0and there’s an expectation thatany minor version will be ABI compatible with the overall major version.As well, the WASI community only refers to WASI SDK versions by their majorversion due to there having never been a minor release. Subsequently, this PEPonly records the major version of WASI SDK until such time that there’s a needto record a minor version.

Acknowledgements

Thanks to Joel Dice and Ben Brandt of the Pythonsub-groupof theguest languages SIGof theBytecode Alliance for discussing the specification of this PEP.

Copyright

This document is placed in the public domain or under theCC0-1.0-Universal license, whichever is more permissive.