DEV Community: JennaSys

Setting up Hot Reload with KivyMD

JennaSys — Tue, 02 Aug 2022 02:27:00 +0000

The KivyMD hot reload feature allows you to make changes to the Python code and kvlang files in your Kivy application and see the results in the running application without having to entirely stop and restart the application each time you make a change. Many other application development platforms support this type of feature, so it is nice to see it is available for developing Kivy/KivyMD applications as well.

But that said, I could not get it to work when I first tried using it. At the time, I was already in the middle of developing an application and didn't want to get side-tracked, so I put off enabling the hot reload feature for another time.

On my second try, I was determined to get it working with my now existing application. Several tutorials and videos are available for getting hot reloading set up with Kivy, but even with that I still struggled to make it functional. After reading documentation, digging into the code for the hot reload feature itself, watching a bunch of videos, reading several blog posts on the subject, and doing a lot of trial-and-error, I finally got it working. In the end, it really wasn't that difficult to set up, but there were some seemingly minor details that kept me from getting it set up correctly on the first try, and it took me longer to get working than it should have.

All that said, I'll document what I finally figured out here to hopefully help anyone who might fall into the same traps that I did. I'm going to assume that anyone reading this is already familiar with the basics of Kivy/KivyMD, so I won't go into much detail on general project setup. Instead, I will focus on just the specific changes that need to be made to enable the hot reload feature.

The Good (Key points for getting it to work)

The hot reload tool now built-in to KivyMD originated as a fork of Kaki. Many of the tutorials on using hot reload with Kivy that you may find are based on that library, but most of the content in them applies to the KivyMD tool as well.

Unlike the kaki Python library that automatically installs the dependencies it requires, with KivyMD you will need to pip install the watchdog library yourself if you use the KivyMD hot reload tool.

MDApp import

The first step in setting up your project for hot reloading, is to change where you import the MDApp Kivy application instance from. Typically, you would import MDApp using:

from kivymd.app import MDApp

but to use the hot reload feature, you need to instead import MDApp like this:

from kivymd.tools.hotreload.app import MDApp

MDApp.build_app() vs MDApp.build()

This is one of the significant points that I had originally missed. While Kivy and KivyMD normally use the build() method for initializing applications, the KivyMD hot reload tool (and Kaki) both instead use build_app() to perform that function. All of the tutorials I saw did indeed use build_app(), but that was a detail I had missed initially.

But even after I realized this, I still had questions. Did it replace the build() method, or was it in addition to the build() method? Through trial-and-error and digging into the source code, I determined that it essentially replaced the build() method that you would normally use. In fact, trying to override the App.build() method like you typically would, generally resulted in just an empty screen being displayed.

One side note about the build_app() method, the signature of that method is slightly different, and it needs to accept an argument in its definition that the normal build() method does not need:

def build_app(self, first=False):
    ...

Lastly, the build_app() method must also use the ScreenManager object as its return value.

DEBUG

DEBUG is a class property that determines if the running instance should use the hot reload feature. Almost every tutorial I saw insisted that you must start the application from the command line after setting this as an environment variable with DEBUG=1. Since I'm using PyCharm, I instead set it up as part of the run configuration for the project. What I didn't expect was that creating another run configuration with DEBUG=0 would still enable the hot reloading feature. Instead, I had to leave the DEBUG environment variable out of the non-debug run configuration altogether in order to actually disable hot reloading.

You also have the option of hard coding the DEBUG flag in your instance of MDApp, or reading it from a dotenv file and then dynamically setting it as well.

KV_FILES, KV_DIRS & CLASSES

Depending on how your project is set up and what you want the hot reload tool to watch, you need to populate these lists and/or dictionary as properties in your subclass implementation of MDApp:

KV_FILES: list[str]
A list of relative or fully qualified file names for each kv file that you want to watch:
```
KV_FILES = ["./View/LoginScreen/login_screen.kv"]
```
KV_DIRS: list[str]
A list of relative or fully qualified folder names for each directory containing kv files that you want to watch:
```
KV_DIRS = ["./View/LoginScreen"]
```
CLASSES: dict[str:str]
A dictionary of Python classes that you want to watch for changes. The dict key is the name of the class as a string, and the dict value is the module name as a string. For example, if you would normally import a particular class into a module, it might look like this:
```
from View.LoginScreen.login_screen import Login
```
To define an analogous CLASSES dictionary, you would create it like this:
```
CLASSES = {"Login": "View.LoginScreen.login_screen"}
```

Note that you do not need to populate all three properties. Just utilize the ones that make sense for how your project is organized, and for what you want to watch for changes that trigger the hot reload.

Summary

So, the tl;dr for enabling the KivyMD hot reload tool ends up being this:

Make sure the Python watchdog library is installed
Use the right MDApp class
Override the right build method
Set the DEBUG property
Populate the variables that tell hot reload what to watch for changes

The Bad (Dealing with maintenance hassles)

Now that hot loading is working, I still didn't care for having to manually add classes and kv file names in the code every time I changed or added something. It's a task that I'm sure I would repeatedly forget to do all the time. So, I added a few helper functions that would do that for me automatically at run time, eliminating the manual code maintenance.

I already had a simple helper function that I was using for loading kv files where I would pass in the name of a module, and it would load a kv file by the same name:

def load_kv(module_name):  
    Builder.load_file(f"{os.path.join(*module_name.split('.'))}.kv")

At the top of each view/screen module I created, I called this function, passing in the name of the current Python module:

load_kv(__name__)

Because the hot loader tool manages loading and unloading kv files itself, I no longer needed to load them myself. In fact, if I did, Kivy would give me warnings about the kv file being loaded multiple times. I happen to know about this because I have personally seen them myself. So I changed the helper function to add the kv file to the KV_FILES list instead of directly calling Builder.load_file():

def load_kv(module_name):
    app = MDApp.get_running_app()
    app.KV_FILES.append(f"{os.path.join(*module_name.split('.'))}.kv")

For the classes, I added a helper method to the sub-classed ScreenManager:

class SM(ScreenManager):  
    def get_classes(self):  
        return {screen.__class__.__name__: screen.__class__.__module__ for screen in self.screens}

It loops through the list of screens that have been added to the ScreenManager object using a dictionary comprehension, adding each {class: module} to the dictionary. Then in the build_app() method, I call the get_classes() method after instantiating the ScreenManager:

screen_manager = SM()  
CLASSES = screen_manager.get_classes()

With these two functions, I no longer have to do any manual editing in order to make sure any changes to the application are being watched by the hot reload tool.

The Ugly (Is it really worth it?)

State management on a hot reload can be tricky. When a screen reloads, it may lose its state. This is particularly true if you are relying on the UI to hold state, like text in a TextField widget. And then, non-UI state also needs to be considered. For example, what screen is currently being displayed, or whether the application is logged-in to a back-end REST server would need to be maintained. This may require you to rethink how state is updated and stored if you want to use hot reloading when developing your application.

One possible solution, is to manually reload state after a hot reload. There is a generic state object tied to the MDApp class as a property and an apply_state(state) method that gets called on every hot reload of the application. This method can be overridden to reapply any state that was lost due to the reload. However, as of right now, there is no hook implemented to give you a chance to save the application state before the hot reload starts.

To use these state management features, you basically need to serialize the state of your application to the MDApp.state object at the beginning of the rebuild process before the ScreenManager gets restarted, and then deserialize the state back to your application in the apply_state() method. For example:

class MainApp(MDApp):  
    DEBUG = True  
    sm = None  

    def build_app(self, first=False):  
        if self.sm is None:  
            self.state = {'current': 'one',  
                          'one': 'data one',  
                          'two': 'data two'}  
        else:  
            self.state = {'current': self.sm.current,  
                          'one': self.sm.get_screen('one').ids.data.text,  
                          'two': self.sm.get_screen('two').ids.data.text}  

        KV_FILES = []  
        self.sm = SM()  
        CLASSES = self.sm.get_classes()  

        return self.sm  

    def apply_state(self, state):  
        self.sm.current = state['current']  
        self.sm.get_screen('one').ids.data.text = state['one']  
        self.sm.get_screen('two').ids.data.text = state['two']

