Brython API vs JS API

[Denis Migdal]

Hi,

As you all know, Brython defines some classes, functions, and methods like "select()"/"select_one()"/"html.DIV"/"local_storage"/"session_storage".

However, I got really confused when I noticed that the JS API seems to work quite well in Brython : "querySelector"/"querySelectorAll"/"window.HTMLDivElement"/"window.localStorage"/etc.

First question : Is there a reason to use, in Brython, this Brython API instead of the JS API ?

EDIT: I think the answer is "Besides this standard interface, Brython propose an alternative interface, more familiar for Brython developers. It is described in the following pages"

https://brython.info/static_doc/en/dom_api.html

But is feels quite hidden at the end of a page (and I spent quite some time using Brython without noticing it xD). I think putting it in an "Alternative API" (or whatever) section in the documentation would be more clear (cf next question).

Second question : Could it be useful/possible to add some "tags" (or whatever) in the documentation to avoid confusions ? e.g. :

• [js] : things coming from the JS API (e.g. browser.window/browser.document ?).
  
• [core] : things added by Brython in order to use the "normal" JS API due to differences between JS and Python languages (e.g. aio).
• [alternative_api] : optional (?) alternative API that can be used to have a more "python-like" API (e.g. select, select_one, and bind ???)
• [helpers] : new features added by Brython, (e.g. browser.template, widgets)
  

