Updated worker docs.

Author: ntoll

docs/api.md

@@ -805,6 +805,59 @@ PyWorker("worker.py", type="micropython")
 <div id="output"></div>  <!-- The display target -->
 ```
 
+### `pyscript.workers`
+
+The `pyscript.workers` reference allows Python code in the main thread to
+easily access named workers (and their exported functionality).
+
+For example, the following Pyodide code may be running on a named worker
+(see the `name` attribute of the `script` tag):
+
+```html
+<script type="py" worker name="py-version">
+import sys
+
+def version():
+    return sys.version
+
+# define what to export to main consumers
+__export__ = ["version"]
+</script>
+```
+
+While over on the main thread, this fragment of MicroPython will be able to
+access the worker's `version` function via the `workers` reference:
+
+```html
+<script type="mpy" async>
+from pyscript import workers
+
+pyworker = await workers["py-version"]
+
+# print the pyodide version
+print(await pyworker.version())
+</script>
+```
+
+Importantly, the `workers` reference will **NOT** provide a list of
+known workers, but will only `await` for a reference to a named worker
+(resolving when the worker is ready). This is because the timing of worker
+startup is not deterministic.
+
+Should you wish to await for all workers on the page at load time, it's
+possible to loop over matching elements in the document like this:
+
+```html
+<script type="mpy" async>
+from pyscript import document, workers
+
+for el in document.querySelectorAll("[type='py'][worker][name]"):
+    await workers[el.getAttribute('name')]
+
+# ... rest of the code
+</script>
+```
+
 ## Worker only features
 
 ### `pyscript.js_import`

docs/user-guide/workers.md

@@ -69,6 +69,19 @@ attribute flag:
 <script type="py" src="./my-worker-code.py" worker></script>
 ```
 
+You may also want to add a `name` attribute to the tag, so you can use
+`pyscript.workers` in the main thread to retrieve a reference to the worker:
+
+```html
+<script type="py" src="./my-worker-code.py" worker name="my-worker"></script>
+```
+
+```python
+from pyscript import workers
+
+my_worker = await workers["my-worker"]
+```
+
 Alternatively, to launch a worker from within Python running on the main thread
 use the [pyscript.PyWorker](../../api/#pyscriptpyworker) class and you must
 reference both the target Python script and interpreter type:
@@ -77,7 +90,7 @@ reference both the target Python script and interpreter type:
 from pyscript import PyWorker
 
 # The type MUST be given and can be either `micropython` or `pyodide`
-PyWorker("my-worker-code.py", type="micropython")
+my_worker = PyWorker("my-worker-code.py", type="micropython")
 ```
 
 ## Worker interactions
@@ -121,6 +134,34 @@ greeting = sync.hello("PyScript")
 window.console.log(greeting)
 ```
 
+Alternatively, for the main thread to call functions in a worker, specify the
+functions in a `__export__` list:
+
+```python title="Python code on the worker."
+import sys
+
+def version():
+    return sys.version
+
+# Define what to export to the main thread.
+__export__ = ["version", ]
+```
+
+Then ensure you have a reference to the worker in the main thread (for
+instance, by using the `pyscript.workers`):
+
+```html title="Creating a named worker in the web page."
+<script type="py" src="./my-worker-code.py" worker name="my-worker"></script>
+```
+
+```python title="Referencing and using the worker from the main thread."
+from pyscript import workers
+
+my_worker = await workers["my-worker"]
+
+print(await my_worker.version())
+```
+
 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).