I got around the current lack of a pre-reload hook for state by keeping my own reference to the ScreenManager object as self.sm. I pull the current state from that just before instantiating a new ScreenManager and save it to the MDApp.state object to be retrieved later in the apply_state() method.

Conclusion

While the hot reloading feature is very convenient, I found that I had to modify my code in some ways that I wouldn’t otherwise have to, just to make it work well with hot reloading. In some cases, it made the code more complicated and subjectively less readable, in my opinion. Refactoring your code so that state is organized and well managed is obviously a good thing. However, there may be situations where it could also over-complicate what may otherwise be a simple application. So that said, while it’s a cool feature, hot reloading may not always be worth the hassle or extra tricks you have to do with the code to get it to work reliably and consistently.

Links to working KivyMD projects demonstrating the hot reload configuration are included below.

Resources

Kivy hot reload tool example code:
https://github.com/JennaSys/kivy_hotreload/tree/hotreload
Code for a more complete(ish) Kivy Project with hot reload enabled:
https://github.com/JennaSys/kivy_rest/tree/hot-reload
KivyMD Hot Reload Tool Documentation:
https://kivymd.readthedocs.io/en/latest/api/kivymd/tools/hotreload/app

Using Parcel v2 and Transcrypt to create web applications with Python

JennaSys — Mon, 07 Mar 2022 19:26:27 +0000

When the React to Python book was published, Parcel version 2 was just about to go into Beta. Because of that, it was still a bit too volatile to include in the book. But now that it is officially released, I thought I'd give those of you using Parcel as part of the toolchain I outlined in the book, a guide to using the newer version of Parcel.

There are definitely some new features available in the latest version of Parcel that makes switching to it worthwhile. To start with, the Parcel development server now supports server proxies, so you don't have to use an external proxy server to serve up your back-end REST services during the development process. On top of that, the tree shaking algorithm is much more efficient at eliminating unused code from the generated JavaScript bundle, making the deployment bundle smaller. Oh, and the builds are faster too! Running a production build on the project in Part III of the React to Python book resulted in a JavaScript bundle that was 30% smaller, and it took 15% less time to build.

The general steps to modify an application to move from using the original version of Parcel to Parcel v2 are covered in the Parcel v2 documentation. Here, we'll go through the migration requirements in a little more detail from the perspective of a Python web application that utilizes the Transcrypt Python-to-JavaScript transpiler.

Installation

The name of the NPM library for Parcel v2 has changed from parcel-bundler to parcel. So to install the Parcel v2 JavaScript library, use the following to install it as a development dependency:

$ npm install parcel --save-dev

A new recently released Parcel plugin for Transcrypt that works with Parcel v2 can be installed with:

$ npm install parcel-transformer-transcrypt --save-dev

Configuration

For Parcel to know about the Transcrypt plugin, we need to add a .parcelrc file in the same folder that the package.json file resides in:

Listing 1: .parcelrc

{
  "extends": ["@parcel/config-default"],
  "transformers": {
    "*.py": ["parcel-transformer-transcrypt"]
  }
}

This file tells Parcel that anytime it has a file with a .py extension, that it should pass the file on to the Transcrypt plugin for processing.

The Parcel CLI parameters have changed slightly compared to the previous version. So upgrading an existing project to Parcel v2 may require you to update your NPM scripts in the package.json file.

Most notably, the --log-level parameter now uses keywords instead of numbers, and the keyword for the output folder has changed from --out-dir to --dist-dir. New scripts may look something more like this:

  "scripts": {
    "start": "NODE_ENV=development parcel --log-level info src/index.html --dist-dir dist/dev --port 8080",
    "build": "NODE_ENV=production parcel build --log-level info src/index.html --no-source-maps --dist-dir dist/prod --no-cache"
  }

If you are using the Node.js require() function in your source code to load static resources like images, you may also need to let Parcel know where to find those resource files at bundling time. If the path to the transpiled JavaScript files are no longer located relative to the source file folder after building, add an "alias" entry to package.json:

  "alias": {
    "./static/**": "./src/static/$1"
  }

This entry will tell Parcel that for any files that are supposed to be in a static/ folder in the current directory, to look for them in the src/static/ folder instead (relative to the root project folder).

Plugin Options

The new Parcel plugin for Transcrypt works pretty much just like the one for the original version of Parcel, with a few additions. The key new features include:

A configurable output folder (when using Transcrypt 3.9)
The Parcel file watch works on all transpiled Python files in development mode and not just the entry point
It checks to make sure that the Python version matches the version of Transcrypt being used
It doesn’t need patching before using it :-)

Like the previous version, it has a default configuration that can be overridden with an entry in the package.json file for a project:

  "parcel-transformer-transcrypt": {
    "transcryptVersion": "3.9",
    "watchAllFiles": true,
    "command": "python -m transcrypt",
    "arguments": [
      "--nomin",
      "--map",
      "--verbose"
    ]
  }

The above configuration shows the default values that the Parcel Transcrypt plugin uses. The "transcryptVersion", "watchAllFiles", "command", and "arguments" keys are all optional. Default values are used for any keys that are not supplied.

If the watchAllFiles key is missing or set to true, all Python files that Transcrypt processes will be added to Parcel’s file watch. If this key is set to false, only the initial entry point file will be watched.

Transcrypt normally puts the files it generates in a folder called __target__, which is created in the same folder as the source files you are processing. This behavior may not be desirable if you prefer to keep your source code tree free of generated files.

By default, if you are using Transcrypt 3.9, the Parcel transformer will instead put Transcrypt's generated files in a folder named .build that is created in the project's root folder (where the package.json file resides and where you run npm commands from). You can override the location of this build folder by adding an argument to the above configuration as shown here:

    "arguments": [
      "--nomin",
      "--map",
      "--verbose",
      "--outdir src/__target__"  
    ]

The output folder you specify in the arguments should be relative to the project's root folder.

Note that the --outdir directive is not valid for Transcrypt version 3.7 and is ignored in that case.

Building a Python React demo application with Parcel v2 and the new Python plugin yields the following console output:

Proxy Server

One of the new features of Parcel v2 is the ability of its development server to act as a proxy for back-end data services like a REST API. So now, instead of having to roll your own proxy server with Express.js and the http-proxy-middleware packages, you can configure Parcel to provide the same capability with no additional plugins required.

To do so does require creating a simple .proxyrc JSON configuration file:

Listing 2: .proxyrc

{
  "/api": {
    "target": "http://localhost:8000/",
    "pathRewrite": {
      "^/api": ""
    }
  }
}

This configuration would forward any requests having a URL starting with /api to a backend server listening on port 8000, stripping off the /api prefix in the process. For example, a request to http://localhost:1234/api/getusers would be proxied to http://localhost:8000/getusers

Additional Details

The new version of Parcel does not automatically treat <script> tags as modules, so you must now explicitly specify them as such in order for imports to work correctly in a web browser. You can accomplish this by including a type="module" attribute in the <script> tag that loads the application entry point in the index.html file as shown below:

Listing 3: index.html

<!DOCTYPE html>
<html lang="en">
    <head>
        <script type="module" src="app.py"></script>
        <title>React to Python</title>
    </head>
    <body>
        <div id="root"></div>
    </body>
</html>

Most of the changes that need to be made when upgrading from Parcel v1 to Parcel v2 happen in the package.json file. In addition to what was mentioned above, you may have a line like this in your package.json file that was added by default when you ran npm init:

“main”: “index.js”

While that key was previously ignored in the older version of Parcel, the new version of Parcel will try and treat your web application as a library if it finds it there. To keep Parcel v2 from complaining, that line will need to be removed.

tl;dr

