Using <script> tags to bootstrap pyscript #1326

WebReflection · 2023-03-29T12:30:32Z

WebReflection
Mar 29, 2023
Maintainer

I've demoed a quick PoC which uses <script> tags to bootstrap pyscript as opposite of using non visual related custom elements to do so, such as <py-script> and <py-config>, which differently form <py-repl>, <py-terminal> or others, don't really belong to the page as these don't represent any UI at all but, because these are defined as custom elements, can't neither bootstrap earlier on a page (i.e. within the <head> tag).

After the demo "100 questions were raised" so I've thought about creating a discussion instead to also hear some feedback from the pyscript community.

current status

We parse as toml some <py-config> element on the page and we are able to run Python code within <py-script> custom elements. Both elements require some special treatment in at least these areas:

the CSS must be inline on the page or it must reach a CDN (network request). Both can be problematic if somebody forgot the former practice, or the network request doesn't work as expected.
in case the CSS lands asynchronously by any mean, there is a risk of FOUC
because components are needed in the page, there might be issues related to layout semantics
because custom elements have no special rules around their HTML content, we both need to parse and sanitize their content before evaluating these as python code and if the CSS is not there these easily pollute the page

example

<!DOCTYPE html>
<div id="test"></div>
<py-script>
form js import document
document.querySelector('#test').textContent = "bumme<hr>!";
</py-script>

We can see the highlight in GitHub already believes that's just HTML and the browser would show this indeed:

py-script alternative