TBF I even think modules should be renamed to avoid confusions in the source code (yeah I'm a radical extremist xD) :

• brython.core.XX
• brython.alternative_api.XXX
• brython.helpers.XXX

Rq1: there is ways to keep backward compatibilities by just depreciating old modules names, so with no impacts on old projects.
Rq2 : the alternative_api could also be in its own js file, thus enabling devs to include whatever they need in their webpages (?).

Third question : is there a way to import all JS global variables (window) into Python global variables, or to link the two ? Like making a kind of "from brower.window import *" ?

Forth question : why does JavaScript module contain "Date", "JSON", "Math", "RegExp", "String", "undefined", when they seem accessible from window ?

Fifth question : I personally find the documentation quite confusing at first (and my students as well last year xD), with lot of useful information in pages I didn't though to look at at first.

Could it be interesting to change the documentation menu structure to be more clear ? like : e.g.

• General
  • Intro
  • How it works
  • whatever
  • FAQ
    
• Using the standard API
  • document/windows/queryselector/addEventListener/ etc
• Using python features (or whatever)
  
  • asynchronous functions (aio/async/await)
  • time.sleep (setInterval/setTimeout/timer module)
    
• Alternative python-like API
  • select/bind/etc
    
• Helpers
  • templates/dialogs/etc
• Modules (?)
  
  • whatever
• Cookbooks
  

Rq1: Maybe using HTML5 details/summary in the documentation menu could be used to hide submenus ? It feels too much seeing all the pages at once when we start.

Rq2 : Maybe using a "page menu" at he right of the page (float:right) could help navigate the documentation as some pages can be quite long ?

I think I may one day create some slides on how to use Brython with the JS API for a 1-2h course (maybe in few months). I could share it if needed.

Cordially

[Ed]

Hi Denis,

I can't definitively answer your why questions, that would be for Pierre.  Perhaps I can help with other issues.

On Thu, Sep 28, 2023 at 10:17 AM Denis Migdal <denis....@gmail.com> wrote:

First question : Is there a reason to use, in Brython, this Brython API instead of the JS API ?

I think you got it: to be more pythonic.  I appreciate the brython APIs for html elements, DOM access, etc.  Personally I usually use the JS API for those things.  Two reasons for me:

1. Portability.  Brython is often great, but when resources are an issue sometimes it's too heavyweight (memory in particular).  If you're running a few Brython pages at a time, no problem.  If you run dozens of more at a time, the memory drain can become noticeable.  I tend to stick to JS API's so that porting brython scripts to compiled js scripts is easier when needed.
2. Documentation - there is tons of documentation on JS APIs like XMLHttpRequest out there.  Brython docs cover basic use cases well, but I find more advanced usage can sometimes be missing or hard to follow.

• Third question : is there a way to import all JS global variables (window) into Python global variables, or to link the two ? Like making a kind of "from brower.window import *" ?
  

I was going to suggest the old manual method: 

for x in dir (window) : globals () [x] = getattr (window, x, none)

But that doesn't work because window doesn't implement __dir__.  Instead you have to do this:

for x in window.Object.keys (window) : globals () [x] = getattr (window, x, none)

Not pretty but it works...

 

Forth question : why does JavaScript module contain "Date", "JSON", "Math", "RegExp", "String", "undefined", when they seem accessible from window ?

My guess is for clearer organization.  Window can hold anything: js objects, brython objects, some other language objects.  Window is a grab bag.

Javascript provides guaranteed access: if other code replaces window.Date, you can still access the original Date via javascript module.  I verified this in brython console:

>>> 

from browser import window as win

>>> win.Date

<Javascript object: [object Function]>

>>> win.Date = 2

>>> import javascript as js

>>> js.Date 

<Javascript object: [object Function]>

>>> win.Date

2

 

Fifth question : I personally find the documentation quite confusing at first (and my students as well last year xD), with lot of useful information in pages I didn't though to look at at first.

I find the documentation quite well organized and understandable.  I'm not saying you're wrong, it's a matter of personal taste.  Confusing to some can be logical to others.  In theory, docs can be organized multiple ways to reach different audiences.  In practice, that's a lot of work for a small project.  I don't know what to suggest.

Hope this helps,

Ed

[Denis Migdal]

On Thursday, September 28, 2023 at 7:50:44 PM UTC+2 Edward Elliott wrote:

I think you got it: to be more pythonic.  I appreciate the brython APIs for html elements, DOM access, etc.  Personally I usually use the JS API for those things.  Two reasons for me:

1. Portability.  Brython is often great, but when resources are an issue sometimes it's too heavyweight (memory in particular).  If you're running a few Brython pages at a time, no problem.  If you run dozens of more at a time, the memory drain can become noticeable.  I tend to stick to JS API's so that porting brython scripts to compiled js scripts is easier when needed.
2. Documentation - there is tons of documentation on JS APIs like XMLHttpRequest out there.  Brython docs cover basic use cases well, but I find more advanced usage can sometimes be missing or hard to follow.

Indeed. I think I will also use the JS API as much as possible as it'll enable my students to familiarize with JS API.

Context : half of my students have very short Web courses (5h lessons + 10h practical work to learn HTML/CSS/execution on the client-side/server-side) so I teach them Brython as they already know Python. Then half of them have more Web courses so I then switch to TypeScript.

But that doesn't work because window doesn't implement __dir__.  Instead you have to do this:

for x in window.Object.keys (window) : globals () [x] = getattr (window, x, none)

Not pretty but it works...

Maybe could be nice to have like an attribute `import-windows-globals="true/false"` (or whatever) on the script tag to do it magically ?

I had to adapt your code due to an "obj is null" error :
```python
g = globals()

for x in window.Object.keys(window):

if x in g:
continue

if x.startswith("on"):
continue

if x in ["opener", "frameElement", "InstallTrigger", "def_value"]:
continue

g[x] = getattr(window, x, None)
```

 

Forth question : why does JavaScript module contain "Date", "JSON", "Math", "RegExp", "String", "undefined", when they seem accessible from window ?

My guess is for clearer organization.  Window can hold anything: js objects, brython objects, some other language objects.  Window is a grab bag.

Javascript provides guaranteed access: if other code replaces window.Date, you can still access the original Date via javascript module.  I verified this in brython console:

I tested it by modifying it in JavaScript. Funny enough it causes errors in brython.js , but when importing javascript, I have the original Date/JSON/etc.

On one side other code should NOT modify it. On another side having protections is always good. On a third side, it is still a feature of JS and could be used to replace the original value with a proxy for some reasons.

Therefore I wonder what best practice would be : using the window or the javascript version ?

Also I tested, window.Date == javascript.Date returns False. Same for JSON.

 

Fifth question : I personally find the documentation quite confusing at first (and my students as well last year xD), with lot of useful information in pages I didn't though to look at at first.

I find the documentation quite well organized and understandable.  I'm not saying you're wrong, it's a matter of personal taste.  Confusing to some can be logical to others.  In theory, docs can be organized multiple ways to reach different audiences.  In practice, that's a lot of work for a small project.  I don't know what to suggest.

Hope this helps,

Ed

TBF, I was in a hurry (like we always are), i.e. with no time to patiently read the full documentation.

I started thinking the Python-like API was the way to do, and only discovered way later it may not be the case in a single phrase at the very end of a page xD.

E.g. I want to access an element, well I go directly to the "Accessing elements" in the menu, and here I only see get/select/select_one, with no indication it is in fact a page for the python-like API only (thus a tag [alternate API] at the top of the page could be useful, e.g. with a title attribute or a subtitle, or whatever "This page is for python-like API, you can still use JS API => link to another page or whatever").

In Introduction, in examples, etc. we only see the python-like API so it is easy to assume that is the way to go.

Without cheating I'm unable to remember and find the page where I found the phrase I cited in my first message.

Also I think there are some hidden pages not accessible from the menu, as well as pages only available in French (e.g. Promise).

[Edward Elliott]

On Thu, Sep 28, 2023 at 8:15 PM Denis Migdal <denis....@gmail.com> wrote:

Therefore I wonder what best practice would be : using the window or the javascript version ?

I think it highly depends on context.  If you want guaranteed behavior in your code, use javascript.*.  If you want to integrate with other scripts on the page and pickup possible changes to Date, RegExp, etc, use window.*.  Usually they're equivalent, especially when you control the server.  

If you do weird things like inject brython into other websites using a browser extension, then window could be anything.  Not an intended brython usage but it works well for me.

Also I tested, window.Date == javascript.Date returns False. Same for JSON.

Interesting, didn't expect that.

  

TBF, I was in a hurry (like we always are), i.e. with no time to patiently read the full documentation.

I started thinking the Python-like API was the way to do, and only discovered way later it may not be the case in a single phrase at the very end of a page xD.

In Introduction, in examples, etc. we only see the python-like API so it is easy to assume that is the way to go.

That is the preferred way.  Brython aims to provide a complete python environment in the browser, so you can do anything that js does purely in Brython.  JS access is meant more to interact with existing apps and libs.

[Pierre Quentel]

Le jeudi 28 septembre 2023 à 11:17:47 UTC+2, Denis Migdal a écrit :

Hi,

As you all know, Brython defines some classes, functions, and methods like "select()"/"select_one()"/"html.DIV"/"local_storage"/"session_storage".

However, I got really confused when I noticed that the JS API seems to work quite well in Brython : "querySelector"/"querySelectorAll"/"window.HTMLDivElement"/"window.localStorage"/etc.

First question : Is there a reason to use, in Brython, this Brython API instead of the JS API ?

Only answering a small part of the question : querySelector, HTMLDivElement, localStorage and the like are not "the JS API", it is the standard DOM API, which is language-independant. Javascript is described in its own section in the MDN documentation, and the DOM API in another one.

Brython supports the DOM API, and has its own specific API to make DOM interaction (hopefully) more intuitive for Python developers, and usually more concise (compare document[elt_id] to document.getElementById(elt_id)).

[Denis Migdal]

Edwart

> Brython aims to provide a complete python environment in the browser, so you can do anything that js does purely in Brython.  JS access is meant more to interact with existing apps and libs.

One issue we had last year is that one of my student tried to do something (I don't remember exactly what), and couldn't find it in Brython's doc.

Finally I think we stumbled across an hidden page that listed lot of properties for the object he wanted to manipulate. It really wasn't clear for us that we could so it the "normal way".

Therefore I really think it is important to better distinguish things in the documentation (DOM API, alternate API, core, etc). To help us understand what we are doing.

For example, I'm currently using aio.ajax, that requires brython_stdlib.js, but maybe using window.fetch I could get ride off this heavy dependency ?

Pierre

> Brython supports the DOM API, and has its own specific API to make DOM interaction (hopefully) more intuitive for Python developers, and usually more concise (compare document[elt_id] to document.getElementById(elt_id)).

Thanks for your answer.

I am a little curious, is there benchmarks somewhere to compare (in execution time and dependencies sizes) :

- pur JS code

- brython code with DOM API

- brython code with alternate API

- brython code with DOM API pre-converted into JS before execution

- brython code with alternate API pre-converted into JS before execution

     => could give the time to load the script (the download time (due to src=), the time to convert it, the time to execute it, the total time, and the total time - download time)

 

[If not, I could get a student to create one for a project. Gotta make good use of our little slaves xD]

I could also create 2 very simple (I'm not an expert on it) webpack loader for Brython :

- one that imports Brython code, that'd be converted on the Browser

- one that'd import and convert Brython code.

Could be quite useful to increase Brython's performances for the ones that need it (it would prevents LOT of HTTP queries for big projects) ?

[Denis Migdal]

I also saw that when we include brython.js and not brython_stdlib.js, the required elements are downloaded.

Could be nice if there could be a tool to get theses calls to see the required files, and then to build a personalize bundle.

Also, is there a very minimal brython.js file that wouldn't include any modules, so that we'd be able exactly all the used modules ?

I saw that our students projects starts in the second semester, I could try to suggest the benchmark and this as a project.

[Ed]

That tool exists.  See section Optimisation here:

https://brython.info/static_doc/en/import.html

--
You received this message because you are subscribed to the Google Groups "brython" group.
To unsubscribe from this group and stop receiving emails from it, send an email to brython+u...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/brython/16049d28-6dd3-4a5e-a9b2-fcfbfb1433e9n%40googlegroups.com.

[Denis Migdal]

Thanks, I'll look at it.

Else, I improved the import of window in the globals(). Instead of keys() we have to use getOwnPropertyNames() in order to also import classes.
Cf https://github.com/brython-dev/brython/issues/2248

[Ed]

On Sat, Sep 30, 2023 at 7:58 AM Denis Migdal <denis....@gmail.com> wrote:

One issue we had last year is that one of my student tried to do something (I don't remember exactly what), and couldn't find it in Brython's doc.

Finally I think we stumbled across an hidden page that listed lot of properties for the object he wanted to manipulate. It really wasn't clear for us that we could so it the "normal way".

I get where you're coming from.  I run across the same issues.  Not with Brython in particular, but page scripts in general.

Page scripts are endlessly frustrating no matter which platform you use.  All sorts of hidden gotchas in the DOM, event bubbles, callbacks, etc.  The web is really a terrible programming platform.  Unfortunately we're stuck with it.

For me, Brython goes a LONG way to easing the pain.  I wouldn't even consider doing half of what I do in JS.  Too painful fighting the language and the platform.  Brython gives me a beautiful language, so I only have to fight the platform. :)

Personally I find the Brython docs quite good.  They point me in the right direction, then I figure the rest out on my own.  That includes google searches and stackoverflow searches for solutions in JS.  The problems are usually issues with the DOM API, not with Brython itself.  Once I know that an event handler returning false isn't enough and needs to call event.preventDefault () as well, that's easy to translate to Brython.

I see where this approach may not be feasible for students just learning web programming.  I can't say how good the brython docs are for that audience.  Some level of js knowledge certainly helps.  Others on the list have talked about using brython with students, perhaps you can search the group archive for their thoughts.

Therefore I really think it is important to better distinguish things in the documentation (DOM API, alternate API, core, etc). To help us understand what we are doing.

I think you're approaching this in a peculiar way.  You have a special use case: students just learning web programming, half of whom move on to a more advanced course in a different language.  So your needs are rather different from most people using brython.

Most people (including me), when learning a new language / platform / API, don't want to be overloaded with implementation details.  I don't care that the DOM listener calls an Event bubbler that passes coordinate info to the parent node (or whatever).  I just wanna know how to click the damn button.  Tell me doc ['button_id'].bind (myfunc) and I'll go from there.  AKA the cookbook approach.

When intro docs go too deep into explanations and labeling, it gets tedious.  Especially when you're just learning the platform.

Detailed and precise docs obviously have a place.  Later on, you sometimes need that info to resolve a particular problem.  But that's why those are reference docs: you refer to them as needed.  Reference docs are terrible for learning a language / platform.

I don't have any official standing here.  Just a regular brython user like you.  Don't take what I say as brython's position.  Here's how I would approach it:

• For learning to use Brython, I think the current docs are pretty good.  Perfect, no.  Could be improved, sure, anything can.  But they follow the cookbook model well.   Here's something a user wants to do, here's code to make it happen.  I wouldn't start throwing extraneous detail in there about which APIs it uses and such.  That turns off most users.
• For more advanced usage, I can see where separate, reference docs could be useful.  Something that explains each approach and alternatives.  It's not hard to piece such things together on your own, but docs would certainly save time.
• Reference docs are a massive undertaking.  I would not ask Pierre to take away his time working on the brython platform to create reference docs.  That project is suitable for someone with large amounts of time and an endless supply of free labor.  Know anyone who fits that bill, hint hint? :)

For example, I'm currently using aio.ajax, that requires brython_stdlib.js, but maybe using window.fetch I could get ride off this heavy dependency ?

fetch, xmlhttprequest, aio.ajax - a pox on the whole lot.  Everything on the web is hopelessly complicated.  We've built mountains of interactive code on a shaky 30 year old stateless asynchronous foundation.  No matter what you do, there will be landslides.

Thanks for the interesting ideas.  I see value in your proposals, just not convinced you've hit the right approach yet.

[Denis Migdal]

> That tool exists.  See section Optimisation here:

>https://brython.info/static_doc/en/import.html

Thanks. It is indeed quite interesting. But it seems it works only to reduce brython_stdlib. I wonder if it'd be possible to do it also for brython.js to reduce it too ? For example brython.js contains browser.html, I wonder if we can not include it if we limit ourselves to the standard DOM API ?

Also I found very dangerous conversions in Brython between null/undefined and <javascript null>/<javascript undefined>/None (as well as a little bug on getters returning undefined) : cf https://github.com/brython-dev/brython/issues/2248

On Saturday, September 30, 2023 at 11:35:53 AM UTC+2 Edward Elliott wrote:

[Jonas O.]

Side question: it seems that occasionally, invalid python code causes brython to generate javascript errors and not python errors, and it becomes difficult to trace where the error comes from, since the browser unrolls a large stack of js that is difficult to read.

Is there a list of things that are known to generate JS errors instead of python errors? That would be helpful when getting JS errors, so I can be able to look for specific problem in my python code.

For example, are out of array bound or dict key errors known to generate JS errors?

To view this discussion on the web visit https://groups.google.com/d/msgid/brython/fbce161c-7bfe-457b-a8d0-866420dab268n%40googlegroups.com.

[Denis Migdal]

@Pierre : what do you think ? (cf below)

TBF I come from JS trying to use Brython. Therefore I don't have much issues with DOM API (except for very niche rules) xD.

> That includes google searches and stackoverflow searches for solutions in JS.  The problems are usually issues with the DOM API, not with Brython itself.

The issue is that in order to do that you first need to know :
- that you can use the whole DOM API in Brython (which is a very big deal).
- where the thing you are currently using is from :
   - the DOM API : I need to look at MDN doc
   - the alternate Brython API : I need to look Brython doc, or to swith to the DOM API if I want to do things not available in the alternate Brython API
   - the Brython core : I need to look the Brython doc + some adaptations I have to do on a Python code (e.g. aio for async).
   - the Brython helpers : I can only look at it in the Brython doc, and if I want to do something else I know there are not equivalent in the DOM API.

I think this are things all Brython developers needs to understand what they are doing, and where to look at things.

> Most people (including me), when learning a new language / platform / API, don't want to be overloaded with implementation details.  I don't care that the DOM listener calls an Event bubbler that passes coordinate info to the parent node (or whatever).

I didn't said to add implementation details to the doc.

>  I just wanna know how to click the damn button.  Tell me doc ['button_id'].bind (myfunc) and I'll go from there.  AKA the cookbook approach.

I understand. But when you'll want to do something not in the cookbook and not in the doc of browser.html, you won't know you can use the DOM API and look at the MDN doc. And you'll spend hours searching the doc, to discover months later there where a little hint in a sentence at the end of a page you didn't though was this important and didn't fully understood at first.

> When intro docs go too deep into explanations and labeling, it gets tedious.  Especially when you're just learning the platform.

I don't think it would be tedious to say :
1) Brython offers 2 API :
- Brython API : simple/python-like, recommended for python beginners. (link)
- DOM API : more complete, recommended for JS developpers. (link)
2) /!\ Some python features requires adaptations to work with Brython (link)
3) Brython also offers additional features, take a look at the doc ;)
4) We have some cookbooks (that could be separated in Brython API and DOM API cookbooks ?) (link).
=>Rq: I can write the DOM API cookbooks from the Brython API cookbooks if you are interested.