In summary, here are the basic changes needed when moving from Parcel v1 to Parcel v2 for Python web applications:

Add type="module" to entry point script tag in index.html
Add .parcelrc file to let Parcel know how to process .py files
Update package.json:
- Remove key entry for "main": "index.js" if it exists
- Update NPM scripts with new Parcel CLI parameters
- Add "alias" key for relative static imports if necessary
- Update "devDependencies":
  - Change parcel-bundler to parcel
  - Change parcel-plugin-transcrypt to parcel-transformer-transcrypt
  - Change parcel-plugin-bundle-visualiser to @parcel/reporter-bundle-analyzer
  - Remove express
  - Remove http-proxy-middleware
If using a proxy server:
- Add a .proxyrc file with the backend server configuration
- Delete dev-server.js and use npm start instead of npm run dev for development

Conclusion

One of the admittedly annoying pain points of using the toolchain I outlined in the React to Python book, was the fact that the Transcrypt plugin for Parcel was broken. And because the plugin was not being actively maintained, it had to be patched after installing it. With Parcel v2 and the new Transcrypt plugin developed for it, this is no longer the case. Developing web applications with Python is now even more seamless and productive than it was before.

Resources

Source Code:
https://github.com/JennaSys/rtp_demo/tree/parcel-v2
Parcel Website:
https://parceljs.org/
Parcel v2 Migration Documentation:
https://parceljs.org/getting-started/migration/
Parcel Plugin for Transcrypt:
https://www.npmjs.com/package/parcel-transformer-transcrypt
Creating React Applications with Python tutorial:
https://leanpub.com/rtptutorial
React to Python Book:
https://pyreact.com
Transcrypt Site:
https://www.transcrypt.org

Setting up a full-stack application on Replit

JennaSys — Mon, 31 Jan 2022 18:45:55 +0000

UPDATE: The two example repls linked below that I created are currently broken thanks to the forced automated update to Nix and not worth trying to fix at this point (I have nothing against Nix though). Quite frankly, Replit has become too slow, unstable, and poorly documented for me to justify using it anymore.

Thanks to a few programming tutorials I went through a while back, I was introduced to the Replit online development platform. More recently, I thought it would be an interesting exercise to see if I could use the Replit platform to host a development environment that I had been using for the Python-based approach to React development that I’ve adopted. I had outlined this approach in the React to Python book and picked a few examples from the book to use as my test cases.

While the Replit platform is pretty impressive, I went through quite a long learning curve in trying to figure out how to get all of the pieces I needed to use installed, configured, and running. In the end, I set up two separate repls using examples pulled right out of the book.

The first was for a front-end-only application and was pretty straightforward to get set up. But the second application was a full-stack example and proved to be a bit more challenging to get configured. Since it wasn't immediately obvious how to run multiple servers in a single Replit repl, I thought I'd document my solution here. While my development stack may be a bit different than most, the approach here would still apply to many situations.

Replit basics

Replit is kind of unique in the online development tool space since it provides you with many more options and more control over how you use it compared to most others I've seen. You can get it working with just about every programming language out there, and for the more common ones, they have templates to get you started quickly.

To create a new Replit project (or repl), you select an appropriate template like Python, TypeScript, Rust, etc., and then start adding your source files. If none of the available Replit templates are to your liking, you can also start with a Nix template that is essentially a blank slate to start building from.

One of the main features of Replit is that repls created on that platform are easily forked. This feature works much the same way as a public repository on GitHub might be forked. Except that instead of just getting a copy of the source code, you are also getting a copy of the entire development environment that was created for it. If your repl is public, even though your code is read-only to others, anyone can view it, fork it, and run it.

One last way Replit gives you to create a repl, is to pull the project source code and Replit configuration directly from a GitHub repository.

Within the Replit workspace, you have access to a file manager, code editor, Linux shell, Markdown viewer, and web browser window.

The basic setup

A typical full-stack web application will have a public-facing front-end web server and a back-end application server that is used by and/or proxied by the front-end server. In my case, I was using Flask as a back-end server that had a very simple REST API, and then I had the Parcel bundler development proxy-server for the front-end.

In addition to the servers, I also had a requirement to install and run a Python-to-JavaScript transpiler that is used in the build process. This transpiler worked in conjunction with the Parcel bundler I was using.

To automate setting up the development environment, I created a shell script that did the following:

Installed the specific version of Python that I needed to use
Installed Transcrypt (the Python-to-JavaScript transpiler)
Installed the JavaScript development and application dependencies for the project

I also created a shell script for starting the build process that will first check to make sure the required dependencies have been installed. If the dependencies are not installed, the build script will automatically run the setup script before running the npm start script that starts the development server.

Running two servers

If you know what you are looking for and where to look, the key to getting multiple servers working at the same time is in the Replit documentation. But even then, what is provided there isn't completely clear and kind of sidesteps this particular issue a bit.

An important key to getting the multi-server repl to work is understanding that the server started using a listening address of 0.0.0.0 becomes the public-facing web server, and starting another server listening on 127.0.0.1 keeps that server private.

When 0.0.0.0 is used, Replit accepts public requests to that server via one of its own publicly accessible IP addresses. In addition to that, it also automatically enables SSL. Regardless of what port your server is listening on, the public-facing server will be accessed via the standard SSL port (443). What this means is that, while you can use multiple ports for your internal servers, the public-facing server only accepts requests via the standard HTTPS port.

Now that we have the back-end/front-end ports figured out, the next issue is how do you run both servers simultaneously? Since both servers are blocking, you can't just chain start up commands, as the second server start command wouldn't execute until the first one ended.

One option is to fork the first command and run it in the background, allowing the second one to execute. While this works, you then don't have a convenient way of stopping the first command once you don't need it anymore.

To solve this issue, I used the npm-run-all package. This package allows you to run multiple npm scripts in parallel, and will exit out of all of them at the same time as well.

My npm scripts in the package.json file end up looking like this:



"scripts": {
  "start": "npm-run-all -p -r flask-dev parcel-dev",
  "flask-dev": "python main.py dev",
  "parcel-dev": "NODE_ENV=development parcel --log-level info src/index.html --dist-dir dist/dev --port 8080",
  "build": "NODE_ENV=production parcel build --log-level info src/index.html --no-source-maps --dist-dir dist/prod --no-cache"
},

Using npm-run-all, the npm start script then just calls two other scripts in parallel. By using the -r or --race option, the process started by each of those scripts will be shut down when one of the other processes exits.

To build or not to build

To run your application on Replit, there is a big shiny green Run button at the top of the Replit workspace. What this button actually does is defined by the Replit template used to create the repl, but it can also be customized in the .replit file.

While it could make sense to have this button start up your development server, it may not be optimal. Because of the way Replit works when someone else wants to view your application, they essentially click that same button. If your build process takes a while, they may give up on your application starting up before the build process finishes.

So to facilitate faster startups in this situation, I prefer to just serve up pre-built application files directly with Flask when the Run button is clicked, and perform the build process and running of the dev server from the command line instead.

However, that means that the Flask server must be started up listening on different ports depending on if it is acting as the full-stack server, or if it's only acting as the back-end server. To achieve this, I added a conditional startup for Flask that is dependent on the existence of a command-line argument dev when it is started.

main.py



...

if __name__ == "__main__":
    # Start up flask in proxied mode if using parcel dev server
    if len(sys.argv) > 1 and sys.argv[1] == 'dev':
        app.run(debug=True, host="127.0.0.1", port=8000)
    else: # Run public server
        app.run(debug=True, host="0.0.0.0", port=8000)

When Flask is started from the npm script as above:



"flask-dev": "python main.py dev"

it will use the 127.0.0.1 address. But when started using the Replit Run button, it is configured in the .replit file to call it without the additional argument:



run = "python main.py"

in which case it is started with the 0.0.0.0 address.

Conclusion

One general tip I can give for using Replit is to not fight their framework. Replit is opinionated in some of the tools they have pre-installed, and you are better off using what they have rather than ignoring them and just using what you may already be used to.

