Update examples.md

[Neon22]

included new examples. Made notes about what packages are loaded and added complexity sub headings.

Also note there are a number of errors in the examples.

Note:

• Updated from 14 to 20 found at above link
• No micropython examples - all are pyodide
• No worker examples
• async used in some examples - possibly obsolete now?
• fetch done several ways - possibly obsolete now?

[Neon22]

Reason for doing this was the increasing number of requests for "Does package X work in pyscript".

This led me to a closer examination of the supplied reference examples. Some of which appear to need updating to approaches preferred in 2024.8.2

Notable misses:

• matplotlib works with numpy despite not referencing it
• no micropython examples
• no preferred worker workflows with mpy and py scripts
• webgl example (icosahedron) is not using modules but instead a very old cdn which does not work with modern three.js versions
• async is now at top level - maybe 'simple-panel' will run ?

Missing docs:

• when to:
  • just include a package in toml for python access and
  • when you will need to load it in index.html and
  • when you can get away with only loading the javascript library in index.html and importing that via js (e.g. D3 example does this)

[WebReflection]

missing link?

[Neon22]

added link.
Do you think these examples should also be updated ? - beyond my expertise sorry.

[WebReflection]

I am not sure we changed so much up to the point we need updates but if sme example is badly broken I'd rather try to fix it or understand why is that, if that makes sense.

[Neon22]

Four primary issues you might want to revisit:

• Icosahedron example

  • because it uses the older style of three.js directly imported in index.html.
  • version 147 is now 20 releases behind today's version 167.
  • soon after 147 they changed to modules. So you cannot use this style of import unless its limited to 147 or earlier.
  • Now should be instantiated as a module in toml
  • This bug reported here: icosahedron example - newer versions will not run. examples#15 which includes links to potential solutions
  • Changing this means users could use three.js into the forseeable future.

• Simple slider panel

  • because it does not run (for me)

• KMeans in a panel

  • because it shows an error in the overlay - meaning the screen can't be seen or used by anyone running it
  • error is to do with threadpools (on my machine)

• matplot example

  • because it imports numpy but numpy is not mentioned in the toml or index.html file.
  • I assume this is because it is directly embedded in the pyodide being referenced.
  • From memory there is one more example which also does not import numpy but uses it. (I did not make a note - sorry :( )
  • There are other examples which do formally import numpy in the toml and are therefore better examples.
    • You can see them referenced in this PR by searching the page for numpy

I will update this PR to remove the 'simple clock' you have since removed so it doesn't reappear if this PR is accepted.

[Neon22]

If the examples are fixed - I would be very pleased to update this PR to meet your satisfaction.

[Neon22]

I'll check these later today - Thanks for doing this Andrea. I really appreciate it.

wrt the Kmeans demo

• its a nice demo of kmeans but I agree that this kind of demo with a fragile environment may not be the best demo to include in the examples.
• Maybe we could designate a "fragile" category, or we should replace it (and what its trying to show users) with another example which demonstrates the same things but using a less fragile example.
• This could be a task added to the community to maybe encourage them to make examples that illustrate various parts of pyscript that you decide should be illustrated ??
  • you/someone would need to identify aspects that should be illuminated by examples. Then people could make those.

[WebReflection]

imho we should improve somehow expectations, at least on PyScript .com side ... with that demo all I see is the inability for ourselves, or our users, to pin a config related dependency on both the Python and the browser side. I am sure it wouldn't be trivial to solve this issue, and we have a way to pin dependencies, but unfortunately that way doesn't necessarily play well with Pyodide registry (not their fault neither). Having a way to keep examples updated is one thing we should consider but having a way to help users keeping their own examples updated seem like a great goal too.

I will discuss this with @ntoll once he's back, but it's clear to me current strategy is not necessarily the best we could offer.

[Neon22]

my notes:

• Icosahderon

  • I will submit PR to this to also update the lighting so it looks better.
  • I hope that having this example included will prompt more three.js examples

• simple panel

  • I followed your link and it just shows a slider but nothing else.
  • Ahhh I think I understand. The slider IS the demo.
    • I guess I expected more than just a slider with a feedback value

• matplotlib

  • looks great

• kmeans

  • clicking on the plot does not filter but generates a bug.
  • The onscreen instruction indicates this should work
  • error is:

  PyodideTask exception was never retrieved
  

future: <PyodideTask finished name='Task-41' coro=<write() done,
defined at /lib/python3.12/site-packages/panel/io/pyodide.py:489> exception=Error:
NumberFormatter(p1053).text_align given invalid value: {"value":"left"}>

I will update my PR

[Neon22]

PR updated. Also added new PR to fix icosahedron example on pyscript-examples:

• update icosahedron examples#23

I.e. better lighting

[WebReflection]

Ahhh I think I understand. The slider IS the demo.

pretty much ... it's Simple for a reason 😁

PyodideTask exception was never retrieved

I have no idea about that example or the underling library but I wonder if updating all scripts to their latest version on the HTML side would just make it work. If it does, then we should likely also pin those versions in the TOML side of affair so that we won't have more surprises in the future.

[Neon22]

potentially missing examples (I guess this belongs on some other place ?)

• no micropython examples (all pyodide)
• no worker examples

Missing documentation on when to:

• just include a package in toml for python access and
• when you will need to also load it in index.html and
• when you can get away with only loading the javascript library in index.html and importing that via js
  • (e.g. D3 example does this)