Non UI related element can break the parser in unexpected and undesired ways, while elements that are not sensible to CSS and that are meant to contain code (<script>) never get parsed internally as meaningful HTML by the browser (there's only one exception to this rule but that exception fails already in current <py-script> logic too).

On top of that, any <script type="..."> that is not recognized by the browser will do pretty much nothing: it won't block, it won't execute, it won't even reach the network if an src is present but the type is not standard.

Accordingly, the previous example that requires extra unnecessary work for the browser, could be instead written as such:

<!DOCTYPE html>
<div id="test"></div>
<script type="py-script">
form js import document
document.querySelector('#test').textContent = "bumme<hr>!";
</script>

note: see the highlight here knows that's just code, not HTML

This approach is also resistant to third party libraries that would otherwise involuntarily poison the content of generic elements on the page and not only because a script tag can be anywhere, including the head element, also because it would be super breaking/bad if third party changes the content of such script.

I hope overall benefits of this approach are clear by now, but I'd be happy to expand further if needed ... but let's see what are the options!

possible variants

<script type="pyscript"> works too, but it "steal" a potential type from the standards, so that similar custom-element naming convention seems to be more appropriate
<script type="text/x-python"> uses the correct python mime type, but it doesn't strictly hint pyscript about its nature
<script is="py-script" type="text/x-python"> uses custom elements builtin extends and represents the correct mime time. This is ideal and very correct for its purpose but:
- unfortunately Safari team doesn't want to hear about builtin extends, so that we'd need a polyfill for Safari which might not be ideal, or better, it puts burden on developers shoulders
- it's arguably way too verbose compared to <py-script>
<script type="py-script"> which seems to be (imho) the best compromise

py-config alternative

For the very same <py-script> reasons, the configuration as toml should not accidentally break the layout, be visible to users and it could be just in the <head> of any page, where a manifest (PWA), some configuration (importmap) or anything meant to bootstrap libraries and logic usually fit better (semantics).

possible variants

we could have a <script type="py-config"> that contains either JSON or toml to help bootstrapping pyscript on the page, and we should probably make this consistent with whatever we chose eventually for the py-script case
we could use our own namespace within the importmap, which would give us the following advantages:
- the content is meant to be valid JSON, so that IDE integration and sanitization comes out of the Web standards box
- we make it easier to integrate as JSON any importmap that has been generated by tools and automation of any kind

This latter idea is basically described as such:

<script type="importmap">
  {
    "py-script": {
      "plugins": ["numpy"]
    }
  }
</script>

Demo

This is more or less exactly what I've demoed as PoC so that you can get an idea of how everything works behind the scene.

The zip contains a pyscript folder where you can python -m http.server in it and see results on your browser of choice.
pyscript.zip

Final thoughts

First of all I want to make it clear that nothing in this proposal is mutually exclusive, or meant to replace current documentation and functionality, so that I am not proposing to remove those custom elements, I am proposing to migrate over time to something technically and practically better. However, if anyone is in favor of doing this ASAP instead and drop those bootstrap components, I would not oppose, but I don't think it's necessary, because both ways can coexist for a while and we can let developers decide which way is better/preferred or more robust.

tedpatrick · 2023-03-31T16:55:20Z

tedpatrick
Mar 31, 2023

I know that this proposal is counter to some historic decisions but I feel it deserves a strong review by the whole team.

Using script elements for code is the only way to prevent entity parsing for inline pyscript code. It also results in a simpler html document and is additive to our existing development model.

1 reply

WebReflection Mar 31, 2023
Maintainer Author

this recent bug speaks thousand words why I am pushing for this discussion to happen ... we're abusing the layout space to represent code and browsers aren't happy about it neither.

antocuni · 2023-03-31T22:34:04Z

antocuni
Mar 31, 2023
Maintainer

Thank you for re-opening this discussion @WebReflection!
As I told you during the zoom call, you opened a couple of can of worms here, and raised questions which have been already discussed several times. I hope that your experience with the web-related technologies can finally help us to find a "right" and definitive answer to those.

Before continuing, let me link to some of the previous discussions around these topics:
For <py-script> vs <script>:

[FEATURE] Use script tag instead of custom py-script #329
Correctly handle HTML entities inside <py-script> source code #735
Browser normalizes html tags inside <py-script> #857
in particular about the last issue, this comment and the subsequent responses: Browser normalizes html tags inside <py-script> #857 (comment)

For <py-config>, and in particular JSON vs TOML:

Better PyScript Application config #701
I think there are more discussions around, because for example I cannot find the one in which we finally decided to support both but keeping TOML as the default.

They are clearly related, but I think it's better to discuss them separately. I think that the choice of <py-script> vs <script> is more important and <py-config> should just follow naturally.

Before starting, I'd like to underline a a design principle which I have been following very strictly in my pyscript work and to which I don't want to renounce unless it's absolutely necessary:

errors/mistakes/typos should never be silently ignored. If our users (which in our aspiration could easily be non programmers or complete beginners) make a mistake, we should try hard to signal it and let them to fix it explicitly.

I know it is a big and tough one because it's basically the opposite of what the browser does by default.

Back <py-script> vs <script>.
TL;DR: I'm +0.75 to kill/deprecate <py-script> and use some form of <script>. Let's try to summarize PROs and CONs of each choice:
About <py-script>

PRO: it is the status quo
PRO: it is literally the name of the project. From a branding perspective, it is just "right"
PRO: if the user makes a typo (e.g. <py-scrpt>) the code is shown in the page. Although this is not a nice error message, it's at least a visual indication than something is wrong (much better than ignoring it completely). Note that this works even if the user completely forget to include pyscript.js.
PRO: it is very short to type. I am with @pzwang here, and he explained very well why "short and easy to type" is important.
CONs: all the ones described above :)

About <script>
6. PRO: It is the "correct" thing to do and solves lots of problems
7. PRO: it can be placed in <head>
8. PRO/CON: can be either "short and simple" or "long, complex and error prone"; more on this below
9. CON: if you mistype the type, it is ignored by default
10. CON: if you forget to include pyscript.js, there is nothing that we can do: it will be silently ignored
11. CON: It might be confusing because we cannot respect the normal order of execution than native <script> tags have. E.g.:

<script>console.log("1");</script>
<script type="py">js.console.log("3? Really?")</script>
<script>console.log("2")</script>

The reasons why I said +0.75 instead of +1 comes from points 1 and 2 (let's say they count -0.05) and most importantly 8-11 (let's say -0.20). Let's try to solve them:

to solve point 8, we should use something very short and simple; my preference is to <script py> (which can work using a MutationObserver as I described here). I might be happy also with <script type="py"> if the MutationObserver is too much of a hack
to solve point 9, we should introduce some logic to detect mistakes and display big red errors. This heuristic can be mild (e.g. detect and report only certain common typos) or hard and complain loudly if you find a <script> with any unknown type. If you really need <script type="my-awesome-language">, you should explicitly add it to a list of allowed types somewhere in <py-config>
points 10 and 11 are unsolvable I fear :(

14 replies

hoodmane Apr 2, 2023

This is somewhat off-topic, but think it would be good to encourage a similar one-<py-script>-tag style.

JeffersGlass Apr 2, 2023

This is somewhat off-topic, but think it would be good to encourage a similar one--tag style.

You may be opening up an entirely new can of worms 😛 - see the discussion in #895, in particular the py-notebook (as well as Fabio's Reponse and my-response). That said, my takeaway there is similar to what you're saying, I think: using one py-script tag where possible will make it easier for users to reason about execution order/namespaces/etc, but we should allow for and support multiple py-script tags for the reasons enumerated in that post.

hoodmane Apr 2, 2023

allow for and support

Right, I did said encourage nothing about forcing people =)

