Linted all the files

Tested all projects

Added a global README

Author: andreburgaud

brython/Makefile

@@ -0,0 +1,11 @@
+.PHONY: lint
+lint:
+	flake8 **/*.py
+
+.PHONY: fmt
+fmt:
+	black .
+
+.PHONY: diff
+diff:
+	black --diff .

brython/README.md

@@ -1,10 +1,121 @@
 # Brython Examples
 
-## Projects
+## async
 
-* github_install:
-* pip_install:
-* zero_install:
+* Project demonstrating how to use Brython asynchronous functions to request data from a server API.
+* In the following examples, the API is a simple text file that returns the text "Real Python"
+* To test the examples, execute a local web server in the respective directory
+* The recommended Python development server is started with: `python -m http.server`
 
+### aio
 
+* Demonstrates the usage of `browser.aio` the substitute to `asyncio` in Brython.
+* https://www.brython.info/static_doc/en/aio.html
 
+### ajax
+
+* Demonstrates the usage of `browser.ajax`.
+* https://www.brython.info/static_doc/en/ajax.html
+
+### fetch
+
+* Demonstrates the usage of JavaScript `fetch` from Brython.
+* https://www.brython.info/static_doc/en/ajax.html
+
+## base64
+
+Examples demonstrating how to access the DOM API starting from an app that takes a string as input, generates the base64 encoded value of the string, and displays it on the page. Each example is slightly different as stated in the following sections.
+
+### embed
+
+The application is a single `index.htm` with embedded Python code. It can be executed by opening the file with an internet browser. Starting a local web server is not required.
+
+The user enters the string to be encoded through the standard prompt message box of the browser.
+
+### form
+
+The application is an `index.html` with the Python code in a separate `main.py` file. Starting a local webserver is required (`python3 -m http.server`).
+
+The user enters the string in the HTML form of the main page.
+
+### sep
+
+This project is the same as `embed` but the Python code is a separate file, `main.py`. A separate Python file requires to start a local server to test this example (`python3 -m http.server`)
+
+### storage
+
+This example is an extension of the **form** project demonstrating how to use `localstorage` and save the data between page reload. It requires to start a local web server (`python3 -m http.server`).
+
+The data is saved as a JSON document associated with a single key of the local storage. The performance is degrading as you add more elements in the JSON file.
+
+### storate_perf
+
+In an attempt to overcome the performance issue of the `storage` example, this example saves each base64 encoded value into a separate key. The key is the original string entered by the user.
+
+## chrome_extensions
+
+### hello_js
+
+Example of a JavaScript Google Chrome extension.
+
+### hello_py
+
+Same example as hello_js using Brython.
+
+## console
+
+Brython console as an iframe embedded in an HTML file. Does not require to run a local web server. Opening `index.html` with a browser is sufficient to test it.
+
+## github_install
+
+`index.html` loading the Brython engine from GitHub. You can open the file directly. It only displays a message box with "Hello Real Python".
+
+## hashes
+
+In the same vein as the Base 64 encode application, this one generate the hash, SHA-1, SHA-256 or SHA-512, of a string. It adds a dropdown to select the desired algorithm (SHA-1, SHA-256, or SHA-512).
+
+This serves as the basis for a translation to the same application with Vue.js (see **vuejs** project below).
+
+It requires a local webserver.
+
+## import
+
+Shows how to import an external Python module. The external module is `functional.py`. The main Python code is embedded in the HTML page.
+
+It requires a local webserver.
+
+## import_js
+
+Expands on the `import` example by allowing the creation of `brython_module.js` generated with `brython-cli --modules`.
+
+This requires a Python virtual environment with Brython installed (`pip install brython`) to have `brython-cli` available in the PATH. The generated files are available in the sub-directory `dist_example`.
+
+You can open `dist_example/index.html` with a browser, without the need for a webserver to run locally, because the dependencies are only JS files (`brython.js` and `brython_modules.js`).
+
+## npm_install
+
+Example of a Brython project installed with `npm`. See the corresponding tutorial section for more details.
+
+## pip_install
+
+Example of a Brython project installed with `pip`. See the corresponding tutorial section for more details.
+
+## sha256
+
+Application to generate the SHA-256 hash of a given string. The data is stored as JSON in a key of the localstorage to preserver the calculations between page reloads.
+
+## vuejs
+
+Brython and Vue.js implementation of `hashes`. Requires a local webserver to be running.
+
+## wasm
+
+An example demonstrating the generation of a WASM file, the loading of the file, and usage of the function from Brython. The source code of the WASM file is Rust.
+
+This requires to have the Rust compiler installed on a local machine. Check the detail in the Brython tutorial. A local webserver is needed as it requires to load the wasm file.
+
+The web server can be started in the directory `wasm/op/web`. The debug wasm file is included. This is only for demonstration. The `add` function does not handle negative and big integers.
+
+## zero_install
+
+An example demonstrating a minimum Brython project. The Brython engine is fetched from a CDN, and the Python code is embedded on the page. No need for a local web server, no need for a local Python environment either, just a browser with JavaScript enabled :-)

brython/base64/form/main.py

@@ -3,22 +3,27 @@
 
 b64_map = {}
 
+
 def base64_compute(evt):
     value = document["text-src"].value
     if not value:
         alert("You need to enter a value")
         return
     if value in b64_map:
-        alert(f"The base64 value of '{value}' already exists: '{b64_map[value]}'")
+        alert(
+            f"The base64 value of '{value}' already exists: '{b64_map[value]}'"
+        )
         return
     b64data = base64.b64encode(value.encode()).decode()
     b64_map[value] = b64data
     display_map()
 
+
 def clear_map(evt):
     b64_map.clear()
     document["b64-display"].clear()
 
+
 def display_map():
     table = html.TABLE(Class="pure-table")
     table <= html.THEAD(html.TR(html.TH("Text") + html.TH("Base64")))
@@ -28,5 +33,6 @@ def display_map():
     base64_display <= table
     document["text-src"].value = ""
 
+
 document["submit"].bind("click", base64_compute)
-document["clear-btn"].bind("click", clear_map)
+document["clear-btn"].bind("click", clear_map)

brython/base64/sep/main.py

@@ -3,6 +3,7 @@
 
 b64_map = {}
 
+
 def base64_compute(evt):
     default = "Real Python"
     data = prompt("Enter a string:", default)
@@ -11,12 +12,14 @@ def base64_compute(evt):
     b64_map[data] = b64data
     display_map()
 
+
 def display_map():
-    table = html.TABLE(style={'border': '1 solid grey'})
+    table = html.TABLE(style={"border": "1 solid grey"})
     table <= html.TR(html.TH("Text") + html.TH("Base64"))
     table <= (html.TR(html.TD(key) + html.TD(b64_map[key])) for key in b64_map)
     base64_display = document["b64-display"]
     base64_display.clear()
     base64_display <= table
 
+
 document["b64-btn"].bind("click", base64_compute)

brython/base64/storage/main.py

@@ -2,33 +2,39 @@
 from browser.local_storage import storage
 import json, base64
 
+
 def load_data():
-    data = storage.get('b64data')
+    data = storage.get("b64data")
     if data:
         b64_map = json.loads(data)
     else:
-        storage['b64data'] = json.dumps({})
+        storage["b64data"] = json.dumps({})
         b64_map = {}
     return b64_map
 
+
 def base64_compute(evt):
     value = document["text-src"].value
     if not value:
         alert("You need to enter a value")
         return
     if value in b64_map:
-        alert(f"The base64 value of '{value}' already exists: '{b64_map[value]}'")
+        alert(
+            f"The base64 value of '{value}' already exists: '{b64_map[value]}'"
+        )
         return
     b64data = base64.b64encode(value.encode()).decode()
     b64_map[value] = b64data
-    storage['b64data'] = json.dumps(b64_map)
+    storage["b64data"] = json.dumps(b64_map)
     display_map()
 
+
 def clear_map(evt):
     b64_map.clear()
-    storage['b64data'] = json.dumps({})
+    storage["b64data"] = json.dumps({})
     document["b64-display"].clear()
 
+
 def display_map():
     if not b64_map:
         return
@@ -40,9 +46,8 @@ def display_map():
     base64_display <= table
     document["text-src"].value = ""
 
+
 b64_map = load_data()
 display_map()
 document["submit"].bind("click", base64_compute)
 document["clear-btn"].bind("click", clear_map)
-
-

brython/base64/storage_perf/main.py

@@ -2,15 +2,18 @@
 from browser.local_storage import storage
 import json, base64
 
+
 def load_data():
     b64_map = {}
     for key in storage.keys():
         b64_map[key] = storage.get(key)
     return b64_map
 
+
 def save_data(key, value):
     storage[key] = value
 
+
 def base64_compute(evt):
     key = document["text-src"].value
     if not key:
@@ -24,11 +27,13 @@ def base64_compute(evt):
     display_map()
     save_data(key, b64data)
 
+
 def clear_map(evt):
     b64_map.clear()
     storage.clear()
     document["b64-display"].clear()
 
+
 def display_map():
     if not b64_map:
         return
@@ -40,9 +45,8 @@ def display_map():
     base64_display <= table
     document["text-src"].value = ""
 
+
 b64_map = load_data()
 display_map()
 document["submit"].bind("click", base64_compute)
 document["clear-btn"].bind("click", clear_map)
-
-

brython/chrome_extensions/hello_py/popup.py

@@ -1,10 +1,12 @@
 from browser import document, prompt
 
+
 def hello(evt):
     default = "Real Python"
     name = prompt("Enter your name:", default)
     if not name:
         name = default
     document["hello"].innerHTML = f"Hello, {name}!"
 
+
 document["hello-btn"].bind("click", hello)

brython/hashes/main.py

@@ -1,12 +1,13 @@
-from browser import document, prompt, html, alert
-import json, hashlib
+from browser import document, html, alert
+import hashlib
 
 hashes = {
     "sha-1": hashlib.sha1,
     "sha-256": hashlib.sha256,
-    "sha-512": hashlib.sha512
+    "sha-512": hashlib.sha512,
 }
 
+
 def compute_hash(evt):
     value = document["text-src"].value
     if not value:
@@ -19,17 +20,12 @@ def compute_hash(evt):
     hex_value = hash_object.hexdigest()
     display_hash(hex_value)
 
-def clear_map(evt):
-    hash_map.clear()
-    storage[LOCAL_STORAGE] = json.dumps({})
-    document["hash-display"].clear()
 
 def display_hash(hex_value):
     text = html.P(hex_value)
     hash_display = document["hash-display"]
     hash_display.clear()
     hash_display <= text
 
-document["submit"].bind("click", compute_hash)
-
 
+document["submit"].bind("click", compute_hash)

brython/import/functional.py

@@ -2,6 +2,7 @@
 
 import itertools
 
+
 def take(n, iterable):
     "Return first n items of the iterable as a list"
     return list(itertools.islice(iterable, n))