Skip to content

Commit 520f6db

Browse files
ntollntoll
authored
Merge pull request #189 from pyscript/is_none
Added documentation for `ffi.is_none(ref)`
2 parents fc55f9b + 2332f4f commit 520f6db

File tree

7 files changed

+66
-16
lines changed

7 files changed

+66
-16
lines changed

‎docs/beginning-pyscript.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -117,8 +117,8 @@ module in the document's `<head>` tag:
117117
<meta charset="utf-8" />
118118
<meta name="viewport" content="width=device-width,initial-scale=1" />
119119
<title>🦜 Polyglot - Piratical PyScript</title>
120-
<link rel="stylesheet" href="https://pyscript.net/releases/2025.7.3/core.css">
121-
<script type="module" src="https://pyscript.net/releases/2025.7.3/core.js"></script>
120+
<link rel="stylesheet" href="https://pyscript.net/releases/2025.8.1/core.css">
121+
<script type="module" src="https://pyscript.net/releases/2025.8.1/core.js"></script>
122122
</head>
123123
<body>
124124

@@ -168,8 +168,8 @@ In the end, our HTML should look like this:
168168
<meta charset="utf-8" />
169169
<meta name="viewport" content="width=device-width,initial-scale=1" />
170170
<title>🦜 Polyglot - Piratical PyScript</title>
171-
<link rel="stylesheet" href="https://pyscript.net/releases/2025.7.3/core.css">
172-
<script type="module" src="https://pyscript.net/releases/2025.7.3/core.js"></script>
171+
<link rel="stylesheet" href="https://pyscript.net/releases/2025.8.1/core.css">
172+
<script type="module" src="https://pyscript.net/releases/2025.8.1/core.js"></script>
173173
</head>
174174
<body>
175175
<h1>Polyglot 🦜 💬 🇬🇧 ➡️ 🏴‍☠️</h1>

‎docs/user-guide/ffi.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Our `pyscript.ffi` offers the following utilities:
1616
counterpart.
1717
* `ffi.create_proxy(def_or_lambda)` proxies a generic Python function into a
1818
JavaScript one, without destroying its reference right away.
19+
* `ffi.is_none(reference)` to check if a specific value is either `None` or `JsNull`.
1920

2021
Should you require access to Pyodide or MicroPython's specific version of the
2122
FFI you'll find them under the `pyodide.ffi` and `micropython.ffi` namespaces.
@@ -209,3 +210,52 @@ only in Pyodide can we then destroy such proxy:
209210
js.setTimeout(proxy, 1000, "success");
210211
</script>
211212
```
213+
214+
## is_none
215+
216+
*Pyodide* version `0.28` onwards has introduced a new *nullish* value that
217+
precisely represents JavaScript's `null` value.
218+
219+
Previously, both JavaScript `null` and `undefined` would have been converted
220+
into Python's `None` but, alas, some APIs behave differently if a value is
221+
`undefined` or explicitly `null`.
222+
223+
For example, in *JSON*, `null` would survive serialization while `undefined`
224+
would vanish. To preserve that distinction in *Python*, the conversion
225+
between *JS* and *Python* now has a new `pyodide.ffi.jsnull` as explained in
226+
the
227+
[pyodide documentation](https://pyodide.org/en/stable/usage/type-conversions.html#javascript-to-python).
228+
229+
In general, there should be no surprises. But, especially when dealing with the
230+
*DOM* world, most utilities and methods return `null`.
231+
232+
To simplify and smooth-out this distinction, we decided to introduce `is_null`,
233+
as [demoed here](https://pyscript.com/@agiammarchi/pyscript-ffi-is-none/latest?files=main.py):
234+
235+
```html title="pyscript.ffi.is_none"
236+
<!-- success in both Pyodide and MicroPython -->
237+
<script type="py">
238+
from pyscript.ffi import is_none
239+
import js
240+
241+
js_undefined = js.undefined
242+
js_null = js.document.body.getAttribute("nope")
243+
244+
print(js_undefined is None) # True
245+
print(js_null) # jsnull
246+
print(js_null is None) # False
247+
248+
# JsNull is still a "falsy" value
249+
if (js_null):
250+
print("this will not be shown")
251+
252+
# safely compared against both
253+
print(is_none(js_undefined)) # True
254+
print(is_none(js_none)) # True
255+
</script>
256+
```
257+
258+
Please note that in *MicroPython* the method works the same but, as we try to
259+
reach feature-parity among runtimes, it is suggested to use `is_none(ref)`
260+
even if, right now, there is no such distinction between `null` and
261+
`undefined` in MicroPython.

‎docs/user-guide/first-steps.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,9 @@ CSS:
2020
<meta charset="UTF-8">
2121
<meta name="viewport" content="width=device-width,initial-scale=1.0">
2222
<!-- PyScript CSS -->
23-
<link rel="stylesheet" href="https://pyscript.net/releases/2025.7.3/core.css">
23+
<link rel="stylesheet" href="https://pyscript.net/releases/2025.8.1/core.css">
2424
<!-- This script tag bootstraps PyScript -->
25-
<script type="module" src="https://pyscript.net/releases/2025.7.3/core.js"></script>
25+
<script type="module" src="https://pyscript.net/releases/2025.8.1/core.js"></script>
2626
</head>
2727
<body>
2828
<!-- your code goes here... -->

‎docs/user-guide/plugins.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ For example, this will work because all references are contained within the
100100
registered function:
101101

102102
```js
103-
import { hooks } from "https://pyscript.net/releases/2025.7.3/core.js";
103+
import { hooks } from "https://pyscript.net/releases/2025.8.1/core.js";
104104