WebReflection Apr 3, 2023
Maintainer Author

On this topic, as I wrote in discord too, the following is also what happens as defined by standards:

<script>console.log(1);</script>
<script type="module">console.log(2);</script>
<script>console.log(3);</script>

the output will log 1 and 3, because script by default is a blocking JavaScript type, so that 2 will be logged when the different type module executes.

That is: you might get confused there too by reading 1 3 2 instead of 1 2 3 but that means people need to read why is that through documentation.

Bringing lack of better knowledge to justify worse practices is a bit of a controversial argument to me but beside that, knowing that if it's needed/desired to have a script that provides global callbacks to Python (not vice-versa as we need to bootstrap python anyway) what will always execute before our logic is rather a plus to me, than an issue.

WebReflection Apr 3, 2023
Maintainer Author

@JeffersGlass beside what I've just written, I'd like to underline a couple of things about what you said:

"<script> tags execute in order from the top of the document to the end, unless they have async or defer attributes, in which case they execute 'later'."

that's a misunderstanding of how defer and async work too ... there's no order guaranteed with async but most importantly a defer attribute with inline content and no src attribute does nothing different from a non deferred script: it just executes inline in a blocking way.

Once again, I come from JS and when I write Python I have tons of code and expectations (and errors) then I read more, I learn, and move forward ... not knowing how HTML and scirpt element works is the same as not knowing how any other element works ... it's not on us, but most importantly:

our instructions are literally "copy and past this thing called a Script Tag into your HTML document and then you can just start writing Python", you can see how that mental model would arise, and be good enough for a lot of circumstances.

This is exactly what anyone using PyScript does the first time: they copy & paste from our documentation and examples, so the risk of typos or the risk of surprises or the risk of misunderstanding seems to be non existent to me and, if anyone files an issue, we can improve the documentation around it.

A framework without documentation is usually bad so if there's any confusion on how PyScript gets bootstrapped it's because we haven't documented good enough how stuff works. Take Vue, React, any other popular framework and there are way more complicated things that surprise developers but they have excellent documentation, I hope we all agree on this and the fact that writing typos all over a HTML page is not really our fault and it's not caused by copy and paste scenarios unless we write typos in our non tested documentation.

WebReflection · 2023-04-01T08:40:56Z

WebReflection
Apr 1, 2023
Maintainer Author

@antocuni thank you for all the pointers and the summarized answer. There are a lot of interesting points I'd like to address right away but I want to take the time I need to read previous discussions and reply properly, like you've done already.

I have relatives visiting this WE though, so this will be done on Monday or late Sunday, just to provide an eta for my answer.

I hope this is OK, and thanks again for your time and thoughts 👍

0 replies

WebReflection · 2023-04-03T10:25:07Z

WebReflection
Apr 3, 2023
Maintainer Author

@antocuni once again, thanks for the links and background, it was worth for me to go through those so I can answer about all discussed topics and I'll try to go in order.

Before starting ...

errors/mistakes/typos should never be silently ignored

There are three pillars on the Web as we know and consume it:

HTML, which is sloppy and forgiving by design, a reason to be both loved and hated by FE/BE developers, also the reason the Web moved away from it via JSX, a strict XML dialect that won't let you do mistakes thanks to linters and editors/transformers. On this note, as we use linters and tests to verify what we write is correct, anyone could do the same for HTML plus many tools, indeed, already do that. The "curse" side of HTML being what it is in our case, is that non UI related elements present anywhere in the body of a document are parsed the way HTML parses it ... but I'll expand on this later, pointing at the discussions and bugs you mentioned.
CSS, which is forgiving by design because that's the only way to support both backward and forward compatibility out of the box, so that width: 100mvw; added after width: 100%; will work even in browsers that don't support new syntax or metrics to define a layout. This is the strength of CSS ability to fallback, then there is the case a CSS is fully malformed and it won't just apply, so that having zero notifications becomes indeed annoying, but then again linters and tools, or IDEs, will help developers. Similarly with HTML, CSS also parses our elements that have nothing to do with the UI of the page.
JS which breaks the world if not correct, the opposite of what HTML and CSS does, so that if you write a script you will definitively see errors, the line that caused it, the stack you can pause via debugger and so on. The JS fully represent your principles about errors never being silently ignored ... and it does it via the <script> tag which is the only place granted to not be parsed, to not interfere with the surrounding DOM, to provide a place for code data blocks so it's the right element for the job, where the job is to write code inside a Web page, simplifying also our job at describing errors in the right place without needing to explain entities VS non entities on the source code (among other issues explained further)

If our users ... make a mistake, we should try hard to signal it and let them to fix it explicitly.

We're not really trying hard here, we're just abusing a visual layout space that if it breaks could, or could not, show something that simply breaks the rest of the page. If we want to try hard helping our users, it's by documentation and code examples they can always safely copy and paste. Using the wrong element to represent code data blocks doesn't help anyone that is not understanding what is doing or what's going on.

Moreover:

a script that forgot a type will throw errors out of the box signaling the content is not valid JavaScript ... a misspelled <py-script> (as this is apparently the argument here) will not explicitly tell anyone that the element is wrong because we won't bootstrap it so we won't able to provide an explicit error of what is going or what's wrong. They will just see we don't know what on the page that no user should see so that errors here ends up on users, not developers, while using the right tools on the developers side will help developers and never surprise users.
a broken element on the page, able to destroy layout around because it cannot be placed anywhere, like <script> tag does, does not inform users what is going on, it shows something unexpected and fully breaks the page. In terms of production risks, having unintended code showed is a much worse UX and higher risk than having a page that doesn't work. In no Python UI framework you see python code within the production UI, you have eventually an error to debug, like it is for JS.
if we are so convinced a custom element on the DOM is the right place to put any sort of script, why nobody else out there is using <t-s> as custom element, shortest ever, hard to typo there, to define TypeScript content and parse it on the fly, but all solutions use <script type="text/typescript"> instead? Shouldn't we learn from previous work on these topics? (React JSX has the same, as well as many other runtime transformer ... all scripts for all the reasons I've already explained).

Last, but not least, using a code data block that always preserves line numbers and position of the chars in it (no entities shenanigans) allows us to implement in the future even a debugging mode with relative ease, because nothing in <script> is parsed.

it's basically the opposite of what the browser does by default

so why have we decided to fight against the browser internals, instead of using the only place the browser itself gives us as a safe place to write code data blocks?

Here my personal principles are more like: "if there are multiple ways of doing the same thing but one is better, always prefer the better one" (actually a citation of Douglas Crockford, inventor of JSON).

In this discussion it's not even about being better, it's about the correct way VS one way that's not meant to be and that already caused various bugs + it makes our parsing slower, it uses more CPU and RAM for no gain, it breaks layout with ease and it always leaks to CSS or query selectors on the page (3rd party scripts that do a query on the document and a <div>, or any innerHTML we do, is part of our <py-script> content will leak and cause potentially disasters to users' code too) ... so that <script> is implicitly more defensive out of the box too.

Here we have two options:

do the right thing and use the correct tag to write code
fix or explain over and over issues due new cases around entities, 3rd party libs, because we picked the wrong tool for the job (as somebody mentioned in other discussions ... bear with me ...)

About your `<py-script>` pros

it is the status quo

This is not really a pro, it's just the way it is, and we have tons of both old and new bugs due this status quo but fair enough: this is why we should migrate to the better solution the Web platform offers, the solution many before us used already successfully, without necessarily break current status quo.

it is literally the name of the project. From a branding perspective, it is just "right"

If branding is what we are after, and because any type="..." is allowed on every browser to date and every future browser (remember, strongest point of HTML5 is non-breaking backward compatibility) then let's sit on <script type="py-script"> as suggested, and preferred, in my examples (edit: I kinda like more <script type="py"> now ... the py-script brand is in there, and there's less to type!).

if the user makes a typo ...

I've lengthy answered to this point already but it's also fair to say that this is very subjective: I don't consider having undesired content on the page I wasn't meant to show, and that it's potentially breaking the page the user is seeing, an improved experience, while we could use Levenshtein distance to spot typos (on developer mode), although it feels completely unnecessary, while we should provide better copy and paste examples.

On top of this, I don't fully understand how this typo argument on py-script as type is different from writing <py-script> badly ... I mean, if we believe it's so easy to misspell our brand name maybe we should revisit the brand name? To me here it feels like we're obsessing over the container of what is actually a node full of python content, where every other typo in there matters most, and I'd love to see data around this argument ... like: how many people misspelled <py-script> to date and, if they did, how long did it take to figure out there was an error in the tag name?

If that's frequent, do we also agree that editors close initial tag automatically so that using <script type="shenanigan"> also is easier to fix while editing only the opening tag won't necessarily close it correctly and more errors will come on our repository?

Isn't it better if stuff just don't run so that they check the script that should run and think "oh ... what a typo, of course it did not run"???

it is very short to type

again ... what matters in this project is the content of the code data block ... this argument to me fails into the "let's use short variable names that means nothing, it's totally faster to type" ... can we really say 12 extra chars easy to copy and paste are the real issue for developers and users of this project? Do we have data around it? But I'll come back to this later ...

My review of previous discussions

On IANA, elements, and type discussion

I have been part of the NodeJS Module group and I could expand around IANA process, if needed, but basically that's just a way to map Mime Types to the browser, same way .mjs extension ended up as understood as application/javascript when the whole idea oh having disambiguation via Mime Type happened. IANA there was only to let Web developers point at .mjs files on the server without having the server failing at serving the right mime type for JavaScript, because indeed if we have a module and we try to import something.txt the browser will throw an error and never execute that content.

<!DOCTYPE html>
<script type="module">
  import "./notjs.txt";
</script>

In few words, the IANA part of that discussion is kinda unrelated to <script type="py-script"> because we don't need any IANA agreement there, we just use what <script type="text/typescript"> or others did already for the last X years: they use the unknown type to avoid blocking and parsing the <script> code data block.

Last on this, the correct mime-type for python is text/x-python as already mentioned in the <script is="py-script" type="text/x-python"> variant which is both the most correct thing to do and the most boring one ... so we can consciously ignore that approach.

Next topic here:

it fits idiomatically with the other tags/webcomponents that we have or will introduce, such as py-repl, py-env, py-data, etc.

Every custom elements based framework is composed by at least 3 parts:

the bootstrap (as script to import on the page to have the framework working ... see lit-element/a-frame/stencil/others)
the custom elements JS logic to handle the component state / behavior
the specialized markup / layout / UI and optionally its dedicated CSS part

Here we're instead moving the second point where it doesn't belong: the third specialized markup / UI one, so that while I fully and completely agree that py-repl and all other custom elements on the page should be registered as Custom Elements, I don't agree the JS equivalent code (Python) should be part of these components, and Server Side Rendering story is the same for most recent standards: nobody wants code as UI element, and the template doesn't usually use JS within it, it just represents the special UI component, or its Shadow DOM parts, not the logic to make such component work. Such logic is code, not layout, so it belongs to the only tag where code belongs: the <script> one. This tag has out of the box all convenient standards parts to handle properly any code as content so in the name of simplicity we're deciding to use the technical incorrect approach to deliver code, and issues keeps coming ... I mean ... if we had zero issues after May 2022 about this choice, because we demonstrated it's good to have code in the middle of the page, I would never raise this concern ... truth is, both those old issues and the recent one demonstrate we'll keep wasting time to offer support or fix something that shouldn't need fixing, if only we used the right tool for the job: code in scripts.

That means that here, where you say:

unless there are compelling technical reasons to do otherwise

there are indeed technical reasons <script> is the tag we should use to write code and tons of previous work on the Web that demonstrated already that works well for everyone, new comers included.

Last on this, it looks like nobody is considering our approach being future hostile for Python syntax too: if we don't chose the right tag to put in there literally any possible syntax any PL could come up in the future, we're looking for troubles if something like <>new Python template</> comes up in some version, while by using the right place to output any kind of code and syntax, we'll never have to worry about any of these kind of concerns.

Correctly handle HTML entities inside

This pointer simply demonstrates we have issues we shouldn't have, we need double parsing "hard to understand" that wouldn't be needed if we used <script> instead, plus the elephant in the room is that anything contained in current <py-script> python code can and will end up exposed (leaked) to every single library out there that parses generic content and produces different outcome: emoji, the recent MathJax library's bug, who knows what else ... do we really think explaining our users that because we made the choice of having python content, as if it was any generic element layout, can break every single library out there where simplicity also was their motto, so that everything as content get parsed out of the box for KISS sake?

In short: how do we make aware our users that every 3rd party library could break so that we play very badly with the rest of the Web ecosystem?

Browser normalizes html tags

Again, same soup here ... we decided to have issues by discarding the <script type="py-script"> correct way of placing python code on the page, but in that specific issue the problem is not even fully understood ... let me explain ...

Your solution is not really a solution for these reasons:

it blocks the page to ensure an early MutationObserver. Not only our code is not super light for a blocking external script, we don't get to know when our script is executed. A defer would already cause potential errors, so goes for async or even type="module".
the example you wrote assumes that MutationObserver performs a blocking synchronous callback. I think @tedpatrick answered about this already edit but to clarify, the MutationObserver is not granted to trigger synchronously, quite the opposite, it uses a queue to group a list of records at once with the callback
the user experience with that approach is horrendous on IDEs because these rightly handle by default any script tag as valid JavaScript ... seeing errors all over and ask our users to change their IDE is not the way forward ... look:

Now let's see with an unknown mime-type that power users could instrument to also highlight python instead, while custom elements don't usually have these kind of non-HTML-related hooks.

And not only this!!! With dedicated <script> we could provide directly syntax error, highlight, and so on, while with generic custom elements content the IDE would also complain about stuff unrelated to the DOM!

It doesn't matter how many dances we do at runtime (again slower, more code to maintain, future hostile) when the User Experience in editing HTML pages with <py-script> is much worse than having to copy and paste <script type="py"> or <script type="py-script"> ... can we all see that once we land on a different platform is much wiser to use that platform primitives instead of inventing our own primitive that won't ever play universally well?

And to conclude, as already mentioned, this highlighted comment breaks too because it's not using the right primitive to do exactly want we want to achieve.

I think I've written everything I needed to write, provided examples, visual examples, old, recent, and new possible bugs, and the whole discussion seems to be based on using something slightly less verbose as "pro users" ignoring completely how this approach backfires on these users too ... and as we're all developers, nobody can safe a new developers from committing typos at the beginning, but we could save them from undesired broken layouts, undesired scripts found in places no 3rd party library should deal with, undesired results out of document.querySelectorAll(...), undesired HTML editors errors around code nothing should parse out there, undesired side-effects when a greedy CSS library use !important to show descendant of a generic container, undesired FOUC if CSS doesn't land ... all of these undesired issues we need to tackle and explain in the name of 12 to max 14 extra chars to write when we know they'll instead just copy and paste?

I am sure we can agree to disagree, but to me the short argument doesn't outperform any of the mentioned issues for the present, the past, or the future of this project, and again, we ave the opportunity to roll this out in parallel, and start explaining our users, or convincing new users, that using the right tag for the job was indeed a technical need that brings a better experience to both them, ourselves, the browsers, and we Web standards we sit on when we execute python on the Web.

P.S. I won't discuss the JSON/toml argument because I agree we need to move forward on py-script tag first, otherwise it makes little sense.

2 replies

WebReflection Apr 3, 2023
Maintainer Author

I know it's already lengthy post but there's one specific part I'd like to be sure everyone understands:

a broken element on the page, able to destroy layout around because it cannot be placed anywhere ...

If we have a page with the following content which even ensures <py-script> is not visible:

<!DOCTYPE html>
<style>py-script{display:none;}</style>
<table>
  <tr>
    <td id="first-row"> some content </td>
  </tr>
  <py-script>
    print("the first <td> contains")
    print(js.document.getElementById("first-row").textContent)
  </py-script>
</table>

we have a broken page, no matter if CSS worked as expected:

by no mean we can fix this because the browser arbitrarily moves UI elements outside the place they don't belong to, and to explain this to our users we need to:

tell them that <py-script> is not really a <script> so that it cannot really be anywhere, it has to be in non breaking places (now explain all breaking place to help them out?)
tell them that there is no fix if not by moving the whole <py-script> element outside the table and bear in mind that won't fix that neither (keep reading)

Then we have the <script type="py"> equivalent:

<!DOCTYPE html>
<table>
  <tr>
    <td id="first-row"> some content </td>
  </tr>
  <script type="py">
    print("the first <td> contains")
    print(js.document.getElementById("first-row").textContent)
  </script>
</table>

And this is the result:

The summary of benefits here are:

no CSS needed ... nothing to explain about why CSS matters when it comes to <py-script> initialization ... easier on our users
the layout remains exactly as it was meant and defined ... the table doesn't have extra rows, the page is as clean as we wrote it
the content of the python code is preserved ... it's not broken and spread all over the page
there's nothing to explain to our users ... except, maybe, to be sure they don't write typos ...

If it's the killing reason against <py-script> we're after, this alone seals the deal to me, and there's no counter-argument I'd personally agree on about using a non code-data-block element to define code-data-block anywhere our users like to do so, without us having bugs, them having bugs and broken pages hard to resolve in every case, and frustration raised in all sides of the equation.

But to be extra clear why that particular example is problematic ... let's even move the py-script after that table:

<!DOCTYPE html>
<style>py-script{display:none;}</style>
<table>
  <tr>
    <td id="first-row"> some content </td>
  </tr>
</table>
<py-script>
  print("the first <td> contains")
  print(js.document.getElementById("first-row").textContent)
</py-script>

This is the resulting layout ... do you notice anything weird in there?

Can you see that print("the first <td> contains") has completely lost that <td> information because within HTML nobody can create a <td> (among other elements) out of a table context (only exception being template elements on purpose and for this exact reason)?

Are we still sure using a broken approach as defined by standards is the right choice, when we have a correct by-all-means one that has been working fine for 20+ years on the Web?

WebReflection Apr 3, 2023
Maintainer Author

quick extra on this note: we're exposing the DOM to Python via pyodide and we're asking our users to be careful about using innerHTML in it or be careful about what they put in their totally valid Python strings ... this seems like shooting ourselves on our feet to me but I am happy to understand how we can prevent or help users, in the name of <py-script> container tag's simplicity, to not seppuku themselves with their Python content (or the position of their script in the page).

WebReflection · 2023-04-03T12:50:20Z

WebReflection
Apr 3, 2023
Maintainer Author

Wrapping up arguments, this table's goal is to summarize what we need to explain to our users around the tag we ask them to use (please note that a few subjective points have not been included on purpose) :

	script type="py"	py-script
there are technical/standard reasons it's the best/only choice.	✅
it's a bit more verbose => more typo-prone (and we're sorry! but ...)	✅
it can, however, be copy-pasted with ease	✅	✅
it surely represents well the project "brand"		✅
it cannot be used anywhere (head/tables/other elements)		✅
it requires dedicated CSS to be invisible/layout irrelevant		✅
it can have CSS frameworks or libraries breaking due style overrides		✅
it can break the HTML layout with or witohut proper CSS already landed		✅
it could lose parts of the written/meant code due HTML parsing		✅
it could accidentally break with 3rd party libraries (emoji/MathJax/others)		✅
it might show HTML entities in source where none was meant in the code		✅
it might not provide HTML entities to python where entities were meant		✅
it's slower to parse and greedier on CPU/RAM due its layout based nature		✅
it's hostile by default for Web IDEs (wrong/broken highlights)		✅
it's harder to debug or it's not ideal due entities parsing indirection		✅
it's potentially future-hostile due possible new Python syntax		✅

I hope I haven't missed anything and beside the first two points, described well by MDN or other sites already, everything else is documentation we need to write and maintain, or issues filed to take care of, or fix, whenever that's even possible, make discussions with 3rd party libraries that should ignore our content by default, or users should find a way to avoid having their code destroyed, and so on.

I know this table might feel a bit "leady" toward <script> solution but honestly I believe the status quo cons overweight by far the only real pros argument which is shorter to type, because when it comes to simplicity, there's nothing simple to explain around all the ways the current approach could break, plus no obvious solutions neither due the way the HTML standard works.

0 replies

WebReflection · 2023-04-03T14:48:38Z

WebReflection
Apr 3, 2023
Maintainer Author

last after-thoughts for today: it looks to me that all previous decisions or discussions have been made to accommodate Python users that would like to use Python on the Web, and somehow don't know too much about the Web, but none of the decisions around this project have addressed Web developers that would also like to use Python on the Web ... the thing is that the former kind of user probably wants the easiest entry point to get started, but few chars more don't look like a real bummer (imho), and the latter kind of user will always complain about the current status quo (and related bugs) like it's been done in all the issues already linked within this post.

