Errors, missing code/links in Workers section

[Neon22]

In one place where workers are mentioned:

• https://docs.pyscript.net/2025.3.1/user-guide/workers/

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

2. 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.)

[Neon22]

So using the example on the page above - and trying to create a worker from within main.py:

from pyscript import PyWorker
# The type MUST be given and can be either `micropython` or `pyodide`
my_worker = PyWorker("my-worker-code.py", type="micropython")

Creating worker from main

I change to pyodide and add config (which was hard to work out) to get:
But can I even add a config ? I guess I can because its pyodide not mpy right? but is the intepreter defined like this or redundant because I specified the type?

from pyscript import PyWorker
from pyscript.ffi import to_js
worker_config = {
       "interpreter": "pyodide/pyodide.js",
       "packages": [ ],
       "files": {"./satin_worker/worker.py" : "",
                   "./satin_worker/get_satins.py" : "",
                   "./satin_worker/weave_pattern.py" : ""}
        }
worker = PyWorker("worker.py", type="pyodide", config=ltk.to_js(worker_config))
print("before ready")
# Await until Pyodide has completed its bootstrap, and is ready.
await self.worker.ready
print("after ready")

With an empty file "./worker.py" this code runs and reports the two "ready states" on the pyscript terminal.
Even if "./satin_worker/worker.py" does not exist but ./worker.py does. No error reported.

If I change the code to:

worker = PyWorker("./satin_worker/worker.py", type="pyodide", config=to_js(worker_config))

I also get the two responses even if there is no "./satin_worker/worker.py"
The existence of the worker.py file seems ignored.

I suppose the environment starts but the worker has not been called yet - so it is not checked for existence.
but it is called because if I create the file and add two lines to it:

from pyscript import sync
print("Foo (onlyappears in JS console)")
sync.worker_msg("Bar")  # in terminalfile

Then "Foo (only appears in JS console)" will be printed into the JS console but not the pyscript terminal.
So now we know the system does not report the worker as missing in terminal or JS console.

and if main.py has one line added to it:
worker.sync.worker_msg = lambda var: print("Pyodide bootstrapped",var)
so now it looks like:

from pyscript import PyWorker
from pyscript.ffi import to_js
worker_config = {
       "interpreter": "pyodide/pyodide.js",
       "packages": [ ],
       "files": {"./satin_worker/worker.py" : "",
                   "./satin_worker/get_satins.py" : "",
                   "./satin_worker/weave_pattern.py" : ""}
        }
worker = PyWorker("worker.py", type="pyodide", config=to_js(worker_config))
worker.sync.worker_msg = lambda var: print("Pyodide bootstrapped",var)
print("before ready")
# Await until Pyodide has completed its bootstrap, and is ready.
await worker.ready
print("after ready")

Then I see in the pyscript terminal ""Pyodide bootstrapped Bar"
So now I know the worker is being started and called.

Doing something in the worker on request

So now to try to get the worker doing something after initialisation

If I add this function to main.py:

def worker_start_task(value):
    print("Initialising task", value)
    result = await worker.sync.long_task(value)
    print("Result:",result)

and in worker I add:

def long_task(value):
    return [1,2,value]

# Define what to export to the main thread.
__export__ = ["long_task"]

I cannot get worker_start_task("Baz") to print or do anything.

The docs seem to confuse starting a worker in index.html with starting a worker in main.py
These seem different enough to need their own sections.
The absence of any error messages in the JS console or terminal makes it hard to work out what is not happening.

[WebReflection]

the sync is something you need to import and orchestrate, it's not based on each module exports because that would easily cause collisions between modules exported name ... you are better off with Polyscript documentation if you want to use internals or less documented parts, we have named workers to do what you are after, here it looks like you want to use internal bricks but, most importantly, there is a reason PyWorker is poorly documented, we actually believed we should remove it as it causes all the issues you are after because people use it to do things they might not fully understand so, at that point, use named workers or just workers as scripts on the page. The dance/orchestration is not trivial and at the end of the day those utilities are limited in features compared to the donkey, exported by the JS module, or the XWorker itself exported by Polyscript.

