Replies: 9 comments 11 replies
-
|
I tried to reorganize the namespace and the following reasons well to me: |
Beta Was this translation helpful? Give feedback.
-
|
Not sure if this is the kind of input you are looking for: Beacons beacon api
E.g. from pyweb import beacon
Beacon = beacon("url") # possibly define if sending txt or application/x-www-form-urlencoded
beacon_data = {"events":[]}
def action(event):
global beacon_data
beacon_data['events'].append("action")
def send_beacon()
global beacon_data
Beacon.send(beacon_data)
for b in beacon_data:
beacon_data[b] = []Note:
|
Beta Was this translation helpful? Give feedback.
-
|
One of the most important api's, for me, is the File System API To implement this we need to differentiate between:
There are also synchronous (e.g 'file.write()`) and async reader writer (e.g. blob, string, buffer) functions available. The synchronous ones are much faster on OPFS files and code could be easily migrated from traditional python style to operate on OPFS files efficiently. from pyscript import pyfsapi as fs
actual_inf = fs.choose_local_file(filettype=[".png", ".gif", ".jpeg", ".jpg"]) # shadowing Window.showOpenFilePicker()
in_file = fs.copy_opfs(actual_inf) # in_file is now on the OPFS for faster access
# usual file access python code style
with open(in_file) as inf:
...
# finished with file access
fs.save_opfs_to_local(in_file, actual_inf) # saved the OPFS file back to the local filesystemIt would be nice if there was a recipe/example which showed how to use a Worker to get the file and proxy it for you. And if this worker also had an option to clean up the OPFS file when it terminated (defaulting to True). So cleanup and exceptions for file not found were handled... |
Beta Was this translation helpful? Give feedback.
-
|
Chiming in explicitly, even if we discussed this in a couple of community calls already... I think @WebReflection comment above captures most of my preferences (as well as @mchilvers , iirc). A couple of small comments on the specifics though:
I do think we need to think about the future, when we add more simplified and pythonic versions of these APIs, to make access easier. For instance, what's in |
Beta Was this translation helpful? Give feedback.
-
|
not only that, I don't see any need for breaking anything we have right now ... I just did a round of "examples update" and every time we touch our namespace a lot of stuff breaks or need updates and if that's true for ourselves, it's even more true for anyone trusting this project in a mature enough state to build up next things ... and I fully agree with that statement, as moving around APIs (aka: shuffling cards of the same deck) doesn't help anyone to date and doesn't help us keeping docs and examples or internal state updated with greater ease, which is (imho) important. |
Beta Was this translation helpful? Give feedback.
-
|
Hi Folks, With all the work on
Most fall under option two. Those under option one have already been created elsewhere, or they're of fundamental importance. Those labelled with option three are simply "nice to have". Please don't hesitate to suggest more, or suggest changes to the API priority.
Assuming we're more-or-less aligned with attempting to create Pythonic versions of the capabilities listed above, our next task is to agree on the "pattern" of the API. For instance, in what consistent manner would we report certain capabilities are not available to users? How might these capabilities be organised into an easy-to-comprehend API taxonomy (see @WebReflection's suggestions)? Are there "refined" capabilities we may wish to reveal (for example, to turn on the phone's light, you'd have to use the Media API to access the camera to turn it on and off... a long winded process that we could hide in a As always folks, thoughts, constructive feedback and creative ideas are most welcome..! 🤗 |
Beta Was this translation helpful? Give feedback.
-
|
+1 on the proposal. I think the path we took with |
Beta Was this translation helpful? Give feedback.
-
|
Hi It's not in the list, I only saw WEBSERIAL Thanks in advance |
Beta Was this translation helpful? Give feedback.
-
|
Hi Folks, Following on from my earlier API list, here's a first stab at how the built-in APIs might line up in a As usual, this is a straw-man / first draft just so we're able to work out what we really want. NOTE Not all the features from the underlying web APIs may be made available... just the most fun/common/easy to use. Should folks require the "advanced" stuff, they can always work directly with the JavaScript APIs via our FFI. The details of such features can be figured out as we implement them. The point of this comment is to get us in the same ball park when it comes to the features / shape / naming of the API. It is important to remember, when it comes to the First off, what about our existing API..? Anything not explicitly referenced below remains the same. However, I really like some of @WebReflection's suggestions: I also think a bunch of stuff could find themselves in the I've already discussed this with @mchilvers - but Some of the existing functionality could be moved into a Given the recent work in #2239 the This leaves the following aspects of the existing API as-is: These feel to me (note the use of "feel" - this is an aesthetic judgement), like they're already in the right place because they're of their fundamental nature. Even if we move things around as described above, as part of the transition to the new API, we could alias alias things so they appear in the old location for a few released while folks move over. And so, we get to those aspects of the API that are dependent on whether the context is on the main thread or on a worker. I suggest simply calling a spade, "a spade" as the saying goes: Finally, there are aspects of our API that are not revealed in our docs, or are for internal use only. Following Python conventions, these should be renamed to start with an underscore: And so we come to the new API, drafted in the table below. The "done" column is a RAG status 🔴 🟡 🟢 and the issue# can be filled in as we create tickets/PRs for each feature. Of course, THIS IS A DRAFT / STRAW MAN for discussion purposes. A note on naming: Some of the APIs have their own top level in the API. I "feel" these are fundamental or the name fits. The
All feedback, creative ideas and constructive criticism most welcome..! |
Beta Was this translation helpful? Give feedback.
-
|
Hey hey. @WebReflection thanks for the feedback. 👍 on a dedicated call, and how this is a big subject. How about Wednesday for that? Just so we have a chance to at least show / discuss this in front of the community on Tuesday, and folks will know when the call will be..? I suggest we replace the community engagement call with a technical call about the API refactor? Thoughts..? WRT plurals and |
Beta Was this translation helpful? Give feedback.
-
I think I am OK with that, except I don't think any discussion should be made tomorrow around it, just a hint/notice we're going to discuss that in depth, so that such community can have a chance to read, digest, and eventually show up the day after with thoughts and/or hints. |
Beta Was this translation helpful? Give feedback.
-
|
Also food for thoughts (maybe) ... there's no difference in JS between imports and modules, imports are modules, that's it ... you import something once? every other import would be the same forever: imports are modules, so that second line really makes little sense to me right now. |
Beta Was this translation helpful? Give feedback.
-
|
👍 Agreed (notice of the discussion on Wednesday in the Tuesday meeting). Also, the JS naming conventions (imports/modules etc)... that's why we have discussions like this: to make sure it all makes sense. Like I said this ^^^ is just an initial brain-dump / first draft. We MUST refine it. 😉 |
Beta Was this translation helpful? Give feedback.
-
|
Sure thing, if I could get an understanding of the meaning of
That's it from me (around this initial topic), looking forward to the deeper discussion around the rest of it! |
Beta Was this translation helpful? Give feedback.
-
|
Looks good! I do wonder where things like the camera should go though? Is the playback/display of images/video/sound different to the recording of them? ie. pyscript.device.camera for recording videao/taking pictures? Not sure where the mic would live? pyscript.device.mic? The device then starts to feel cumbersome.... We could flatten even more and pull the device namespace out? pyscript.sensors etc.... Just some early morning ramblings.... |
Beta Was this translation helpful? Give feedback.
-
|
Yeah... I hear ya! I had a bit of a ponder about that... I started with a Anyway, I hope this explanation of my thought pattern that led to my naming makes sense. As always, I'm happy to change things around and discuss better ways to modelling this. The whole point of this comment isn't for me to say "that's how it is", rather, "it's a start, let's refine". 👍 |
Beta Was this translation helpful? Give feedback.
-
|
My summary for today meeting: About pyscript.js VS pyscript.pyUnless we have extremely specific use cases I don't think having a dedicated namespace would help. About pyscript.utilsI don't have any thought on those but most suggestions are there from legacy. About Eventspyscript.events.when
pyscript.events.EventI am OK with About most common used thingspyscript.config
pyscript.document
pyscript.ffi.*
pyscript.storage
pyscript.windowIt would be the third time we change the world ... meaning:
I am looking at the latter point: is this really fair for our users? Should we alias/deprecate whatever is in already somehow instead? About main/worker ideapyscript.main.PyWorker
pyscript.main.workers
pyscript.worker.syncThere is no My concern here is that we make the initial idea of workers, which was seamlessly portable code, beside Are we moving away from that initial idea? About dunder exportsI belkieved that was a Python convention so I wonder why we should care. About the table
|
Beta Was this translation helpful? Give feedback.
-
|
+1 on most of the above here but I have a question and a few comments... Question: @WebReflection , a lot of your comments seemed to indicate more work than just bringing these APIs, 1:1, to the python/pyscript layer. My understanding of where we aligned, was that for the most part, we are not looking at adding much work than just a 1:1 layer. The additional work to provide a Pythonic API on top of(or in addition to) that is going to be for a future phase. Comments: I does seem like we could trim some of that list down and wait on some of them to be requested. The deprecated ones are an easy pick, but also the ones that seem to be tricky and are likely less popular... we can probably wait.
+1 on
While I agree on keeping it YAGNI...... Given that most of these, at this stage, are going to be a thin layer API exposing the underlying JS api out of the box mostly dynamically, it shouldn't be that much work to add these... Given that, and the nature of some of these APIs, I'd rather just bite the bullet on this one (or on others, like battery for instance) because of the low cost of adding it. (Not strongly opposed to skip it for now though)
I think it's fine for me tbh.. |
Beta Was this translation helpful? Give feedback.
-
|
This is just kind of a goofy idea but I thought it might be helpful. If my memory serve me correctly and if i understand things currently (2 BIG IF HERE) pyscript is bassed on a plug-in. I would think that each plugin could have a name and source you load the plugin from you could allow import it to whatever you want this way. This would be similar to the way you import Javascript esm module . I would have the plugin name followed by the import name you want. This would allow you test 2 version of the same plugin. |
Beta Was this translation helpful? Give feedback.
-
In yesterday's community call we discussed the names in and structure of the API we provide in the
pyscriptnamespace. It is currently mostly flat and very crowded. Clearly we need to refactor and improve this "organically" grown situation.We feel it essential that we have community engagement in this process... so we have a fun challenge for you. Yes folks, it's the Great Pythonic API BakeOff, and you really will want to take part! ;-)
"How?", I hear you ask... well, my friend, it's easy... and it bears absolutely no resemblance to a famous cooking programme we like, but we had to think of something to grab your attention:
pyscriptAPI (see: https://docs.pyscript.net/2024.7.1/api/)pyscriptAPI in terms of names/structure.We'll collate the (reasonable and sensible :-P) responses we get and, sometime in September, share a "first draft" based upon the results. From this draft we hope to engage further with the community to make sure we have the most polished API possible. Then we'll ship it.
The existing browser APIs are, how can we put it?, colourful in their diversity.
We're looking for names that are easy to understand, a structure that is rational and understandable and ways of working that are consistent (for example, any asynchronous APIs are always awaited in Python).
For example, modern browsers include speech recognition (https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition) and text to speech (https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis). We could expose them in PyScript like this:
Clearly, in this example the intention is only to reveal the simplest / most common use cases. Bonus points for including "escape hatches" to more advanced / lower level APIs closer to the browser's own implementations.
Folks who have contributed to the final API that we eventually ship get their name immortalised in our release notes! :-)
So...
Ready?
Set?
Bake!
Beta Was this translation helpful? Give feedback.
All reactions