pyscript: Examples should NOT point to /latest/

Currently, some of our examples are broken “out of the box”. For example, look at issue #654; to reproduce:

git clone git@github.com:pyscript/pyscript.git (at the time of writing, the latest commit is 2a59ff8)
open pyscript/example/simple_bioinformatics_tool.html directly in the browser, without doing make examples
observe that the buttons don’t respond.

This specific reproducer was broken by ee9b0960, which changed pys-onClick into py-onClick. After that commit, the examples work if you do make examples and run them using the locally built pyscript, but they don’t work with either pyscript.net/alpha or pyscript.net/latest.

The underlying fundamental problem is that we are trying to use examples/ in two contradictory ways:

as a tool to check that our code works. In this sense, for a given checkout we want examples to work with the pyscript version living in that checkout. This is what make examples and our CI is currently testing.
as an entry point for beginners to start playing with pyscript: in this sense, we would like that if you git clone pyscript and open a random HTML file, it will work out of the box; but to work out of the box, it must point to a globablly available pyscript version, which is what we have been trying to do by pointing them to pyscript.net/alpha/, /latest/ and/or /unstable/.

The two statements are contradictory because (1) points to a very precise and fixed-in-stone version of pyscript (the one corresponding to the given checkout) while (2) points to a variable version: for a given checkout, if I point the examples to /latest/ or /unstable/, maybe they will work today, but eventually they will break for sure. This is basically the equivalent of cloning the repository of a random python project and hope that the tests in the master branch pass against the latest released version on PyPI: sometimes they will, sometimes they won’t.

I think we already discussed IRL with @fpliger and we have two different opinions:

@fpliger would like people to be able to git clone the repo, open the examples in the browser, and play with them (Fabio, please correct me in case I am reporting your thoughts wrongly);
I think that keeping the dual nature of the examples is fundamentally impossible and will lead to inevitable confusion. So I would like to add some logic which actively prevents examples to be opened from a git checkout

If we really want to try to keep them working, the best we can do is to point the examples to /unstable/, which points to the latest published git commit. This ensures that if I do a git clone and immediately open the examples, they will work. However, this is a very partial solution, because it might happen the following:

I clone pyscript at commit N
at this point in time, pyscript/examples point to /unstable/ which is version N, and they work
a certain time T passes
someone merges a PR with an incompatible change, commit N+1
I open the examples: now /unstable/ points to version N+1, and my examples no longer work unless I git pull.

Of course, the more time passes in point (2), the higher is the possibility that someone merges a backwards-incompatible commit. If you are unlucky, it might happen only a few minutes, which makes it very confusing for beginners.

This is related to #624, which attempted to fix the problem, but now the examples point to /latest/ which is already incompatible with the current main.

/cc @marimeireles and @pww217

About this issue

Original URL
State: closed
Created 2 years ago
Comments: 22 (22 by maintainers)

Most upvoted comments

Aaaaaah, gotcha! I think we already had something like that because of cors but, if not, sounds like a plan!

Cheers!! 🍻🍻

fpliger on Aug 4, 2022

Overall agree with both @antocuni and @pww217 above. Only think we need to shave some edges on these parts of the proposal:

we add a small JS logic at the top of each file which checks whether they are being opened locally and warns the user in that case, explaining what’s going on and pointing them to the proper resources for “Getting started with PyScript”.

That’s a great proposal and we actually talked about this (or something very close) before. I think this should be an extension or something and not too custom to examples. This, actually, doesn’t need to be a part of “fixing” the current state and could be an enhancement issue on its own.

when we do a release, we run a CI which fixes the URL, removes the JS custom logic and push them to pyscript.net.

I think there is still value to keep the custom logic the walks the user through what’s going on in the example even when deployed on pyscript.net. That said, we can discuss that in a separate issue related to my comment above.

This is a good discussion, I think we are converging towards a better structure 😃

fpliger on Aug 4, 2022

My personal opinion is that examples should serve as display of the basic functionality of the latest released of the framework to end users. For this reason (in order):

the first goal is that they are displayed somewhere (today is in pyscript.net/examples) correctly and work [bonus points if the users can see the code that is generating that example]

they are tested and work when we release a new version (so that they work on pyscript.net)

They should not be considered the main source of testing but merely as smoke tests

The examples tests right now are basically just a quick and dirty way to mitigate our lack of tests, they are not the solution. The quality problem will only be solved when we add more tests.

I agree with all of the above. The point which IMHO causes troubles is this:

there’s value for people to just download and open a file to understand the example, without having to build

I agree it would be nice, but it causes more troubles than it solves. To start with, only the very simple examples work out of the box: all the examples which reference external files don’t work, so the hypotetical user will be very confused because half of them work and half don’t.

Moreover, as I explained above, there is a fundamental tension between the need of being “self consistent in the repo” (i.e., I expect the examples to work with the pyscript in the same checkout) and “work out of the box with an external URL which changes over time”.

Moreover, cloning the git repo is for developers, not casual users. I agree that we want some nice tutorial/getting started for people to start playing with pyscript, but it does not belong to the main pyscript repo, in the same way that python courses are not in the main CPython repo.

I propose the following:

the examples should point to a local url, like build/pyscript.js.
the main entry point for playing with them is make dev, which builds the local copy and starts a local webserver
we add a small JS logic at the top of each file which checks whether they are being opened locally and warns the user in that case, explaining what’s going on and pointing them to the proper resources for “Getting started with PyScript”.
when we do a release, we run a CI which fixes the URL, removes the JS custom logic and push them to pyscript.net.

This way, we are still friendly to the casual user which just open the HTML file, we ensure that examples pushed to pyscrpt.net always work, and we save a lot of headaches.

Should we move the examples to https://github.com/pyscript/pyscript-collective?

this might be a good idea. We could write that the main pyscript repo is ONLY for people who wants to modify pyscript itself, and that if you just want to play with it, you should clone pyscript-collective and start from the examples.

We may want to move some of the examples to the collective but i strongly believe that, as core team, should have a set of meaningful examples that serve our users and we guarantee will work on each release

as @marimeireles says, some of the examples like Mario don’t really belong to the main repo but I don’t have any strong opinion.

As I mentioned above, depends on the points of view and what we need. From the pyscript.net/examples point of view /latest is the only reliable build (and examples should be deployed there and aligned to latest when we release, not when we merge a PR). From the repository and testing point of view, local build (and eventually /unstable) is the only reliable source since is examples should be in sync with the source.

Yes I agree, but we can modify the URL when we publish to pyscript.net, there is no need to hardcode it in the git files.

antocuni on Aug 4, 2022

I think I agree with everything here. Just reiterating that some tests should be moved e.g the Mario one has too many dependencies and things we don’t really care about, it’s just hard to maintain (cause we’ll be maintaining other work that’s not relevant to pyscript).

marimeireles on Aug 4, 2022

Yeah, I’m slowly making progress on it! I hope to post something today by the end of the day.

marimeireles on Aug 3, 2022