[Neon22]

I agree completely but I am using pyscript docs page.
So this page needs (IMHO) to be updated to be how we should use it.
I can't find docs on how to use it properly

[Neon22]

BTW the reason why I picked PyWorker from the docs is I want to use a worker in my single file components - so that I can make larger UI's out of files, which do the UI for one aspect of what is on the page.
If I can encapsulate the work that needs to be done into one file, and not have it require globals, then I can have isolation between each component and they won't affect each other.

If that's not a goal for pyscript - that's ok, Just means I won't be able to do that. I will then find another way to do it.
My work on this is documented in my PR for pyscript examples: pyscript/examples#26

[Neon22]

I have just found a section in the docs on named workers. Thanks for your hint.

• https://docs.pyscript.net/2025.3.1/api/#pyscriptworkers

I will see if this helps me do what I want. Cheers

[Neon22]

OK. so the recommended mechanism is to use "Named workers" and not Pyworkers.
Named workers appear to be only possible from the index.html file - so for each Single file Component a manual mod to index.html is required.
Info on Named workers appears in only one place (which alas can only be found by typing "named workers" exactly. If you capitalize a word then it is not found) here:

• https://docs.pyscript.net/2025.3.1/api/#pyscriptworkers

The right thing to do appears to be adding the following to index.html - worker's name is "name_A":

<!-- Worker -->
<script type="py" src="./worker_A.py" config="./worker_A.toml" worker name="name_A">     

The "worker_A.toml" file might look like:

packages = ["pyjokes"]

The worker file "worker_A.py" might look like:

from pyscript import sync
import pyjokes
from random import randrange

print("MSG: worker_started (in console)")

def get_a_joke(value=3):
    print(" - Getting a Joke (in console)", value)
    joke = pyjokes.get_joke()
    return joke

def get_a_number(maximum):
    print(" - getting a rand num (in console)")
    num = randrange(0,maximum)
    return num

# Define what to export to the main thread.
__export__ = ["get_a_joke", "get_a_number"]

The main.py might have a section like: (taken from link above)

if __name__ == "__main__":
    # start workers
    for el in ltk.window.document.querySelectorAll("[type='py'][worker][name]"):
        print("found", el, el.id)
        await workers[el.getAttribute('name')]
    print("workers loaded but we waited")

But this does not allow execution to continue until the workers are loaded and does not allow us to get access to the created worker.
A more useful approach might be to initiate worker starting asynchronously. And when workers are started, somehow signal a variable or function call to indicate they have.
This could be used to make sure the worker is not called until its ready, or to put a "loading" indicator over a section of the UI which the worker will eventually be called to create content for.

Also this approach does not allow us to get access to the created worker.
In the docs the prev example does this:

pyworker = await workers["name_A"]

This assigns pyworker to the discovered and now active worker. But the general example above does not give us a handle.

To call the worker and get a result back we need to add this to main.py

print("Initialising task")
pyworker = await workers["name_A"]
result = await pyworker.get_a_joke(12)
print("Joke:",result)
for i in range(3):
    result = await pyworker.get_a_number(12)
    print("Number:",result)

But it does work...

OK so if I had a request it would be:

• how to asynchronously set the workers off to get ready, and get handles for them for later use.
• Use a more complex example like above so name confusion is minimised.
• get the worker docs in a smaller number of places
• change doc search to ignore capitalisation
• Determine if there is a similar mechanism that can be initiated without manually inserting into index.html. So that I can more easily have single file components (I was hoping this was Pyworker but apparently not)

[Neon22]

OK. we have an additional problem.
The worker only ever runs once...

Here is a working example:

• https://pyscript.com/@neon22/starter-05-workers/latest?files=main.py,worker_A.py,index.html
• It uses mpy for main and py for worker
• The ltk is used for on screen UI
• There is extensive printing in the sliding window terminal about what is happening.
• looking in the JS console (assuming chrome) shows the prints that do not go to the pyterminal but do go to the console.

I was really hoping you could call a Named worker more than just once.

• I added a bug report at Named workers only run once pyscript#2330