"""

This module provides access to named

[web workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)

defined in `<script>` tags, and utilities for dynamically creating workers

from Python code.

Named workers are Python web workers defined in HTML with a `name` attribute

that can be referenced from the main thread or other workers. This module

provides the `workers` object for accessing named workers and the

`create_named_worker()` function for dynamically creating them.

Accessing named workers:

```html

<!-- Define a named worker -->

<script type="py" worker name="calculator">

def add(a, b):

return a + b

__export__ = ["add"]

</script>

<!-- Access from main thread -->

<script type="mpy">

from pyscript import workers

calc = await workers["calculator"]

result = await calc.add(5, 3)

print(result) # 8

</script>

```

Dynamically creating named workers:

```python

from pyscript import create_named_worker

# Create a worker from a Python file.

worker = await create_named_worker(

src="./background_tasks.py",

name="task-processor"

)

# Use the worker's exported functions.

result = await worker.process_data([1, 2, 3, 4, 5])

print(result)

```

Key features:

- Access (`await`) named workers via dictionary-like syntax.

- Dynamically create workers from Python.

- Cross-interpreter support (Pyodide and MicroPython).

Worker access is asynchronous - you must `await workers[name]` to get

a reference to the worker. This is because workers may not be ready

immediately at startup.

"""

import js

import json

from polyscript import workers as _polyscript_workers

class _ReadOnlyWorkersProxy:

"""

A read-only proxy for accessing named web workers. Use

`create_named_worker()` to create new workers found in this proxy.

This provides dictionary-like access to named workers defined in

the page. It handles differences between Pyodide and MicroPython

implementations transparently.

(See: https://github.com/pyscript/pyscript/issues/2106 for context.)

The proxy is read-only to prevent accidental modification of the

underlying workers registry. Both item access and attribute access are

supported for convenience (especially since HTML attribute names may

not be valid Python identifiers).

```python

from pyscript import workers

# Access a named worker.

my_worker = await workers["worker-name"]

result = await my_worker.some_function()

# Alternatively, if the name works, access via attribute notation.

my_worker = await workers.worker_name

result = await my_worker.some_function()

```

**This is a proxy object, not a dict**. You cannot iterate over it or

get a list of worker names. This is intentional because worker

startup timing is non-deterministic.

"""

def __getitem__(self, name):

"""

Get a named worker by `name`. It returns a promise that resolves to

the worker reference when ready.

This is useful if the underlying worker name is not a valid Python

identifier.

```python

worker = await workers["my-worker"]

```

"""

return js.Reflect.get(_polyscript_workers, name)

def __getattr__(self, name):

"""

Get a named worker as an attribute. It returns a promise that resolves

to the worker reference when ready.

This allows accessing workers via dot notation as an alternative

to bracket notation.

```python

worker = await workers.my_worker

```

"""

return js.Reflect.get(_polyscript_workers, name)

# Global workers proxy for accessing named workers.

workers = _ReadOnlyWorkersProxy()

"""Global proxy for accessing named web workers."""

async def create_named_worker(src, name, config=None, type="py"):

"""

Dynamically create a web worker with a `src` Python file, a unique

`name` and optional `config` (dict or JSON string) and `type` (`py`

for Pyodide or `mpy` for MicroPython, the default is `py`).

This function creates a new web worker by injecting a `<script>` tag into

the document. The worker will be accessible via the `workers` proxy once

it's ready.

It returns a promise that resolves to the worker reference when ready.

```python

from pyscript import create_named_worker

# Create a Pyodide worker.

worker = await create_named_worker(

src="./my_worker.py",

name="background-worker"

)

# Use the worker.

result = await worker.process_data()

# Create with standard PyScript configuration.

worker = await create_named_worker(

src="./processor.py",

name="data-processor",

config={"packages": ["numpy", "pandas"]}

)

# Use MicroPython instead.

worker = await create_named_worker(

src="./lightweight_worker.py",

name="micro-worker",

type="mpy"

)

```

!!! info

**The worker script should define** `__export__` to specify which

functions or objects are accessible from the main thread.

"""

# Create script element for the worker.

script = js.document.createElement("script")

script.type = type

script.src = src

# Mark as a worker with a name.

script.setAttribute("worker", "")

script.setAttribute("name", name)

# Add configuration if provided.

if config:

if isinstance(config, str):

config_str = config

else:

config_str = json.dumps(config)

script.setAttribute("config", config_str)

# Inject the script into the document and await the result.

js.document.body.append(script)

return await workers[name]