For example, in my case, I would typically set up a Python virtual environment using venv, and then pip install any Python dependencies I needed. When I first tried that on Replit, the results were inconsistent at best. When I went ahead and used the pre-installed Poetry package manager instead, everything went a lot smoother.

While setting up a full-stack application on Replit isn't too difficult, figuring out exactly what needs to be done may not be immediately apparent. Hopefully, my example here will give you some hints on how you might approach it.

Resources

Replit website:
https://replit.com
React to Python full-stack project source code:
https://github.com/JennaSys/replit_rtp_fullstack
React to Python full-stack example on Replit:
https://replit.com/@JennaSys/replitrtpfullstack
Parcel Bundler:
https://parceljs.org
Creating React Applications with Python tutorial:
https://leanpub.com/rtptutorial
React to Python Book:
https://pyreact.com

No-el: Eliminate explicit calls to createElement() when using Python to code React applications

JennaSys — Mon, 13 Dec 2021 03:12:57 +0000

For those of you that have been utilizing the approach to creating React applications with Python from the React to Python book, it may feel a bit kludgy having to call the React.createElement() function all of the time. But doing so is a necessity since JSX isn't a very practical option when using Transcrypt. Or perhaps having all of those el()'s littering your code just makes things look a bit messier than you would prefer. Well, I may have another option for you to try out that eliminates all of those createElement() calls, yet doesn't really change the way you've been writing your Python React code all that much.

Recently, a colleague was showing me some code they had written in Jetpack Compose for Web, a toolkit by JetBrains which is based on Google’s platform for building reactive user interfaces with Kotlin. It's not React, but it uses essentially the same paradigms as React. One of the features that stood out to me when I was looking at their code was that, unlike React, the native HTML components were represented as actual component functions. So, instead of creating React HTML elements like this as we have been doing in Python:

el('div', {'style': {'padding': '12px'}}, "Hello React!")

where the HTML element is represented as a string, Jetpack Compose for Web treats HTML elements as first-class citizens and uses something more like this:

Div({style {padding(12.px)} }) {Text("Hello Jetpack!")}

Seeing that got me thinking: "I wonder how difficult it would be to utilize that type of syntax in my own Python React projects?" Going into it, I knew that I would want to accomplish two things in this challenge:

Create wrapper functions for HTML elements so that React HTML components would be represented like any other functional React component.
Create a Python decorator that wraps component functions with the call to createElement().

Accomplishing these two goals would effectively eliminate the need to explicitly use createElement() calls for generating every React element in a component tree. Well, I'm happy to say that I accomplished both of those goals. And it turns out that it wasn't even that difficult to do (I really do love Python!).

The Code

If you recall from the React to Python book or the Creating React Applications with Python tutorial, a module called pyreact.py is created to hold all of the code that bridges Python objects to the React JavaScript library. It turns out that we only need to add a few more functions to this module to be able to eliminate all of the calls to createElement() in the rest of our Python code.

The heart of the entire solution is a single Python function that wraps a React component in a call to createElement() and returns that as a new function. It looks like this:

def react_component(component):  
    def react_element(props, *children):  
        return createElement(component, props, *children)  

    return react_element

If you have ever created a Python decorator, you may recognize the structure of this function. In general terms, it is a function that takes a function as an argument and then returns a new function. In this case, that returned function takes two (or more) arguments: props and zero or more children. The return value of the new function is just the call to React.createElement() that is used in the usual way.

We will use this function in two ways. Even though this function is structured like a decorator, there is nothing to keep us from also calling it directly. Thanks to the dynamic nature of Python, the component that we pass into this function doesn't even necessarily have to be a function. In fact, it can even be a string. This feature allows us to handle the first part of our challenge in turning React HTML elements into functional components :

Div = react_component('div')

The string 'div' that is passed into the function gets used as the first parameter in the call to createElement() in the generated function. This is just like we were previously using it in our own Python React code. We then save the return value of the call to react_component('div') in a variable called Div which now contains the newly generated wrapped function.

Putting all of this together, the additional code we end up adding to the updated pyreact.py module then looks like this:

def react_component(component):  
    def react_element(props, *children):  
        return createElement(component, props, *children)  

    return react_element

Form = react_component('form')  
Label = react_component('label')  
Input = react_component('input')  
Ol = react_component('ol')  
Li = react_component('li')  
Button = react_component('button')  
Div = react_component('div')  
Span = react_component('span')

As you can see, creating function wrappers for other React HTML elements becomes a trivial task. Now that we have that in place, we'll next take a look at how these new functions simplify the code we use to create our React applications by eliminating the need to explicitly call createElement() every time ourselves.

An Example

Starting with the React code from the tutorial, we add the necessary wrapper functions to pyreact.py as above and then refactor the demo application to remove the calls to createElement().

Listing 1: app.py

from pyreact import useState, render, react_component  
from pyreact import Form, Label, Input, Ol, Li  


@react_component  
def ListItems(props):  
    items = props['items']  
    return [Li({'key': item}, item) for item in items]  


def App():  
    newItem, setNewItem = useState("")  
    items, setItems = useState([])  

    def handleSubmit(event):  
        event.preventDefault()  
        # setItems(items.__add__(newItem))  
        setItems(items + [newItem])  # __:opov  
        setNewItem("")  

    def handleChange(event):  
        target = event['target']  
        setNewItem(target['value'])  

    return Form({'onSubmit': handleSubmit},  
                Label({'htmlFor': 'newItem'}, "New Item: "),  
                Input({'id': 'newItem',  
                       'onChange': handleChange,  
                       'value': newItem  
                       }  
                      ),  
                Input({'type': 'submit'}),  
                Ol(None,  
                   ListItems({'items': items})  
                   )  
                )  


render(App, None, 'root')

The first thing you may notice about this refactored code is that there are no calls to createElement() in sight! Removing all of those el()'s from the original version of app.py has cleaned up the code quite a bit.

Now that we're not basing the HTML components on strings, we do have to import the ones we use in the module as we did here.

from pyreact import Form, Label, Input, Ol, Li

In the import line above that one, we also imported the new react_component() function that we created in the pyreact.py module. Here, we now use this as a decorator for any React functional components that we create. When we do, they will also get wrapped by the call to createElement() when the component gets rendered by React.

@react_component  
def ListItems(props):  
    items = props['items']  
    return [Li({'key': item}, item) for item in items]

A side-benefit of using this decorator, is that it now becomes very easy to tell which of your Python function definitions are React components and which are just plain functions.

In this code block, you can also see the first use of our new HTML components that we use in place of the explicit call to createElement(). So instead of using

el('li', {'key': item}, item)

where the HTML element is identified by a string as we did before, we now use

Li({'key': item}, item)

where the HTML element is a functional component itself.

The other changes we made were all in the return statement that builds the component tree. Here, all of the calls to createElement() were replaced by their functional component counterparts. All of the props and the child component structure aspects remained exactly the same as they were before making the changes.

For instructions on preparing the development environment and running the code we discussed here, you can reference the original tutorial.

Conclusion

While it is definitely subjective, for me, calling React.createElement() when aliased as el() in my Python code is but a small concession for not having JSX available to use in the Python modules. In all honesty, it never really bothered me all that much. But for larger components, having all of those el()'s cluttering up the Python code can tend to impact readability a bit. By encapsulating the call to createElement() in the component itself, we can avoid having to explicitly call it in our Python code when building the element tree.

One drawback to eliminating the explicit calls to createElement() is that it might not be quite as evident as to what parts of your Python code are creating React elements versus just making regular function calls. Another possible downside might be that this encapsulation of the element creation could be seen as moving away from the mental model of how React actually works. These points are both very subjective, so you will have to decide for yourself if it makes sense to use what I've described here.

On the plus side, now that we've eliminated some of the createElement() code clutter, I feel that this approach makes it even less of an issue that we are not using JSX for creating React applications. Additionally, by using defined functions instead of strings for creating HTML components, the IDE is able to help us out a little bit better when coding.

Resources

Source Code:
https://github.com/JennaSys/rtp_demo/tree/no-el
Original Source Code:
https://github.com/JennaSys/rtp_demo
Transcrypt Site:
https://www.transcrypt.org
Jetpack Compose for Web:
https://compose-web.ui.pages.jetbrains.team
Creating React Applications with Python tutorial:
https://leanpub.com/rtptutorial
React to Python Book:
https://pyreact.com

Creating React Applications with Python

JennaSys — Mon, 21 Jun 2021 17:44:55 +0000

Full-Stack Python

Let me start by getting this out of the way: I really like programming in Python, and I'm not a big fan of JavaScript. But let’s face it, JavaScript is the way of the web, and Python doesn’t run in a web browser. So end of story, right? Well not so fast, because just like the popular TypeScript language gets transpiled into JavaScript to run in a web browser, Transcrypt does the same thing for Python.

Because of the way Transcrypt maps Python data types and language constructs to JavaScript, your Python code is able to utilize the full ecosystem of JavaScript libraries that exist. Transcrypt acts as a bridge that enables you to take advantage of existing JavaScript web application technologies rather than trying to reinvent them. And, it does it in a way that doesn't significantly affect application performance over using plain JavaScript, or that requires a large runtime module to be downloaded to the client. And though we use JavaScript libraries, we don't have to code in JavaScript to use their APIs.

Features of Transcrypt include:

It's PIP installable
Python code is transpiled to JavaScript before being deployed
It uses a very small JavaScript runtime (~40K)
It can generate sourcemaps for troubleshooting Python in the browser
The generated JavaScript is human-readable
The generated JavaScript can be minified
Performance is comparable to native JavaScript
It maps Python data types and language constructs to JavaScript
It acts as a bridge between the Python and JavaScript worlds
It supports almost all Python built-ins and language constructs
It only has limited support for the Python standard library
Your Python code can “directly” call JavaScript functions
Native JavaScript can call your Python functions
It only supports 3rd party Python libraries that are pure Python

npm instead of pip

Most Python language constructs and built-ins have been implemented in Transcrypt, so working with standard Python objects like lists, dictionaries, strings, and more will feel just like Python should. Generally speaking however, third-party Python libraries are not supported unless the library (and its dependencies) are pure Python.

What this means is that instead of turning to urllib or the requests library when you need to make an HTTP request from your web browser application, you would utilize window.fetch() or the JavaScript axios library instead. But you would still code to those JavaScript libraries using Python.

Installation

Getting started with Transcrypt is pretty easy. Ideally, you would want to create a Python virtual environment for your project, activate it, and then use PIP to install Transcrypt. Transcrypt currently supports Python 3.9 or Python 3.7 so you will need to create your virtual environment with one of those versions, and then install the appropriate version of Transcrypt:

$ python3.9 -m venv venv
or
$ python3.7 -m venv venv

$ source venv/bin/activate
(for Windows use venv\Scripts\activate )

(venv) $ pip install transcrypt==3.9
or
(venv) $ pip install transcrypt==3.7.16

Hello World

With Transcrypt installed, we can try a simple Hello World web application to see how it works. We'll create two files: a Python file with a few functions, and an HTML file that we will open up in a web browser:

Listing 1: hello.py



def say_hello():
    document.getElementById('destination').innerHTML = "Hello World!"

def clear_it():
    document.getElementById('destination').innerHTML = ""

Listing 2: hello.html



<!DOCTYPE html>
<html lang="en">
    <body>
        <script type="module">
            import {say_hello, clear_it} from "./__target__/hello.js";
            document.getElementById("sayBtn").onclick = say_hello;
            document.getElementById("clearBtn").onclick = clear_it;
        </script>
        <button type="button" id="sayBtn">Click Me!</button>
        <button type="button" id="clearBtn">Clear</button>
        <div id="destination"></div>
    </body>
</html>

We then transpile the Python file with the Transcrypt CLI:

(venv) $ transcrypt --nomin --map hello

Here, we passed the transcrypt command three arguments:

--nomin turns off minification to leave the generated code in a human-readable format
--map generates sourcemaps for debugging Python code in the web browser
hello is the name of python module to transpile

We can serve up the Hello World application using the built-in Python HTTP server:

(venv) $ python -m http.server

This starts up a webserver that serves up files in the current directory, from which we can open our HTML file at:

http://localhost:8000/hello.html

As you can see with this simple demonstration, we have Python calling methods of JavaScript objects using Python syntax, and JavaScript calling "Python" functions that have been transpiled. And as mentioned earlier, the generated JavaScript code is quite readable:

Listing 3 (Generated code): __target__/hello.js



// Transcrypt'ed from Python
import {AssertionError, ... , zip} from './org.transcrypt.__runtime__.js';
var __name__ = '__main__';  
export var say_hello = function () {  
   document.getElementById ('destination').innerHTML = 'Hello World!';  
};  
export var clear_it = function () {  
   document.getElementById ('destination').innerHTML = '';  
};  

//# sourceMappingURL=hello.map

Sourcemaps

To demonstrate the sourcemap feature, we can again create two source files: a Python file with a function to be transpiled, and an HTML file that will be the entry point for our application in the web browser. This time, our Python file will have a function that outputs text to the web browser console using both JavaScript and Python methods, along with a JavaScript method call that will generate an error at runtime:

Listing 4: sourcemap.py



def print_stuff():
    console.log("Native JS console.log call")
    print("Python print")
    console.invalid_method("This will be an error")

Listing 5: sourcemap.html



<!DOCTYPE html>
<html lang="en">
    <body>
        <script type="module">
            import {print_stuff} from "./__target__/sourcemap.js";
            document.getElementById("printBtn").onclick = print_stuff;
        </script>
        <button type="button" id="printBtn">Print</button>
    </body>
</html>

(venv) $ transcrypt --nomin --map sourcemap

This time, with the built-in Python HTTP server started using:

(venv) $ python -m http.server

We can open our test application at:

http://localhost:8000/sourcemap.html

If you open the developer console in the web browser and then click the button, the first two calls will execute, printing the text to the web browser console. The call to the JavaScript console.log() method behaves as you would expect. But as you can see here, the Python print() function ends up getting transpiled to call the JavaScript console.log() method as well.

The third function call generates an error since we are trying to call a nonexistent method of the JavaScript console object. However, what's nice in this case is that the sourcemap can direct us to the cause of the problem in our Python source file. So, even though it is the generated JavaScript that is actually running in the web browser, using a sourcemap, we can still view our Python code right in the web browser and see where the error occurred in the Python file as well.

React

Now that we've seen how Transcrypt lets us make calls to JavaScript, let's step it up and use Transcrypt to make calls to the React library. We'll start with another simple Hello World application again, but this time doing it the React way. We'll stick with the two source files: a python file to be transpiled and an HTML file that will be opened in a web browser. The HTML file will be doing a little extra work for us in that it will be responsible for loading the React JavaScript libraries.

Listing 6: hello_react.py



useState = React.useState
el = React.createElement

def App():
    val, setVal = useState("")

    def say_hello():
        setVal("Hello React!")

    def clear_it():
        setVal("")

    return [
        el('button', {'onClick': say_hello}, "Click Me!"),
        el('button', {'onClick': clear_it}, "Clear"),
        el('div', None, val)
    ]

def render():
    ReactDOM.render(
        el(App, None),
        document.getElementById('root')
    )

document.addEventListener('DOMContentLoaded', render)

Listing 7: hello_react.html



<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8"/>
    <script crossorigin
      src="https://unpkg.com/react@16/umd/react.production.min.js">
    </script>
    <script crossorigin
      src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js">
    </script>
    <script type="module" src="__target__/hello_react.js"></script>
  </head>
  <body>
    <div id="root">Loading...</div>
  </body>
