Writing applications and backends in Python

Python source builds as a Codename One application. The build translates each module to Java, compiles it with the rest of the project, and from there it goes wherever Java goes: iOS, Android, the JavaScript port, the desktop ports, the simulator, and native server binaries built on the Codename One backend.

No Python interpreter ships with the application. Each module becomes a Java class, each function a method, and a small runtime supplies Python’s object model, its built-in types and the standard library modules applications use. Annotated code is compiled to unboxed Java arithmetic, so a typed numeric loop runs at the speed of the equivalent Java.

Two things follow from compiling ahead of time rather than interpreting:

Put the sources in common/src/main/python, or import an existing Python project into a Codename One application:

The import copies the .py files, adds the Python runtime dependency and the transpile-python goal to the common module, records the entry module and makes the application’s main class run it. Then build and run the project as usual; the translation runs in generate-sources. Gradle projects get the same step as the transpilePython task.

The goal reads these properties:

The translated classes carry the Python source’s file and line numbers in place of the generated Java’s. A stack trace names the Python file and line:

The same lines reach a Java debugger attached to the simulator or to a server binary run on the JVM. Each class also carries a JSR-45 source map whose default stratum, Python, gives the file’s path within the source directory, for example app/util.py. Breakpoints are set by Python line number, and a debugger that resolves sources through the source map opens the .py file. With jdb:

The mapping is applied to the compiled classes by the build’s remap-compat step (cn1RemapCompat in Gradle), so the generated Java in target/generated-sources/python still shows the Python line that each statement came from, as a /* line N */ comment above it.

Any class on the project’s class path is importable under the java. prefix:

A Python function or lambda passed where Java expects a listener or another single-method interface becomes an implementation of that interface. Overloads are chosen at build time when the argument types are known, and otherwise by the runtime from the values passed.

Values cross the boundary as follows:

Java collections behave as their Python counterparts in Python code: len, indexing, in and iteration work on an ArrayList or a HashMap, and a Java exception arrives as a Python exception whose message names the Java type.

To call into Python from Java, import the module through the runtime and call its attributes. The build generates com.codename1.generated.python.PythonModules, which registers every translated module. When Python is the application’s entry point, its main class calls PythonModules.registerAll() at startup; a Java application that uses Python as a library calls it once before importing anything:

The user interface is Codename One’s, called from Python, so everything in the rest of this guide applies: layouts, themes and CSS, the component inspector, and the same look on every platform. The examples below are complete applications. Each is a main.py you can put in common/src/main/python.

The first example fetches JSON with requests on a worker thread, shows a progress indicator while it waits and fills a list when the response arrives. Pull the list down, or tap the toolbar button, to load it again.

Three conventions carry over from Codename One’s Java API:

The second example keeps notes in SQLite through the standard sqlite3 module, models them as a dataclass and moves between a list and an editor form. The editor saves when the user goes back, and asks before deleting.

The structure is the one a Python developer would write for any user interface toolkit: a storage class with no user interface code, and a class that owns the forms and turns model objects into components. show() moves forward to a form, showBack() returns with the reverse transition, and the toolbar’s back command is also what Android’s back button runs.

The standard library modules applications use most are included: json, re, datetime, decimal, fractions, collections, itertools, functools, dataclasses, enum, typing, inspect, asyncio, logging, pathlib, os.path, csv, struct, hashlib, base64, uuid, random, statistics, heapq, bisect, textwrap, string, tomllib, sqlite3, threading, queue, concurrent.futures, pickle, shelve, urllib.request, http.client, email.message, zlib, gzip, zipfile, zoneinfo, unittest (with unittest.mock) and others. A small pytest is included as well: raises, approx, marks, fixtures and parametrized tests.

These third party packages are provided, each tested against the output of the real package:

cn1:import-python-project installs the project’s requirements, read from pyproject.toml and requirements.txt, from PyPI. Each requirement and everything it depends on is resolved to the newest release its version specifiers accept, its download is checked against the SHA-256 PyPI publishes, and its Python sources go into common/src/main/python-packages. The build translates that directory together with src/main/python. Requirements on packages the runtime already provides, such as requests or numpy, aren’t downloaded.

The versions chosen are recorded in python-packages/python.lock. Importing again installs the same versions, so a dependency changes only when you delete its line from the lock, or the file itself, and import again.

You can also copy a package’s sources into the source directory by hand; they translate like the application’s own modules.

A package with a C extension is supported. Its compiled modules are what CPython loads from C; everything around them is ordinary Python. The build translates that Python as usual, and each compiled module is replaced by a Java class that registers the same functions. Most C extensions are small accelerators or thin wrappers over a system facility, so the Java is usually short, and often a call into a Codename One API that already does the job.

The import finds the compiled modules (.so and .pyd files in a wheel, .pyx sources in a source distribution) and the names the package’s Python uses from each one. For every module it generates a class in common/src/main/java/com/codename1/python/ext with a stub per function, and lists it in python-packages/cn1-native-modules.properties:

Replace each stub’s body with Java. The functions receive plain Java values (a Number for an int or a float, String, byte[], java.util.List for a list or tuple, java.util.Map for a dict, null for None) and return the same kinds; an Object[] comes back to Python as a tuple. Raise a Python exception with Py.error(Py.TYPE_ERROR, "…​") and its siblings, and use NativeModule.raw for a function that needs the Python objects themselves. Until a stub is filled in, calling it raises a NotImplementedError that names it. The import never overwrites a class that already exists, so importing again keeps your code.

