pyscript / pyscript/docs

Errors, missing code/links in Workers section

Open
#179 7 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
17
Forks
20
PR merge metrics
No merged PRs in 30d

Description

In one place where workers are mentioned:

There are several pieces of code with code elements missing.
Also the two ways workers can be started are confusing because of this missing code.
Also the link to a working example is 404

The only problem with this is that people who are NOT Javascript experts may not be able to work out all the usecases that are legitimate from the code available. (I know I can't.)

  1. Missing link:
  • In this section of the page is a link:
The values passed between the main thread and the worker must be serializable. Try the example given above via [this project on PyScript.com](https://pyscript.com/@ntoll/tiny-silence/latest).
  • this link is 404
  1. In the Section Common use case the code refers to greeting which is defined in the previous section Worker interactions but not in this code. Its not clear which code should be carried forward from example to example and which is standalone. Ideally all the code for main and worker should (IMHO) be standalone and complete - or point to an example which works.

IMHO - It would be nice if the sections showed:

  • starting a worker from index.html
    • that does one job and has one function (from pyscript import workers)?
    • same but can be called multiple times with multiple functions (__export__ = ["fname1", "fname2"])?
    • some of which update the dom directly and some of which pass data back to main.
  • starting from python using Pyworker (from pyscript import PyWorker)
    • defining multiple functions that can be called,
    • setting a config so a package can be loaded,
    • some of which update the dom directly and some of which pass data back to main.
  • whatever is required for the donkey to:
    • send new code to the donkey for it to operate with,
    • see results like donkey's main use case - running code and seeing the results in a textarea,
    • see results where it can do the jobs defined for the previous two cases (sending data back).

IMHO this would make it easier for people to work out how to use workers in pyscript.
Any examples that could be generated for the docs would also be great and it would be nice if they followed the categories indicated above.
(I'd happily contribute a demo if I could work out how to make it ALL work.)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the Workers documentation page at https://docs.pyscript.net/2025.3.1/user-guide/workers/ and inspect the Worker interactions and Common use case sections. Verify the broken PyScript.com link and identify missing code or unclear dependencies between examples. Done means the examples are complete or clearly cross-referenced, the link works or is replaced, and the worker startup patterns are understandable.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, python
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.