You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This page contains most common questions and "*gotchas*" asked in [our Discord channel](https://discord.com/channels/972017612454232116/972017612454232119) or within our community.
3
+
This page contains the most common questions and "*gotchas*" asked on
4
+
[our Discord server](https://discord.gg/HxvBtukrg2), in
5
+
[our community calls](https://www.youtube.com/@PyScriptTV), or
6
+
within our community.
4
7
5
-
There are two major areas we'd like to help with, grouped here as [common errors](#common-errors) and as [common hints](#common-hints).
8
+
There are two major areas we'd like to explore:
9
+
[common errors](#common-errors) and [helpful hints](#helpful-hints).
6
10
7
11
## Common Errors
8
12
9
-
This area contains most common issues our users might face due technical reasons or some misconception around the topic.
13
+
These are the most common errors users of PyScript encounter.
10
14
11
15
### SharedArrayBuffer
12
16
13
-
This is not by accident the very first, and most common, error our users might encounter while developing or deploying *PyScript* projects.
17
+
This is the first and most common error users may encounter with PyScript.
Unable to use SharedArrayBuffer due insecure environment.
18
27
Please read requirements in MDN: ...
19
-
20
-
The error contains [a link to MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer#security_requirements) but it's easy to get lost behind the amount of content provided by this topic.
21
-
22
-
**When**
23
-
24
-
This errors happens in one of these combined scenarios:
25
-
26
-
* the server doesn't provide the correct headers to handle security concerns or there is no *Service Worker* able to override headers, as described [in the worker page](http://127.0.0.1:8000/user-guide/workers/) and ...
27
-
* there is a `worker` attribute in the *py* or *mpy* script element and the [sync_main_only](https://pyscript.github.io/polyscript/#extra-config-features) flag is not present or not `True`
28
-
* there is a `<script type="py-editor">` that uses a *worker* behind the scene
29
-
* there is an explicit *PyWorker* or *MPWorker* bootstrap
30
-
31
-
The only exception is when the `sync_main_only = True` is part of the config with the following caveats:
32
-
33
-
* it is not possible to manipulate the DOM or do anything meaningful on the main thread directly because *Atomics* cannot guarantee sync-like locks within *worker* ↔ *main* operations
34
-
* the only desired use case is to expose, from the worker, `pyscript.sync` utilities that will need to be awaited from the *main* once invoked
35
-
* the worker can only *await* main related references, one after the other, so that *DX* is really degraded in case one still needs to interact with main
36
-
37
-
If your project simply bootstraps on the *main* thread, none of this is relevant because no *worker* would need special features.
38
-
39
-
**Why**
40
-
41
-
The only way to make `document.getElementById('some-id').value` work out of a *worker* execution context is to use these two JS primitives:
42
-
43
-
***SharedArrayBuffer**, which allows multiple threads to read and / or write into a chunk of memory that is, like the name suggests, shared across threads
44
-
***Atomics**, which is needed to both `wait(sab, index)` and `notify(sab, index)` to unlock the awaiting thread
45
-
46
-
While a *worker* is waiting for some operation on main to happen, this is not using the CPU, it just idles until that index of the shared buffer gets notified, effectively never blocking the *main* thread, still pausing its own execution until such buffer is notified for changes.
47
-
48
-
As overwhelming or complicated as this might sounds, these two fundamental primitives make *main* ↔ *worker* interoperability an absolute wonder in term of *DX* so that we encourage to always prefer *workers* over *main* scripts, specially when it comes to *Pyodide* related projects with its heavier bootstrap or computation abilities, yet still delivering a *main-like* development experience.
49
-
50
-
Unfortunately, due past security concerns and attacks to shared buffers, each server or page needs to allow extra security to prevent malicious software to also read or write into these buffers but be assured that if you own your code, your project, and you trust the modules or 3rd party code you need and use, **there are no security concerns around this topic within this project**, it's simply an unfortunate "*one rule catch all*" standard any server can either enable or disable as it pleases.
28
+
```
29
+
30
+
The error contains
31
+
[a link to MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer#security_requirements)
32
+
but it's the amount of content provided on this topic is overwhelming.
33
+
34
+
#### When
35
+
36
+
This error happens when **the server delivering your PyScript application is
37
+
incorrectly configured**. It fails to provide the correct headers to handle
38
+
security concerns for web workers, or you're not using
39
+
[mini-coi](https://github.com/WebReflection/mini-coi#readme) as an alternative
40
+
solution. (These requirements are explored
41
+
[in the worker page](../user-guide/workers#http-headers).)
42
+
43
+
**And** at least one of the following scenarios is true:
44
+
45
+
* There is a `worker` attribute in the *py* or *mpy* script element and the
to both `wait(sab, index)` (`sab` is a `SharedArrayBuffer`) and
83
+
`notify(sab, index)` to unlock the awaiting thread.
84
+
85
+
While a worker waits for an operation on main to happen, it is not using the
86
+
CPU. It idles until the referenced index of the shared buffer changes,
87
+
effectively never blocking the main thread while still pausing its own
88
+
execution until the buffer's index is changed.
89
+
90
+
As overwhelming or complicated as this might sounds, these two fundamental
91
+
primitives make main ↔ worker interoperability an absolute wonder in term of
92
+
developer experience. Therefore, we encourage folks to prefer using workers
93
+
over running Python in the main thread. This is especially so when using
94
+
Pyodide related projects, because of its heavier bootstrap or computation
95
+
requirements. Using workers ensures the main thread (and thus, the user
96
+
interface) remains unblocked.
97
+
98
+
Unfortunately, due to security concerns and potential attacks to shared
99
+
buffers, each server or page needs to allow extra security to prevent malicious
100
+
software to read or write into these buffers. But be assured that if you own
101
+
your code, your project, and you trust the modules or 3rd party code you need
102
+
and use, **there are less likely to be security concerns around this topic
103
+
within your project**. This situation is simply an unfortunate "*one rule catch
104
+
all*" standard any server can either enable or disable as it pleases.
51
105
52
106
### Borrowed Proxy
53
107
54
-
This is another classic error that might happen with listeners, timers or any other circumstance where a *Python* callback might be lazily invoked in the *JS* side of affair:
108
+
This is another common error that happens with listeners, timers or in any
109
+
other situation where a Python callback is lazily invoked from JavaScript:
55
110
56
111
!!! failure
57
112
58
-
Uncaught Error: This borrowed proxy was automatically destroyed at the end of a function call. Try using create_proxy or create_once_callable.
Uncaught Error: This borrowed proxy was automatically destroyed at the end of a function call.
119
+
Try using create_proxy or create_once_callable.
59
120
For more information about the cause of this error, use `pyodide.setDebug(true)`
121
+
```
60
122
61
-
**When**
123
+
#### When
62
124
63
125
This error usually happens in *Pyodide* only related project, and only if a *Python* callback has been directly passed along as *JS* function parameter:
64
126
@@ -85,7 +147,7 @@ This flag tries to intercept all *Python* proxies passed to a *JS* callback and
85
147
86
148
The [FinalizationRegistry](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry) is the primitive used to do so. It is not observable and nobody can predict when it will run to free, hence destroy, retained *Python* proxies. This means that *RAM* consumption might be slightly higher, but it's the *JS* engine responsibility to guarantee that when such *RAM* consumption is too high, that finalization registry would call and free all retained proxies, leaving room for more *RAM*.
87
149
88
-
**Why**
150
+
#### Why
89
151
90
152
Most *WASM* based runtimes have their own garbage collector or memory management but when their references are passed along another programming language they cannot guarantee these references will ever be freed, or better, they lose control over that memory allocation because they cannot know when such allocation won't be needed anymore.
91
153
@@ -176,7 +238,7 @@ NameError: name 'failure' isn't defined
176
238
177
239
The same applies when the error is shown in devtools/console where unfortunately the stack right after the error message might be a bit distracting but it's still well separated from the error message itself.
178
240
179
-
## Common Hints
241
+
## Helpful Hints
180
242
181
243
This area contains most common questions, hacks, or hints we provide to the community.
0 commit comments