In short: wouldn't it be great if we could welcome both kind of users, those that don't know Web and also those that actually do know how the Web works and are totally interested in having Python available in there too? [1]

[1] I see myself in this picture, and I really like it!

0 replies

WebReflection · 2023-04-19T14:48:08Z

WebReflection
Apr 19, 2023
Maintainer Author

Quick update just to not forget about this discussion and keep some history around it ... @hoodmane got bitten by a test that was trying to represent SVG within a <py-script> tag ... he solved in a snap but the issue remains: if even we get bitten by the current status-quo around this choice of using a tag that gets parsed and breaks HTML documents, what are the chances our users won't also get bitten by it in the immediate to next/far future?

The solution was to avoid writing <circle ... or other SVG tags with a comment like "careful here, can't use less than sign!" which I personally find extremely hard to reason about, no matter how hard we might try.

If <script type="py"> would've been used instead, nobody could have, today or in the future, the same issue, resulting into indirections around the developer intent, which is "just write some SVG to format via Python" within a PyScript enabled content.

edit on top of that, our tests could be way more easy to reason about, without commenting every time that the intent was to write SVG or some HTML but <py-script> tag happened.

0 replies

WebReflection · 2023-04-27T15:53:39Z

WebReflection
Apr 27, 2023
Maintainer Author

This has landed #1396
and it's proven to solve long-standing issues when weird chars are meant as part of the text/content of the py-script component #1431 addressing all use cases presented in #735

We can re-open or re-visit or even drop the code as it landed in a completely non-breaking, non-changing mode, but to whoever was following this conversation, we have options now, it's up to us using these or not.

0 replies

Using <script> tags to bootstrap pyscript #1326

Uh oh!

Uh oh!

WebReflection Mar 29, 2023 Maintainer

current status

py-script alternative

possible variants

py-config alternative

possible variants

Demo

Final thoughts

Replies: 8 comments · 17 replies

Uh oh!

tedpatrick Mar 31, 2023

Uh oh!

WebReflection Mar 31, 2023 Maintainer Author

Uh oh!

antocuni Mar 31, 2023 Maintainer

Uh oh!

hoodmane Apr 2, 2023

Uh oh!

Uh oh!

JeffersGlass Apr 2, 2023

Uh oh!

hoodmane Apr 2, 2023

Uh oh!

Uh oh!

WebReflection Apr 3, 2023 Maintainer Author

Uh oh!

Uh oh!

WebReflection Apr 3, 2023 Maintainer Author

Uh oh!

WebReflection Apr 1, 2023 Maintainer Author

Uh oh!

Uh oh!

WebReflection Apr 3, 2023 Maintainer Author

Before starting ...

About your <py-script> pros

My review of previous discussions

On IANA, elements, and type discussion

Correctly handle HTML entities inside

Browser normalizes html tags

Uh oh!

Uh oh!

WebReflection Apr 3, 2023 Maintainer Author

Uh oh!

Uh oh!

WebReflection Apr 3, 2023 Maintainer Author

Uh oh!

Uh oh!

WebReflection Apr 3, 2023 Maintainer Author

Uh oh!

Uh oh!

WebReflection Apr 3, 2023 Maintainer Author

Uh oh!

Uh oh!

WebReflection Apr 19, 2023 Maintainer Author

Uh oh!

WebReflection Apr 27, 2023 Maintainer Author

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

WebReflection
Mar 29, 2023
Maintainer

Replies: 8 comments 17 replies

tedpatrick
Mar 31, 2023

WebReflection Mar 31, 2023
Maintainer Author

antocuni
Mar 31, 2023
Maintainer

WebReflection Apr 3, 2023
Maintainer Author

WebReflection Apr 3, 2023
Maintainer Author

WebReflection
Apr 1, 2023
Maintainer Author

WebReflection
Apr 3, 2023
Maintainer Author

About your `<py-script>` pros

WebReflection Apr 3, 2023
Maintainer Author

WebReflection Apr 3, 2023
Maintainer Author

WebReflection
Apr 3, 2023
Maintainer Author

WebReflection
Apr 3, 2023
Maintainer Author

WebReflection
Apr 19, 2023
Maintainer Author

WebReflection
Apr 27, 2023
Maintainer Author