</html>

Now transpile the Python file with Transcrypt:

(venv) $ transcrypt --nomin --map hello_react

Once again, after Transcrypt is done generating the JavaScript files, start up the built-in Python HTTP server using:

(venv) $ python -m http.server

Then open the demo React application at:

http://localhost:8000/hello_react.html

While functionally the same as the first demo application we did, this time React adds dynamically generated HTML as a child of a specified element - in this case, the "root" div.

Here, we added some convenience variables, useState and el, to map the global React methods to local Python variables. The React createElement() method is the workhorse of the library and is used to generate HTML elements in the browser dynamically.

React is declarative, functional, and is based on state. What this means, is that you define the view, and then React handles when and how it gets updated when there are changes in state. By design, React state variables are immutable and use a setter function to make updates. This helps React to know when changes to state occur, so it can then re-render the view as needed. In this example, we used the React useState() method to create the val variable and its corresponding setVal() setter function.

The return statement of a React functional component generally consists of a number of nested and chained calls to the React createElement() function that collectively form a tree structure of HTML elements and/or React components. This is where the view is declaratively defined. It may take some time to get more comfortable with this if you are not used to doing functional programming in Python.

The ReactDOM render() function takes the top-level React component and a reference to the HTML element to attach it to in the DOM. This is where it adds the dynamically generated HTML tree that React produces as a child of the specified element.

Building a React Application

UPDATE: The Parcel bundler has recently been updated and there is now a new version of the Transcrypt plug-in for Parcel v2 that eliminates the patch requirements outlined below. See the Using Parcel v2 and Transcrypt blog post for details on how to implement that version. The instructions provided below still apply if using the older version of Parcel.

Having done a simple React application, let's now create one that has a few more moving parts. This demo will take a value entered through the UI and add it to a list when submitted.

Most web applications of any utility will get large enough to where it becomes too unwieldy to manage manually. This is where package managers and application bundlers come into play. For this next example, we'll use the Parcel bundler to build and bundle the application so you can see what this developer stack might look like for larger applications.

First, we need to install the necessary JavaScript libraries to support the development toolchain. This does require Node.js to be installed on your system so that we can use the Node Package Manager. We start by initializing a new project and installing the Parcel bundler library along with the plug-in for Transcrypt:

$ npm init -y

$ npm install parcel-bundler --save-dev

$ npm install parcel-plugin-transcrypt --save-dev

Then we can install the React libraries:

$ npm install react@16 react-dom@16

Because of a version incompatibility, there is a file in the current Transcrypt plug-in that requires a patch. The file in question is:

./node_modules/parcel-plugin-transcrypt/asset.js

In that file, change line 2 that loads the Parcel Logger module from this:



const logger = require('parcel-bundler/src/Logger');

to this:



const logger = require('@parcel/logger/src/Logger');

Once this modification is made to change the location of the Parcel Logger module, the Transcrypt plug-in for Parcel should be working.

NOTE FOR WINDOWS USERS:

For those of you using Windows, two more changes need to be made to the asset.js file for it to work in Windows environments. The first is to modify the default Transcrypt build configuration to just use the version of Python that you set your virtual environment up with.

To do that, change line 14 that defines the Transcrypt command to simply use python instead of python3, changing it from this:



"command": "python3 -m transcrypt",

to this:



"command": "python -m transcrypt",

The second change has to do with modifying an import file path so that it uses Windows-style back-slashes instead of the Linux/Mac style forward-slashes. For this modification, we can use a string replace() method on line 143 to make an inline correction to the file path for Windows environments. So change this line:



this.content = `export * from "${this.importPath}";`;

to this:



this.content = `export * from "${this.importPath.replace(/\\/g, '/')}";`;

At some point, I would expect that a modification will be incorporated into the parcel-plugin-transcrypt package so that this hack can be avoided in the future.

Now that we have a bundler in place, we have more options as to how we work with JavaScript libraries. For one, we can now take advantage of the Node require() function that allows us to control the namespace that JavaScript libraries get loaded into. We will use this to isolate our Python-to-JavaScript mappings to one module, which keeps the rest of our code modules all pure Python.

Listing 8: pyreact.py



# __pragma__ ('skip')
def require(lib):
    return lib

class document:
    getElementById = None
    addEventListener = None
# __pragma__ ('noskip')

# Load React and ReactDOM JavaScript libraries into local namespace
React = require('react')
ReactDOM = require('react-dom')

# Map React javaScript objects to Python identifiers
createElement = React.createElement
useState = React.useState


def render(root_component, props, container):
    """Loads main react component into DOM"""

    def main():
        ReactDOM.render(
            React.createElement(root_component, props),
            document.getElementById(container)
        )

    document.addEventListener('DOMContentLoaded', main)

At the top of the file, we used one of Transcrypt's __pragma__ compiler directives to tell it to ignore the code between the skip/noskip block. The code in this block doesn't affect the transpiled JavaScript, but it keeps any Python linter that you may have in your IDE quiet by stubbing out the JavaScript commands that are otherwise unknown to Python.

Next, we use the Node require() function to load the React JavaScript libraries into the module namespace. Then, we map the React createElement() and useState() methods to module-level Python variables as we did before. As we'll see shortly, this will allow us to import those variables into other Python modules. Finally, we moved the render() function we created previously into this module as well.

Now that we have the JavaScript interface somewhat self-contained, we can utilize it in our application:

Listing 9: app.py



from pyreact import useState, render, createElement as el


def ListItems(props):
    items = props['items']
    return [el('li', {'key': item}, item) for item in items]


def App():
    newItem, setNewItem = useState("")
    items, setItems = useState([])

    def handleSubmit(event):
        event.preventDefault()
        # setItems(items.__add__(newItem))
        setItems(items + [newItem])  # __:opov
        setNewItem("")

    def handleChange(event):
        target = event['target']
        setNewItem(target['value'])

    return el('form', {'onSubmit': handleSubmit},
              el('label', {'htmlFor': 'newItem'}, "New Item: "),
              el('input', {'id': 'newItem',
                           'onChange': handleChange,
                           'value': newItem
                           }
                 ),
              el('input', {'type': 'submit'}),
              el('ol', None,
                 el(ListItems, {'items': items})
                 )
              )


render(App, None, 'root')

As mentioned before, we import the JavaScript mappings that we need from the pyreact.py module, just like we would any other Python import. We aliased the React createElement() method to el to make it a little easier to work with.

If you're already familiar with React, you're probably wondering at this point why we're calling createElement() directly and not hiding those calls behind JSX. The reason has to do with the fact that Transcrypt utilizes the Python AST module to parse the PY files, and since JSX syntax is not valid Python, it would break that. There are ways to utilize JSX with Transcrypt if you really wanted to, but in my opinion the way you have to do it kind of defeats the purpose of using JSX in the first place.

In this module, we created two functional React components. The App component is the main entry point and serves as the top of the component tree that we are building. Here we have two state variables that we create along with their companion setter functions. The newItem state variable will hold an entered value that is to be added to the list. The items state variable will then hold all of the values that have been previously entered.

We then have two functions, one to perform an action when the form submits the value that was entered, and another that synchronizes the value that is being entered with the state of our React component.

Then, in the return statement of the App() function, we declare the tree of elements that define the UI. The top of the element tree starts with an HTML form. This allows us to take advantage of its default submit button, which in this case calls our handleSubmit() function that will add new values to the list.

In the handleSubmit() function, when adding a new item to our list, we used an in-line compiler directive to let Transcrypt know that this particular line of code is using an operator overload:



        setItems(items +  [newItem])  # __:opov`  
