I tried to reorganize the namespace and the following reasons well to me:

# proposal                # currently as pyscript.*pyscript.js.imports       # js_importspyscript.js.modules       # js_modulespyscript.py.imports       # py_import# I prefer .web over .netpyscript.web.Worker       # PyWorkerpyscript.web.Socket       # websocket.WebSocketpyscript.web.Storage      # storage.Storagepyscript.web.storage      # storage.storagepyscript.web.fetch        # fetch# it could be .web.ui toopyscript.ui               # web.*# not super sure ...# I feel like these# could be part of# pyscript.uipyscript.utils.HTML       # HTMLpyscript.utils.display    # displaypyscript.utils.when       # when

Not sure if this is the kind of input you are looking for:

Beacons

beacon api

• want to be able to signal a server with beacon info. E.g. memory use, length of time on page
• useful practice:
  • start a worker to gather data for the beacon,
  • occasionally send data to the worker to be recorded
  • send beacon and clear current store when instructed.
  • ensure that sent before worker destroyed. (Purpose of beacon API)
• useful sub api to support:
  • measure memory api -https://wicg.github.io/performance-measure-memory/
  • device memory API -https://developer.mozilla.org/en-US/docs/Web/API/Device_Memory_API

E.g.

frompywebimportbeaconBeacon=beacon("url")# possibly define if sending txt or application/x-www-form-urlencodedbeacon_data= {"events":[]}defaction(event):globalbeacon_databeacon_data['events'].append("action")defsend_beacon()globalbeacon_dataBeacon.send(beacon_data)forbinbeacon_data:beacon_data[b]= []

Note:

• beacons use type: "application/x-www-form-urlencoded" or text
• possible limited to 8kb
• return value is True if sent.
• can use return value to fallback to other older less reliable mechanisms.
• if implemented in a Worker then can make a recipe which does the job with fallbacks for default usage.

One of the most important api's, for me, is the File System API

• https://developer.mozilla.org/en-US/docs/Web/API/File_System_API

To implement this we need to differentiate between:

• the user's file system - directory and file handles
• the OPFS, an internal browser filesystem private to the origin of the page.
  • https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system
  • https://web.dev/articles/origin-private-file-system
  • the OPFS is much faster and is ideal for using for frequent access from within pyscript code.
  • an ideal api would enable reading a userfile into an OPFS file, a filehandle for that 'temp' file which the user then uses to operate on the file contents, and finally an interface to enable that OPFS file to be saved back to the user's file system.
  • This would enable efficient workflows where the pyscript code did significant work on a file in the browser.

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.

frompyscriptimportpyfsapiasfsactual_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 stylewithopen(in_file)asinf:    ...# finished with file accessfs.save_opfs_to_local(in_file,actual_inf)# saved the OPFS file back to the local filesystem

It 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...

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:

• ideally, we don't want nested imports too deep. Iirc, we said level 2 imports are the ideal goal (that's my preference and I think that reflects the general sentiment when discussed during the community call)
• I preferweb overnet as well. The risk I see withweb though is that it can be "too generic". Tbh though, can't think of a better option... (maybeio? But that also doesn't feel like a good fit forWorker)
• Agree thatHTML anddisplay seem a better fit underui

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 inui right now is not I consider the "final goal". It's more like foundation for us to give easier direct access to straight browser APIs and to build pythonic APIs on top of it in the future. I think the current proposal doesn't exclude that possibility but would be good to keep that in mind

Hi Folks,

With all the work onwhen,Event and other Pythonic machinery for revealing asynchronous APIs like those found in the browser, we're soon going to be ready to add such browser based APIs. As a result I've had a look on MDN (https://developer.mozilla.org/en-US/docs/Web/API) for currently supported browser APIs, and I propose the following "pick list" of capabilities/features/APIs to implement. I've prioritised them in three ways:

1. 🥇 priority (to be implemented first),
2. 🥈 must have (for initial version of our API),
3. 🥉 nice to have eventually.

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.

• Beacons 🥉 - a means of sending a non-blocking telemetry request to a remote server.
• BLE (web Bluetooth) 🥈 - something folks like Chris@Tufts would love to be able to use.
• Battery status 🥈 - helpful for folks running PyScript on a mobile device.
• Barcode detection 🥉 - again, helpful for mobile based developers.
• Clipboard 🥈 - a means of interacting with the OS's underlying clipboard buffer.
• Document picture-in-picture 🥉 - how YouTube does those floating video pop-outs as you scroll around the web page.
• Device orientation 🥈 - allows you to detect the device's orientation and detect device motion too. Useful for mobile PyScript users.
• File API 🥇 - access to the device's local file system.
• Fullscreen 🥈 - allows developers to put the app into full screen mode.
• Gamepads 🥈 - access and respond to signals from game controllers. Useful in educational contexts and to promote PyScript as a game authoring platform.
• Geolocation 🥇 - geolocation services.
• Idle detection 🥈 - useful for developers working in a mobile context, since this allows them to detect the user's attention (idle, active, locked etc...)
• MediaStream and (related)MediaRecording andMediaCapture/Streams 🥇 - record audio and video / capture a photo from a camera device.
• Notifications 🥈 - allow the PyScript app to send system notifications.
• Payment request 🥉 - payment and checkout via PyScript apps.
• Screen capture 🥉 - capture the whole, or a part thereof, of the screen as a media stream.
• Screen orientation 🥇 - provides information about the orientation of the screen. Useful for mobile PyScript users.
• Selection 🥈 - access and manipulate the part of the document selected by the user.
• Sensors 🥈 - lower level access to device sensors.
• Touch 🥈 - touch event support, great for PyScript on tablets/mobile.
• Vibration 🥈 - a fun capability for alert / signalling purposes. Especially good for PyScript on mobile.
• View transitions 🥈 - animated transitions between website views. Especially useful for single page apps (such as those generated by Invent).
• Virtual keyboard 🥉 - control the layout of applications when the on-screen virtual keyboard is activated. Useful for PyScript in mobile.
• Web Audio 🥇 - play sounds.
• Web speech 🥇 - text to speech and speech to text capabilities.
• Web Serial 🥈 - this would allow USB/serial connections to devices like the Lego Spike and the micro:bit. Very helpful for the chris@Tufts folks.

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 apyscript.light.toggle function 😄 )?

As always folks, thoughts, constructive feedback and creative ideas are most welcome..! 🤗

Hi Folks,

Following on from my earlier API list, here's a first stab at how the built-in APIs might line up in apyscript.FOO API taxonomy. The purpose is to reveal the underlying JavaScript/browser based APIs in a consistent, simple and Pythonic manner.

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 thepyscript.FOO namespace, we should allow ourselves to think of this as our Python3 moment ~ where we tidy up, reorganise, refactor and perhaps break things because of name/taxonomy reasons. Then we will be in a much better place (than a flat and crowded API) in which we can implement, refine and expand thepyscript Pythonic API we reveal to our users.

First off, what about our existing API..? Anything not explicitly referenced below remains the same. However, I really like some of@WebReflection's suggestions:

pyscript.js.importspyscript.js.modulespyscript.py.import

I also think a bunch of stuff could find themselves in thepyscrpit.utils namespace:

pyscript.utils.displaypyscript.utils.HTMLpyscript.utils.RUNNING_IN_WORKERpyscript.utils.current_target

I've already discussed this with@mchilvers - butpyscript.web sounds too generic, and so we're erring towards renaming this topyscript.dom.

Some of the existing functionality could be moved into apyscript.io namespace, which will be expanded with further new capabilities (see below).

pyscript.io.fetchpyscript.ui.WebSocket

Given the recent work in#2239 thewhen decorator will move:

pyscript.events.whenpyscript.events.Event

This leaves the following aspects of the existing API as-is:

pyscript.configpyscript.documentpyscript.ffi.*pyscript.storagepyscript.window

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:

pyscript.main.PyWorkerpyscript.main.workerspyscript.worker.sync

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:

pyscript._flattedpyscript._magic_jspyscript._media

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. Thepyscript.io namespace will grow to include several APIs that allow direct communication with outside-the-browser things. Thepyscript.screen name was chosen to avoid a clash with the existingpyscript.display. Thepyscript.device namespace is for capabilities relating to the host device/OS itself. All these names are up for discussion!

All feedback, creative ideas and constructive criticism most welcome..!

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....

My summary for today meeting:

About pyscript.js VS pyscript.py

Unless we have extremely specific use cases I don't think having a dedicated namespace would help.
In particular, I am looking atfrom pyscript import js easy conflict withimport js and a
way too genericfrom pyscript import py when we stress enough in our docs thatpy is notmpy.

About pyscript.utils

I don't have any thought on those but most suggestions are there fromlegacy.
Do we want to also keep legacy utilities around or could this be an opportunity to improve these?

About Events

pyscript.events.whenpyscript.events.Event

I am OK withEvent being there but ifwhen is a decorator able to deal with
not just events I am not sureevents is its best place.
Should be finish the@when story before deciding its namespace?

About most common used things

pyscript.configpyscript.documentpyscript.ffi.*pyscript.storagepyscript.window

It would be the third time we change the world ... meaning:

• we need to update every single documentation around those properties
• we need to update every single example if we want to keep examples updated
• we need to explain that there is zero added value in breaking what's working just because we decided to change the world again

I am looking at the latter point: is this really fair for our users?
I feel like in a good intent of providing the best we can we will just keep losing previous users in the making.

Should we alias/deprecate whatever is in already somehow instead?

About main/worker idea

pyscript.main.PyWorkerpyscript.main.workerspyscript.worker.sync

There is nopyscript.worker.sync on main and vice-versa, there is nopyscript.main.* in workers ... or should that be the case?

My concern here is that we make the initial idea of workers, which was seamlessly portable code, besideinput caveats or similar
that can possibly work only in workers, but code meant to run on main could be easily moved in a worker without touching the source.

Are we moving away from that initial idea?

About dunder exports

I belkieved that was a Python convention so I wonder why we should care.
I've been very careful to prefix stuff with_ when it was not meant to be imported or consumed
outside our core functionality ... am I doing it wrong? what's the best way to export only what we want to export?

About the table

• pyscript.io.files I am OK with it
• pyscript.location I amnot OK with it. It's description is about sensingdevice location
  andlocation as a name is already confusing on the Web duewindow.location ...
  • thedevice namespace it's proposed later on ... should this be moved in there?
  • what's wrong with a more verbose, yet explicit,geolocation name instead?
• pyscript.{sound,image.video} are better off within apyscript.media namespace, imho
• pyscript.screen.mode feelsYAGNI to me, until it's not ... we don't have many mobile users (AFAIK), we shouldn't decide now mobile browsers things
• pyscript.speech is fine but the speech API is not widely supported or cross browser ... there are tons of inconsistencies around it
• pyscript.io.bluetooth here be dragons ... the Bluetooth API is only a Chrome/ium thing and nowhere easy to deal with or debug ..
  it requires a lot of HW, ask Chris @ Tufts if you don't believe me
• pyscript.device.battery is part of theYAGNI to me at this point
• pyscript.clipboard feels OK as long as it's a module. If it's just a callback I am not sure
• pyscript.crypto feels right but be aware on JS side mostly everything is asynchronous when it comes to crypto: should we explore Python ways or are we OK with this?
• pyscript.device.orientation feels fine as long as it's an easy-peasy thing to deal with@when and not a new API to understand/document
• pyscript.screen.fullscreen requires explicit user actions, it's not something we can do out of the box ... is this a concern?
• pyscript.game.controller I think it's Chrome/ium only too
• pyscript.device.idle it's already easy to harakiri onrequestIdleCallback I am not sure what is this about or what's the use-case for it in our project
• pyscript.device.notify I am OK but it's a bumpy ride due poor mobile support
• pyscript.device.selection this feels more like atext related namespace ... this API is not straight forward to deal with, I'd like to understand use cases ...
  on mobile, people know how to select, copy and paste, out of their OS interface, on desktop is a right click away ... do we really need to interfere with primitives that
  already everyone knows and use daily?
• pyscript.device.sensors is Chrome/ium only
• pyscript.screen.touch is legacy ...pointerevents is what everyone uses these days and are superior ... we should re-think this because poiterevents make the usage
  of pointers related events independent so that you can have a mouse and a touch screen and both can work without changing code, not the same with touch
• pyscript.device.vibrate this requires user interaction (IIRC) not something we can decide out of the box
• pyscript.screen.transitions I am OK with this, we should make our users aware changing page though would re-load Pyodide (as example)
• pyscript.io.serial I think I've done this already and Tufts is using my module happily ever after ... should we just embed it?
• pyscript.io.beacon this is an awkward API because it doesn't grant anything and is not consistent across browsers ... this is also something usually done onlyonbeforeunload
  as event but there I wouldn't know how to make it more Pythonic
• pyscript.io.barcode Chrome/ium only (mostly) and full of gotchas ... I'd be OK in expliring it though
• pyscript.screen.overlay Chrome/ium only and nowhere on mobile
• pyscript.payment no Firefox and no WebView on Android ... I am still OK with this
• pyscript.screen.capture nowhere on mobile, not sure about use cases on Desktop as it's trivial to have a screenshot in there (Print on keyboard)
• pyscript.screen.keyboard Chrome/ium only and a weird thing as we don't get to know if the screen has touch capabilities AFAIK ... awkward to use with a mouse

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.pyscript.load_plugin("www.github/pyscript/sound.py&tag1. 0","pyscript. soundV1")
pyscript.load_plugin("www.github/pyscript/sound.py&tag2. 0","pyscript. soundV2")
you could also test some
of your current though on structure I could see it be useful and was not sure( that what discusión are for so i said to my self why not post it.)