pyscript / research Goto Github PK

View Code? Open in Web Editor NEW

1.0 1.0 1.0 16 KB

The PyScript R&D Repo - Experiments and proposals welcome

License: Apache License 2.0

HTML 56.28% Python 38.93% JavaScript 4.79%

research's Introduction

PyScript

What is PyScript

Summary

PyScript is a framework that allows users to create rich Python applications in the browser using HTML's interface and the power of Pyodide, MicroPython and WASM, and modern web technologies.

To get started see the Beginning PyScript tutorial.

For examples see here.

Other useful resources:

The official technical docs.
Our current Home Page on the web.
A free-to-use online editor for trying PyScript.
Our community Discord Channel, to keep in touch .

Every Tuesday at 15:30 UTC there is the PyScript Community Call on zoom, where we can talk about PyScript development in the open. Most of the maintainers regularly participate in the call, and everybody is welcome to join.

Every other Thursday at 16:00 UTC there is the PyScript FUN call: this is a call in which everybody is encouraged to show what they did with PyScript.

For more details on how to join the calls and up to date schedule, consult the official calendar:

Google calendar in UTC time;
iCal format.

Longer Version

PyScript is a meta project that aims to combine multiple open technologies into a framework that allows users to create sophisticated browser applications with Python. It integrates seamlessly with the way the DOM works in the browser and allows users to add Python logic in a way that feels natural both to web and Python developers.

Try PyScript

To try PyScript, import the appropriate pyscript files into the <head> tag of your html page:

<head>
    <link
        rel="stylesheet"
        href="https://pyscript.net/releases/2024.6.2/core.css"
    />
    <script
        type="module"
        src="https://pyscript.net/releases/2024.6.2/core.js"
    ></script>
</head>
<body>
    <script type="py" terminal>
        from pyscript import display
        display("Hello World!") # this goes to the DOM
        print("Hello terminal") # this goes to the terminal
    </script>
</body>

You can then use PyScript components in your html page. PyScript currently offers various ways of running Python code:

<script type="py">: can be used to define python code that is executable within the web page.
<script type="py" src="hello.py">: same as above, but the python source is fetched from the given URL.
<script type="py" terminal>: same as above, but also creates a terminal where to display stdout and stderr (e.g., the output of print()); input() does not work.
<script type="py" terminal worker>: run Python inside a web worker: the terminal is fully functional and input() works.
<py-script>: same as <script type="py">, but it is not recommended because if the code contains HTML tags, they could be parsed wrongly.
<script type="mpy">: same as above but use MicroPython instead of Python.

Check out the official docs for more detailed documentation.

How to Contribute

Read the contributing guide to learn about our development process, reporting bugs and improvements, creating issues and asking questions.

Check out the developing process documentation for more information on how to setup your development environment.

Governance

The PyScript organization governance is documented in a separate repository.

Release

To cut a new release of PyScript simply add a new release while remembering to write a comprehensive changelog. A GitHub action will kick in and ensure the release is described and deployed to a URL with the pattern: https://pyscript.net/releases/YYYY.M.v/ (year/month/version - as per our CalVer versioning scheme).

Then, the following three separate repositories need updating:

Documentation - Change the version.json file in the root of the directory and then node version-update.js.
Homepage - Ensure the version referenced in index.html is the latest version.
PSDC - Use discord or Anaconda Slack (if you work at Anaconda) to let the PSDC team know there's a new version, so they can update their project templates.

research's People

Contributors

Stargazers

Watchers

Forkers

msgpo

research's Issues

EVENT: Usability on handler's event argument

Some suggestions...

Optional?

The handler is currently defined with event=None. Looking at MDN, I don't believe None should be allowed. It appears the decorator has no real effect if event is None.

`event` -> `trigger`

Calling it event is going to make it seem like an instance of Event. HTMX uses htmx-trigger="click". Perhaps we could use trigger.

Positional vs. Keyword

I suggest the first argument (event type) is positional, everything else is keyword. The current zen of Python might be moving towards all-keyword.

Tooling-friendly contraint on event type

It sucks when you slightly misspell an event name. On the HTML/JS side, tools will warn you. Would be nice on the Python side.

We could do an Enum. I think Brett Cannon did a Twitter poll, not sure if people liked that.

We could instead do it on the type hinting side, with a union of Literal for each possible value. But perhaps we don't want this at all, for the (very rare) case of custom events.

EVENTS: def instead of DOMContentLoaded

Minor point...a recommendation from Jake at HTTP 203

Point being: use <script defer src="pyscript.js">

EVENTS: Does inline event handler body have to be valid JS?

A question about a constraint or non-constraint in this discussion. If non-constraint...I'll have another proposal.

First, a number of quite-cool ideas in Ted's proposal. MDN strongly recommends against inline event handlers. @handler(event_name, event_target) makes for something a lot more convenient than inline, so people will use it.

When people do use inline...for example in py-event_api.html:

<div py-mousemove="move">py-mousemove</div>

Does the attribute value -- move -- have to be a valid JS expression, pointing at a known symbol?

I think JS tooling doesn't really care, because JS (in browser) scopes are such a mess. Symbols can arrive async, so static analysis can never know.

I mean more "do we care"? Are we ok with saying: "Sure, your expectation is thatmove will exist in JS, but really, there's just this sort-of-anonymous proxy created by Python code via Pyodide".

I view the <button onclick="py.foo()"> as a bit more promising in this regard. There can be an actual py object in JS.

EVENT: Use a query selector for the element spec

In the proposal, you might write: @handler( event="mousemove", element=Element("empty_button").element )

Instead, I propose allowing element: Element | str. If it is a string, then use document.querySelector. This would have a few benefits:

It's nicer. 😀
It doesn't require evaluation at import time.
It could match multiple nodes and attach handlers to them.

EVENT: Optimizing the handler function registration

There's a lot of potential YAGNI below. If needed at all, unlikely to be needed any time soon.

When I was doing empty_button with mousemove event I thought: I bet my CPU is getting toasty. Lots of likely-expensive calls across the proxy. It made me think: we could put a wrapper on the JS side that did a little mediating before calling the registered proxy.

Debouncing

The decorator could have an optional value to set some debouncing policy.

Logging

When trying to figure out what's going on with events, this wrapper would provide a central place to collect info. Perhaps with a py-config knob.

Expression

I'm kinda proud of this one. Write a truth-y arrow function that gets run to determine whether to call the proxy.

Where to discuss each proposal/experiment?

First, apologies for my drive-by comment yesterday. I wasn't at computer and hadn't even cloned the code...should have been more deliberate!

Probably not best to discuss points on each proposal via a PR conversation. If we put here in issue, do we prefix each subject or use labels to map to each experiment?