Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

gh-95451: Update docs for wasm32-emscripten and -wasi platforms #95452

Merged
merged 15 commits into from
Aug 2, 2022
Merged

gh-95451: Update docs for wasm32-emscripten and -wasi platforms #95452

merged 15 commits into from
Aug 2, 2022

Conversation

tiran
Copy link
Member

@tiran tiran commented Jul 29, 2022 •
edited by bedevere-bot
Loading

@bedevere-bot bedevere-bot added awaiting core review docs Documentation in the Doc dir labels Jul 29, 2022
@tiran tiran requested a review from brettcannon July 29, 2022 21:03
@tiran tiran marked this pull request as ready for review July 30, 2022 11:19
@tiran tiran requested review from ethanfurman, a team, vsajip, 1st1 and asvetlov as code owners July 30, 2022 11:19
merwok
merwok reviewed Jul 31, 2022
View reviewed changes
@tiran @merwok
Update Doc/library/intro.rst
948f519 
Co-authored-by: Éric <merwok@netwok.org>
mdboom
mdboom approved these changes Aug 1, 2022
View reviewed changes
Doc/library/intro.rst Outdated
PyScript is built on top of Pyodide, which itself is built on top of
CPython and Emscripten. Pyodide provides access to browsers' JavaScript and
DOM APIs as well as limited networking capabilities with JavaScript's
``XMLHttpRequest`` and ``Fetch`` API.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking forward to the day when that's just a "browser support module" installable in upstream CPython...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm lobbying for a high level HTTP API in Python core.

Doc/library/intro.rst Outdated
The properties and behavior of Python on WebAssembly platforms depend on the
`Emscripten`_ or `WASI`_-SDK version, WASM runtimes (browser, NodeJS, `wasmtime`_),
and Python build time flags. WebAssembly, Emscripten, and WASI are evolving.
Some features like networking may be supported in the future.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given that Emscripten and WASI runtimes are moving targets, there could at least be unofficial builds of Python build against future versions of emscripten where some of the features marked as unavailable become available. Do we want to somehow flag the difference between "explicitly disabled in Python" vs. "not known to work in current environments"? Maybe we want to add to this paragraph:

"Python features documented as unsupported may in fact work depending on your environment."

But maybe that's too confusing for most users to understand, and something we can address in the future as these things mature.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very few features are explicitly disabled. The config.site files disable a few syscalls that fail tests or make no sense. For example I disabled the effective user/group id function family. Emscripten returns 0, which some code interprets as CAP_SYS_ADMIN privileges. The config.site files in Tool/wasm directory have comments for special cases.

The target audience for the section is "curious users without previous WASM experience". I want to give them some ideas what does not work without going into too many technical details.

ezio-melotti
ezio-melotti reviewed Aug 1, 2022
View reviewed changes
tiran and others added 5 commits August 1, 2022 21:53
@tiran @mdboom
Update Doc/library/intro.rst
d9a2457 
Co-authored-by: Michael Droettboom <mdboom@gmail.com>
@tiran @ezio-melotti
Update Doc/library/intro.rst
6fee2e2 
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
@tiran @ezio-melotti
Update Doc/library/intro.rst
2bebb1b 
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
@tiran
Remove stray 'a'
c7db243
@tiran
More links, explain sockest
b9e04e7
CAM-Gerlach
CAM-Gerlach reviewed Aug 2, 2022
View reviewed changes
Copy link
Member

@CAM-Gerlach CAM-Gerlach left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few questions on better explaining confusing or potentially mistyped content, and a bunch of small suggestions mostly fixing grammar and organization issues (including a bunch of identical comma splices), improving phrasing, and a few reST deficiencies.

tiran and others added 2 commits August 2, 2022 08:09
@tiran @CAM-Gerlach
Apply suggestions from code review
c0061fd 
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
@tiran
Move link, rearrange text
1d5d890
@tiran tiran added the needs backport to 3.11 only security fixes label Aug 2, 2022
merwok
merwok reviewed Aug 2, 2022
View reviewed changes
tiran and others added 2 commits August 2, 2022 18:31
@tiran @merwok
Update .gitignore
61192a0 
Co-authored-by: Éric <merwok@netwok.org>
@tiran @CAM-Gerlach
Update Misc/NEWS.d/next/Documentation/2022-07-29-23-02-19.gh-issue-95…
a16f568 
…451.-tgB93.rst

Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
@tiran tiran merged commit e3b6ff1 into python:main Aug 2, 2022
@miss-islington
Copy link
Contributor

Thanks @tiran for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖

@tiran tiran deleted the gh-95451-wasm-docs branch August 2, 2022 19:00
@bedevere-bot
Copy link

GH-95580 is a backport of this pull request to the 3.11 branch.

@bedevere-bot bedevere-bot removed the needs backport to 3.11 only security fixes label Aug 2, 2022
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Aug 2, 2022
@tiran @miss-islington
pythongh-95451: Update docs for wasm32-emscripten and -wasi platforms (…
dd73244 
…pythonGH-95452)

Co-authored-by: Éric <merwok@netwok.org>
Co-authored-by: Michael Droettboom <mdboom@gmail.com>
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
(cherry picked from commit e3b6ff1)

Co-authored-by: Christian Heimes <christian@python.org>
@tiran
Copy link
Member Author

tiran commented Aug 2, 2022

Thank you for your feedback and reviews!

miss-islington added a commit that referenced this pull request Aug 2, 2022
@miss-islington @tiran
gh-95451: Update docs for wasm32-emscripten and -wasi platforms (GH-9…
72cad6c 
…5452)

Co-authored-by: Éric <merwok@netwok.org>
Co-authored-by: Michael Droettboom <mdboom@gmail.com>
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
(cherry picked from commit e3b6ff1)

Co-authored-by: Christian Heimes <christian@python.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@merwok merwok merwok left review comments

@CAM-Gerlach CAM-Gerlach CAM-Gerlach left review comments

@ezio-melotti ezio-melotti ezio-melotti left review comments

@mdboom mdboom mdboom approved these changes

@brettcannon brettcannon Awaiting requested review from brettcannon

@ethanfurman ethanfurman Awaiting requested review from ethanfurman ethanfurman is a code owner

@vsajip vsajip Awaiting requested review from vsajip vsajip is a code owner

@1st1 1st1 Awaiting requested review from 1st1 1st1 is a code owner

@asvetlov asvetlov Awaiting requested review from asvetlov asvetlov is a code owner

Assignees
No one assigned
Labels
docs Documentation in the Doc dir
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
7 participants
@tiran @miss-islington @bedevere-bot @mdboom @merwok @CAM-Gerlach @ezio-melotti