In the DOM API, ofc don't need to copy the MDN doc. Just say that you just need to import browser.windows, and EVERYTHING is accessible from it as windows is like the python globals(), i.e. contains all JS global symbols. Therefore you access and use the FULL JS API but in Python. Say that they can look at the MDN/W3C doc/tutorials/courses for more details about DOM/JS API (links), as well as :
- Could even give a function to import window content to the globals() in order to be even more JS-like.
- Need to explicit some conversions with null/undefined/None and other tricky stuffs that may arise.
- Just give an example, link to a JS/DOM API cookbook, and I think that's all that is needed.

In the Brython API, add that this is compatible with the DOM API. i.e. you can use both, the Brython to do simple stuffs, and then the DOM API to do more advanced stuff not implemented in the Brython API. Give an example and that's all. In html page, say that "(!) There is other functions from the JS/DOM API \o/, link for more".


The rest, is just moving existing pages into different categories to know what they are about (cf my first message).

> I wouldn't start throwing extraneous detail in there about which APIs it uses and such.  That turns off most users.

I don't think so, to the contrary.
If you have 2 types of cookbooks : "JS/DOM API" and "Brython API (recommended)", knowing there are 2 ways of doing it with one way being the recommended/preferred way, it would enable users to understand this fundamental thing : there is a more complete API if needed (the DOM API). It would also helps developers coming from JS to use Brython more easily, or for Python developers wanting to learn web devs to latter switch to JS, or for the one that want more perfs, etc.

Then in the documentation, just putting pages either in DOM-API or Brython-API categories would be enough (cf my first message). And would be very helpful as in case of issue they'd know where to search : MDN ? Brython doc ? etc.

> "That project is suitable for someone with large amounts of time and an endless supply of free labor.  Know anyone who fits that bill, hint hint? :)"

I have students, wink, wink xD.
Also I'm planning to make some slide before next (scholar) year

[Denis Migdal]

On Thursday, September 28, 2023 at 7:50:44 PM UTC+2 Edward Elliott wrote:

1. Portability.  Brython is often great, but when resources are an issue sometimes it's too heavyweight (memory in particular).  If you're running a few Brython pages at a time, no problem.  If you run dozens of more at a time, the memory drain can become noticeable.  I tend to stick to JS API's so that porting brython scripts to compiled js scripts is easier when needed.
   

I think I found the issue :

https://github.com/brython-dev/brython/issues/2249

I think this could reduce the memory usage manifold while increasing execution speed.

[Denis Migdal]

Honestly,

I have hard time on the documentation. Today I tried to include only one module in my distribution using the github repository (to have the current dev version).But information are scattered across ~5 pages, scattered in the menu : Installation / Deploying / Brython packages / Import / standard distribution.

Standard distribution would gain in readability by having a short list of folders with their usages, at the top of the page in order to better navigate (I think they are explained somewhere but I can't remember where).

Informations in Import page seems False/outdated :

• a module X in the standard distribution
  
• a file X.py in the root directory
  
• a file __init__.py in directory X

It is in fact :

1. $BRYTHON_DIR/Lib/{X}.py (for standard distribution)
   
2. $BRYTHON_DIR/libs/{X}.js (for standard distribution JS)
3. $CURRENT_DIR/{X}.py
4. $CURRENT_DIR/{X}/__init__.py
5. $BRYTHON_DIR/Lib/sites-packages/{X}.py
6. $BRYTHON_DIR/Lib/sites-packages/{X}/__init__.py

For optimisation, the only example is with brython-cli, when brython is installed through pip. But what if we downloaded Brython from github or another way ? Is this dependent on the Brython released registered in pip ? Or is it a separate tool/command when can use in any dir ?

In other pages brython-cli is also used. I think this tool should be introduced.

Therefore, I think it theses pages should be merged either in one page or in one set of pages (e.g. "Modules in Brython" ) :

1. Import (how it works)
2. Brython-cli tool presentation
3. Optimisation/
4. Distribution
5. Standard distribution
6. Contribute ? (I think there is a documentation page in the github with more details about the repository directories)
   

(Maybe 2-3-4 in the same page ?)

What do you think ?

I think I'll open an issue about the documentation some day.