105105
hooks.worker.onReady.add(() => {
106106
// NOT suggested, just an example!
@@ -114,7 +114,7 @@ hooks.worker.onReady.add(() => {
114114
However, due to the outer reference to the variable `i`, this will fail:
115115

116116
```js
117-
import { hooks } from "https://pyscript.net/releases/2025.7.3/core.js";
117+
import { hooks } from "https://pyscript.net/releases/2025.8.1/core.js";
118118

119119
// NO NO NO NO NO! ☠️
120120
let i = 0;
@@ -147,7 +147,7 @@ the page.
147147

148148
```js title="log.js - a plugin that simply logs to the console."
149149
// import the hooks from PyScript first...
150-
import { hooks } from "https://pyscript.net/releases/2025.7.3/core.js";
150+
import { hooks } from "https://pyscript.net/releases/2025.8.1/core.js";
151151

152152
// The `hooks.main` attribute defines plugins that run on the main thread.
153153
hooks.main.onReady.add((wrap, element) => {
@@ -197,8 +197,8 @@ hooks.worker.onAfterRun.add(() => {
197197
<!-- JS plugins should be available before PyScript bootstraps -->
198198
<script type="module" src="./log.js"></script>
199199
<!-- PyScript -->
200-
<link rel="stylesheet" href="https://pyscript.net/releases/2025.7.3/core.css">
201-
<script type="module" src="https://pyscript.net/releases/2025.7.3/core.js"></script>
200+
<link rel="stylesheet" href="https://pyscript.net/releases/2025.8.1/core.css">
201+
<script type="module" src="https://pyscript.net/releases/2025.8.1/core.js"></script>
202202
</head>
203203
<body>
204204
<script type="mpy">

‎docs/user-guide/pygame-ce.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -106,8 +106,8 @@ will be placed. Make sure to update the pyscript release to the latest version.
106106
<title>PyScript Pygame-CE Quickstart</title>
107107
<meta charset="UTF-8">
108108
<meta name="viewport" content="width=device-width,initial-scale=1.0">
109-
<link rel="stylesheet" href="https://pyscript.net/releases/2025.7.3/core.css">
110-
<script type="module" src="https://pyscript.net/releases/2025.7.3/core.js"></script>
109+
<link rel="stylesheet" href="https://pyscript.net/releases/2025.8.1/core.css">
110+
<script type="module" src="https://pyscript.net/releases/2025.8.1/core.js"></script>
111111
</head>
112112
<body>
113113
<canvas id="canvas" style="image-rendering: pixelated"></canvas>

‎docs/user-guide/workers.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -282,9 +282,9 @@ Here's how:
282282
<meta charset="utf-8">
283283
<meta name="viewport" content="width=device-width,initial-scale=1">
284284
<!-- PyScript CSS -->
285-
<link rel="stylesheet" href="https://pyscript.net/releases/2025.7.3/core.css">
285+
<link rel="stylesheet" href="https://pyscript.net/releases/2025.8.1/core.css">
286286
<!-- This script tag bootstraps PyScript -->
287-
<script type="module" src="https://pyscript.net/releases/2025.7.3/core.js"></script>
287+
<script type="module" src="https://pyscript.net/releases/2025.8.1/core.js"></script>
288288
<title>PyWorker - mpy bootstrapping pyodide example</title>
289289
<script type="mpy" src="main.py"></script>
290290
</head>

‎version.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
{
2-
"version": "2025.7.3"
2+
"version": "2025.8.1"
33
}

0 commit comments

Comments
 (0)