```
By default, Transcrypt turns off this capability as it would cause the generated JavaScript to take a performance hit if it were enabled globally due to the overhead required to implement that feature.  If you'd rather not use the compiler directive to enable operator overloading only where needed, in a case like this you could also call the appropriate Python operator overload dunder method directly as shown in the commented line just above it.

Inside (or below) that, we have an `input` element for entering new values along with a corresponding `label` element that identifies it in the UI.   The `input` element has the `handleChange()` function as its `onChange` event handler that keeps the React state synced up with what the UI is showing.

Next in the element tree is the list of values that have already been entered.  These will be displayed in the UI using an HTML ordered list element that will number the items that are added to it.

This brings us to this module's second functional component, `ListItems`, that renders the values in our `items` state variable as HTML `li` elements.  The `items` are passed into this component as a property that we deconstruct into a local variable.  From there, we use a Python list comprehension to build the list of `li` elements by iterating through the items.

The last step is to call the imported `render()` function that will attach our `App` React component to the DOM hook point identified by `'root'` in the HTML file:
```python
render(App, None, 'root')
```
You'll notice that because we put all of the Python-to-JavaScript mappings in the **pyreact.py** module, that this module can be 100% pure pythonic Python.  No mixing of languages, no weird contortions of the Python language, and no JavaScript!

To complete this demo, we now just need an HTML entry point that we can load into a web browser:

Listing 10: [*index.html*](https://github.com/JennaSys/rtp_demo/blob/main/index.html)
```html
<!DOCTYPE html>
<html lang="en">
    <head>
        <script src="app.py"></script>
        <title>React to Python</title>
    </head>
    <body>
        <div id="root"></div>
    </body>
</html>
```

This time, instead of running Transcrypt directly, we can run the `parcel` command using the Node `npx` package runner.  And thanks to the Transcrypt Parcel plugin, it will also run Transcrypt for us and bundle up the generated JavaScript files:  

(venv) $ `npx parcel --log-level 4 --no-cache index.html`  

This also starts up the Parcel development webserver that will serve up the generated content using a default route at:  
http://localhost:1234  

![React App Screenshot](https://github.com/JennaSys/rtp_demo/raw/main/images/app_screenshot.png)

And with this, we have the foundational basis for building React applications using Python!

&nbsp;

## For more...
If you are interested in learning more details about what is presented here, the [React to Python](https://pyreact.com) book dives a lot deeper into what is needed to develop complete web applications using this approach.  

[![Cover image for the React to Python book](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/cq6kw5yv5wr7wwdbd7yi.jpg)](https://pyreact.com)

**The book Includes:**
- Setting up the required developer environment tools
- Creating CRUD Forms
- Asynchronous requests with a Flask REST service
- Basics of using the Material-UI component library
- Single Page Applications
- Basic user session management
- SPA view Routing
- Incorporating Google Analytics into your application
- Walks you through building a [complete demo project](https://rtp.jennasys.com)  
[![Screenshot of the project featured in the React to Python book](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/y9x5qe830npmt5qdorii.png)](https://rtp.jennasys.com)
&nbsp;

## Resources
- Source Code:
    https://github.com/JennaSys/rtp_demo  

- Transcrypt Site:
    https://www.transcrypt.org  

- Transcrypt GitHub:
    https://github.com/TranscryptOrg/Transcrypt  

- React to Python Book:
    https://pyreact.com  

*This content was originally released as a download on [Leanpub](https://leanpub.com/rtptutorial)*

Python and the Browser - Revisited

JennaSys — Sat, 10 Apr 2021 01:57:20 +0000

A while back, I posted about my initial foray into using Python to develop front-end web applications with React by using the Transcrypt transpiler.

Python and the Browser. I had to find out: Was it actually… | by JennaSys | Medium

JennaSys ・ Mar 6, 2022 ・
jennasys.Medium

Part of the initial learning process I went through was doing the official React tutorial, but using Python for the code instead of JavaScript. When I did that, I adhered to the structure of the application that was used in the tutorial pretty closely. Since then, I have been working with Transcrypt and React quite a bit more and have formed some of my own standards of practice for producing clean Python code in my React applications. In this post, I'll show you a few of those practices as I take the original class-based version of that program I did (which is what the React tutorial is based on), and convert it to use functional components and React hooks instead (which is all I use now).

Overview

The premise of the React tutorial is a Tic-Tac-Toe game that maintains a history of moves, where you can reset the board back to any previous point. The design consists of a Game component that manages the state of the game and holds the history of moves. Then there is a Board component that handles the rendering of the board. And Lastly, there is a Square component that renders a single square in the game.

My original version of the application has four files:

index.html (the application entry point and DOM root)
game.css (CSS selectors for the application)
tictacreact.py (the application code in Python)
pyreact.py (Python wrappers for the React.Component class and miscellaneous JavaScript functions)

Support Files

For this makeover, the CSS file and the index.html file will remain pretty much unchanged:

Listing 1: index.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8"/>
    <title>Tic Tac React!</title>
    <link rel="shortcut icon" href="favicon.ico" type="image/x-icon" />
    <script crossorigin src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
    <script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>
    <link rel="stylesheet" href="game.css" />
</head>
<body>
<div id="root"></div>
<script type="module" src="__target__/tictacreact.js"></script>
</body>
</html>

Since we will no longer be using React class components, we can clean up the pyreact.py file quite a bit. I use this Python module to hold all of the Python-to-JavaScript mappings, that I can then import into other Python modules. This approach facilitates keeping any JavaScript messiness in one place and allows all of the other Python modules to remain pure Python, which keeps the Python linter happy.

For most projects, I've been using the Parcel bundler which has a Transcrypt plug-in available for it. With that, I would normally have a few lines in the pyreact.py module to load the React libraries with a JavaScript ES5 style import that uses the Node require() function like this:

React = require('react')
ReactDOM = require('react-dom')

In this case, since we are loading the React libraries in the HTML header, the React and ReactDOM namespaces will be global, so I instead just stubbed out those libraries in the Python file.

Listing 2: pyreact.py

# __pragma__ ('skip')
"""
These JavaScript object stubs are just to
quiet the Python linter and are ignored by transcrypt as long
as they are imported inside of pragma skip/noskip lines.
"""

class React:
    createElement = None
    useState = None
    useEffect = None
    createContext = None
    useContext = None


class ReactDOM:
    render = None


class document:
    getElementById = None
    addEventListener = None
# __pragma__ ('noskip')


# Map React javaScript objects to Python identifiers
createElement = React.createElement
useState = React.useState
useEffect = React.useEffect
createContext = React.createContext
useContext = React.useContext


# Wrap the ReactDOM.render method to hide JavaScript details
def render(root_component, props, container):
    def main():
        ReactDOM.render(
            React.createElement(root_component, props),
            document.getElementById(container)
        )

    document.addEventListener("DOMContentLoaded", main)

The section between the skip/noskip pragma lines isn't really needed other than to quiet the Python linter not being able to resolve the JavaScript object names. They are just Python stub declarations that will ultimately be ignored by Transcrypt thanks to the compiler directives.

The mappings in this file are where Transcrypt does a lot of its magic. I'm basically assigning a JavaScript object to a Python variable. From there, it can be used just like any other Python object. It can be imported into other Python modules, and its methods can be called. Even though I'm using JavaScript libraries, I only need to know the library's API to code to it using Python.

The render() function doesn't change from before, and is just a wrapper around the ReactDOM.render() method that lets us encapsulate the JavaScript calls that go along with it.

The Refactoring

Most of the actual refactoring we did in this version of the application was in the tictacreact.py module. Beyond just turning the class components into functional components, we also changed how some of the state gets updated. While it didn't save us many lines of code, it is now a bit more modularized and (hopefully) more readable than what was there before.

Listing 3: tictacreact.py

from pyreact import render, useState, createElement as el
from pyreact import createContext, useContext


Ctx = createContext()


def Square(props):
    idx = props['idx']

    ctx = useContext(Ctx)
    squares = ctx['squares']
    onClick = ctx['onClick']

    return el('button', {'className': 'square',
                         'onClick': lambda: onClick(idx)
                         }, squares[idx])


def Row(props):
    rowNum = props['rowNum']

    row = [el(Square, {'idx': (rowNum * 3) + col_num}) for col_num in range(3)]
    return el('div', {'className': 'board-row'}, row)


def Board():
    rows = [el(Row, {'rowNum': row_num}) for row_num in range(3)]
    return el('div', None, rows)


def Moves(props):
    numMoves = props['numMoves']
    setStepNumber = props['setStepNumber']

    def get_move(move):
        desc = ('Go to move #' + str(move)) if move > 0 else 'Go to game start'
        return el('li', {'key': move},
                  el('button', {'className': 'move-history',
                                'onClick': lambda: setStepNumber(move)
                                }, desc)
                  )

    return [get_move(move) for move in range(numMoves)]


def Game():
    history, setHistory = useState([{'squares': [None for _ in range(9)]}])
    stepNumber, setStepNumber = useState(0)

    board = history[stepNumber]
    xIsNext = (stepNumber % 2) == 0
    winner = calculate_winner(board['squares'])

    if winner is not None:
        status = f"Winner: {winner}"
    elif stepNumber == 9:
        status = "No Winner"
    else:
        status = f"Next player: {'X' if xIsNext else 'O'}"

    def handle_click(i):
        new_squares = list(board['squares'])
        if winner or new_squares[i]:  # Already winner or square not empty
            return  # Nothing to do

        new_squares[i] = 'X' if xIsNext else 'O'

        tmp_history = history[:stepNumber + 1]  # Slice in case step changed
        new_history = [{'squares': move['squares']} for move in tmp_history]
        new_history.append({'squares': new_squares})
        setHistory(new_history)
        setStepNumber(len(new_history) - 1)

    return el(Ctx.Provider, {'value': {'squares': board['squares'],
                                       'onClick': handle_click}
                             },
              el('div', {'className': 'game'},
                 el('div', {'className': 'game-board'},
                    el(Board, None),
                    el('div', {'className': 'game-status'}, status),
                    ),
                 el('div', {'className': 'game-info'}, 'Move History',
                    el('ol', None,
                       el(Moves, {'numMoves': len(history),
                                  'setStepNumber': setStepNumber}
                          )
                       )
                    )
                 )
              )


# Render the component in a 'container' div
render(Game, None, 'root')


def calculate_winner(squares):
    lines = [
        [0, 1, 2],
        [3, 4, 5],
        [6, 7, 8],
        [0, 3, 6],
        [1, 4, 7],
        [2, 5, 8],
        [0, 4, 8],
        [2, 4, 6],
    ]

    for line in lines:
        a, b, c = line
        if squares[a] and (squares[a] == squares[b]) and (squares[a] == squares[c]):
            return squares[a]
    return None

In the main Game component, we made several changes starting with converting the class-based state object to individual useState() hooks instead. So the history and stepNumber state variables now have their own companion update functions.

Since the xIsNext state variable that was being used before is just calculated based on the value of another state variable, I changed it to be a local variable instead. It will get recalculated if a re-render happens due to a change in the state that it is based on.

To clarify what is being displayed at any given time, I also added the local variable board to hold the current board values as a convenience. Now, as determined by the stepNumber, we pull it out of the history list just once instead of every time we need to use it as we were doing before. This value also gets recalculated when a re-render happens.

The handle_click() function gets cleaned up a little, but it is still a bit busy since we need to make copies of the history and board squares in order to update them since we are working with immutable objects. Until Transcrypt adds the Python copy standard library to what it supports, you either have to use a JavaScript function to do that, or do it manually as we did here for history where we used a list comprehension:

new_history  = [{'squares': move['squares']} for  move  in  tmp_history]

For the list of previous moves that get displayed in the UI, instead of generating the list item elements in the Game component, we moved that functionality into its own Moves component. This change cleans up the Game component and makes the overall application structure a little more readable.

One of the practices I started doing was to deconstruct the values held in the props object into local variables rather than directly referencing them from props just when they are needed:

def Moves(props):
    numMoves = props['numMoves']
    setStepNumber = props['setStepNumber']

This practice accomplishes two things. First, by deconstructing all of the values right at the top of the function definition, I know exactly what props that component is expecting without having to search the entire function to figure it out. Second, it cleans up the code in the function where I actually use those values by not having to do the dictionary lookups in place.

The last somewhat subtle change we made is to put the handle_click() function and the board squares into a context variable:

el(Ctx.Provider, {'value': {'squares': board['squares'],
                            'onClick': handle_click}
                            },

Using this context variable saves us from having to pass these values down through several other layers of components that don't need them, just so that we can use them in the Square component.

In the Board component, we really cleaned it up in that it now just returns a div element with three Row components. And since we are now using the context variable, we no longer need to pass any props into it.

The Row component is something new we added with this refactor that clarifies conceptually what is being generated. Similar to the Board component, the Row component returns a div element containing just three Square components.

The Square component is now a bonafide React component instead of just an imperative function. Functionally it is the same as before, but we did add in the React useContext() hook to pull out the values we needed to use here:

ctx = useContext(Ctx)
squares = ctx['squares']
onClick = ctx['onClick']

Finally, we just made some minor optimizations to the calculate_winner() function from the earlier version.

Transpile & Run

Right now, Transcrypt version 3.7.16 only works with Python 3.6 or 3.7, so in setting up a virtual environment, I'll use this:

$ python3.7 -m venv venv

then activate it:

$ source ./venv/bin/activate

(for Windows use venv\Scripts\activate )

and then install Transcrypt:

(venv) $ pip install transcrypt

To build the application, you just need to give Transcrypt the entry point of your application, and it will walk the dependency tree to transpile any other related modules:

(venv) $ transcrypt --nomin --build --map tictacreact

We also gave it a few CLI options:

nomin - tells it not to minify the generated JavaScript (Note: The Java runtime is needed for this to work)
build - tells it to start from scratch
map - tells it to generate a JavaScript-to-Python source code map file

Once that is done, we need to serve up the generated files before we can open up the application in a web browser. A quick way to do this is using the HTTP server that comes with Python:

(venv) $ python -m http.server

Then open the application:

http://localhost:8000/index.html

You can find all of the source code for this application here:

https://github.com/JennaSys/tictacreact2

A live demo of this code (with source maps) is also hosted on GitHub Pages:

https://jennasys.github.io/tictacreact2/

Conclusion

As someone that really likes Python and isn't a big fan of JavaScript, using Transcrypt to develop React applications with Python has been working out decidedly well for me so far. To share how I was doing it, I had started putting together an outline for a talk I was going to give at my Python meetup group. As it turned out, that outline kept growing, and I ended up writing an entire book about it instead. If you're interested, you can find out more about the "React to Python" book here: https://pyreact.com

DEV Community: JennaSys

Setting up Hot Reload with KivyMD

The Good (Key points for getting it to work)

MDApp import

MDApp.build_app() vs MDApp.build()

DEBUG

KV_FILES, KV_DIRS & CLASSES

Summary

The Bad (Dealing with maintenance hassles)

The Ugly (Is it really worth it?)

Conclusion

Resources

Using Parcel v2 and Transcrypt to create web applications with Python

Installation

Configuration

Plugin Options

Proxy Server

Additional Details

tl;dr

Conclusion

Resources

Setting up a full-stack application on Replit

Replit basics

The basic setup

Running two servers

To build or not to build

Conclusion

Resources

No-el: Eliminate explicit calls to createElement() when using Python to code React applications

The Code

An Example

Conclusion

Resources

Creating React Applications with Python

Full-Stack Python

Features of Transcrypt include:

npm instead of pip

Installation

Hello World

Sourcemaps

React

Building a React Application

Python and the Browser - Revisited

Python and the Browser. I had to find out: Was it actually… | by JennaSys | Medium

JennaSys ・ Mar 6, 2022 ・ jennasys.Medium

Overview

Support Files

The Refactoring

Transpile & Run

Conclusion

JennaSys ・ Mar 6, 2022 ・
jennasys.Medium