Introduction to Brython

Brython is made to develop applications for the browser in Python. To enable it, the HTML page must have this structure : 
<html>
<head>
<script src="/brython.js"></script>
<script src="/brython_modules.js"></script>
</head>
<body onload="brython()">
<script type="text/python">
# python code here
</script>
</body>
</html>

brython.js is the Brython engine. brython_modules.js includes all the modules in the standard distribution.

The function brython(), defined in brython.js, is executed when the page has finished loading : it scans the Python scripts in the page, ie the code inside script tags with the attribute type="text/python", and runs them.

Here are a few examples of how you can use Brython to interact with a web page.

Initial content 

    
    browser is a Python-specific module that defines the objects used to interact with the page ; it is included in brython_modules.js. 

document is an object representing the HTML document ; document[element_id] is the element with attribute id equal to element_id.

Setting the attribute text of an element changes its text content.

bind() is a method that defines the function to call when an event occurs on the element. When the user clicks on the element, this event is called "click". The last line means : when the user clicks on the element (here, the button with the text "change the text of an element"), call the function change().
The function takes one element, an object representing the event.







    
    coloured content
    
    
    
    


    
    The attributes and methods of the elements are described in the Document Object Model (DOM), which is abundantly documented. One of these attributes is style, which itself has an attribute color used to set or get the color of the element.
    






    
    on / off
    
    

    


    
    display is another attribute of DOM elements. Setting it to "none" hides the element.
    





    
    
    

    


    
    alert is used to display small popup windows.
    
Note that here, since the callback function is short, it is defined in a lambda function.
    





    
    
    
    
    


    
    By default, print() writes message in the browser console window (to open it, do Ctrl+Maj+K on Firefox, Ctrl+Maj+J on Chrome, F12 on IE, etc).
    
Like in Python, the output can be reset by setting sys.stdout to an object with a method write().
    





    
    initial content
    
    

    


    
    To create DOM elements, Brython provides the module browser.html. It defines classes with the name of all the valid HTML tags in uppercase ; html.B("message") creates the element <B>message<B>
    
To include an element inside another one, Brython uses the operator <= : think of it as a left arrow, not as "inferior or equal". The use of an operator is more concise and avoids having to use a function call.
    
Since the elements supports all the standard DOM methods, you can also write element.appendChild(html.B(nb)).
    
    






    
    
    
    

    


    
    To build a table, we use the tags TABLE, TR, TH and TD. The first attribute passed to the classes defined in browser.html is either a string, another instance of a class, or an iterator on such elements. Here we use a Python generator expression to include several headers (TH) in the first row (TR) of the table, and the same for the table cells (TD) in the next rows.
    
clear() is a method that removes all the element contents.
    
    
    
    





    
    
    
    

    


    
    We start by importing the module math, the same as in the Python standard distribution.
    
Canvas allows drawing geometric forms in the page. There again you can easily find documentation and examples.
    





    
    
    
    





    
    Position of the International Space Station 
    
    

    


    
    The module browser.ajax allows sending Ajax calls, ie sending HTTP requests to a URL and handle the reply without having to reload the page. 
    
Here we use a public API that gives the current position of the International Space Station. The callback function complete() is called when the Ajax call has completed ; its argument has an attribute responseText, the response sent by the server. In this case, the API tells us that it's a JSON string. We decode it with the module json of the standard distribution.
    






Brython interacts with Javascript objects and libraries