Many packages ship a C accelerator together with a pure Python version of the same code, and import the compiled module inside try: …​ except ImportError:. When every import of a compiled module is guarded that way, the import reports it as optional and generates nothing: the pure Python version runs instead.

threading, queue and concurrent.futures run on Java threads. As in CPython, one global interpreter lock serializes Python code: it’s released while a thread sleeps, waits on a lock, a queue or a future, or waits for a network response, so threads help with blocking work and not with computation. ProcessPoolExecutor is accepted and runs its tasks on threads.

Codename One’s user interface belongs to its event dispatch thread. Python code started by the application runs on that thread, so update components from a worker thread with Display.getInstance().callSerially, as Java code does.

sqlite3 runs on the platform’s own SQLite through Codename One’s Database. On iOS, Android and the simulator a value comes back in the storage class SQLite recorded for it. The Linux, Windows and JavaScript ports don’t report storage classes, so a value comes back as an int or a float when its text is a number, and as a str otherwise.

A Flask or FastAPI application builds into a single native server executable. The application starts the server the way it always does:

app.run() and uvicorn.run(app) are lowered onto the Codename One backend’s HTTP server, so the same file still runs under CPython for development:

Routing, converters, JSON bodies, abort, error handlers and the default error pages of Flask, and FastAPI’s path, query, body and header parameters, dependencies, response_model and OpenAPI generation are supported, and Flask sessions, flash, Jinja templates (extends, block, include, macros, call, import, filter blocks, loops, conditions and the common filters, with autoescaping), multipart file uploads and streamed responses work as well. A streamed response is sent chunk by chunk as its generator yields. Session cookies use Flask’s own itsdangerous format, so a server built here and one running under CPython read each other’s sessions when they share a secret key.

FastAPI middleware works as in Starlette: @app.middleware("http"), BaseHTTPMiddleware subclasses, CORSMiddleware, GZipMiddleware and TrustedHostMiddleware. WebSocket endpoints are supported, including TestClient.websocket_connect. A WebSocket endpoint runs on a real asyncio event loop, so it can await asyncio.sleep, tasks and queues while its socket is open, and pure ASGI middleware sees WebSocket connections as it does in Starlette. Denying a connection answers with the status the endpoint or middleware chose, such as 403.

SQLAlchemy’s Core and ORM run over the platform’s SQLite, and on a backend over the PostgreSQL, MySQL and MariaDB drivers the Codename One backend ships. The engine URL picks the database, as it does under CPython:

Declarative models with Mapped annotations, relationships in both directions (including many-to-many and cascades), selectinload and joinedload, joins, aliases, subqueries, common table expressions, unions, single and joined table inheritance and text() queries are supported. Numeric columns come back as decimal.Decimal and DateTime and Date columns as datetime values on every database. A text() query has no column types, so on a server database its numbers and dates come back as the text the server sent. SQLAlchemy’s own drivers, such as psycopg, aren’t used: the URL postgresql+psycopg:// selects the backend’s driver.

Every request runs on a virtual thread with 1MB of C stack, because transpiled Python frames are large and re recurses. A handler that recurses deeper than that raises it with a build hint in codenameone_settings.properties, in bytes or with a KB or MB suffix:

CN1_HTTP_VT_STACK can still raise it when the server starts, and the larger of the two applies.

The same programs, run on one Apple Silicon Mac with scripts/python-compare/compare.py and scripts/python-compare/common_compare.py. Codename One rows are native executables. The interpreters are CPython 3.14, PyPy 3.11 (7.3.20) and GraalPy 3.13 (Community edition 25.4, on its own JVM). Every program runs in a process of its own, so each memory figure is that program’s peak resident memory.

A program that prints one line, best of ten runs:

Classic benchmark programs written for Python (scripts/python-bench/kernels), fastest round in milliseconds, then peak memory in MB:

The Flask sample above, measured with ab -n 20000 -c 8 after a warm-up:

The deployed size is the interpreter’s installation plus Flask and its dependencies, against the one executable. CPython, PyPy and GraalPy serve with Werkzeug’s threaded server, which is what app.run() starts; a production CPython deployment behind a WSGI server with several worker processes serves more, using a full interpreter’s memory per worker. The Codename One server’s heap grows under load and stays at that size, which is the memory after load column; it doesn’t grow further on longer runs.

Where an application needs CPython instead: code that builds source text and runs it with exec, and packages whose C code is the bulk of the package rather than an accelerator under its Python, such as scipy or torch. Replacing those means writing a numerical library in Java, not a few functions.

The workloads below are the ones every Codename One port is measured with, com.bench.CommonWorkloads, ported line by line to Python in scripts/python-bench/common. Each one returns a checksum, and every runtime has to return the checksum Java returns, so all five columns compute the same thing. The Python port reproduces Java’s 32 and 64-bit wrap-around with masks, since a Python int never overflows.

The Codename One Java column is the Java original compiled by Codename One into the same executable. It’s the floor: the speed and memory Codename One reaches for this work when written in Java, and the target for the same program written in Python.

What the numbers say:

A profile usually shows a handful of functions that dominate the run time. Any of them can be rewritten as a Java method in the same project and called from Python like any other Java class. The rest of the program stays Python.

The integer kernel in Python:

The same function in Java, under common/src/main/java:

And the Python that calls it:

The Java int wraps by itself, so the masks disappear and the loop compiles to a few machine instructions. In the run above that took the workload from 1.75 seconds to 65 milliseconds, faster than PyPy and GraalPy, in 11 MB.

Guidelines for choosing what to move: