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, argparse, 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. Memory is the process’s physical footprint, the figure the operating system meters a process by and the one a memory limit is measured in, read the same way for every runtime.

Every Codename One figure below appears twice, from the same executable.

Codename One is the program on a machine with memory to spare. Its collector adapts to the load. While collecting costs the program little CPU it keeps the heap close to what the program uses. When the program is busy enough that more frequent collections would cost it throughput, it lets the heap grow instead: idle memory on the machine earns nothing, and the speed it buys is real. That’s a choice the runtime makes because the memory is there, not a size it needs.

Codename One, 128 MB budget is the same executable given a memory limit, the way a container, a small cloud instance or a phone would give it one. With a budget, the collector stops spending memory for speed: it keeps the heap tight, and paces allocation so the process stays inside the limit. The budget is a hard cap, not a target: when the limit is near, a thread that needs memory waits for the collector rather than going over. The trade flips, and the program gives back some speed to use less memory.

Collecting garbage has a cost, and at high throughput it shows: under a budget, more of the CPU goes to the collector instead of the program. The server figures below make that visible.

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 footprint in MB:

The numeric kernels allocate almost nothing, so the budget changes nothing there. dicts_strings builds large dictionaries and strings, and shows the trade in miniature: under the budget it gives up about a tenth of its speed for more than a quarter less memory.

The Flask sample above, under thirty seconds of ab -c 8 after a warm-up. Every server gets the same length of load rather than the same number of requests, so a fast server isn’t measured before its collector has settled. Footprint is read when the load ends, again five seconds later, and at its peak. Each server runs the way app.run() starts it: Werkzeug’s threaded server under CPython, PyPy and GraalPy, and the native backend server under Codename One, which lowers the same call onto it.

Read that table with suspicion. Codename One serves 37 times as many requests as CPython, and the gap doesn’t fit anything else on this page. On the kernels above, Codename One runs about as fast as PyPy, and PyPy is many times faster than CPython. Yet here PyPy serves 692 requests a second and CPython 699: the interpreter that runs Python several times faster gains nothing. When a faster engine doesn’t move the result, the engine isn’t what’s being measured.

Three measurements found what was being measured instead.

First, Flask alone, with no server. scripts/python-compare/flask_cost.py sends the same request through Flask’s test client, which calls the application directly without a socket, so it times only the routing, the view and the JSON response. On one core CPython handles about 14,000 of these requests a second, PyPy about 28,500 and GraalPy about 5,800. Flask is fast enough on every interpreter: under app.run(), 95% of each request’s time went somewhere else.

Second, concurrency. With one connection at a time Werkzeug’s server answered 86 requests a second, with 8 connections 686, and with 32 connections 2,707. Throughput rose in step with the number of connections while the server used about a tenth of one core. A server bound by computation stops scaling once its core is busy; this one was mostly waiting.

Third, one request timed by hand: send it, then note when the first byte of the response arrives and when the server closes the connection. The response arrived after 0.4 ms. The server closed the connection about 12 ms after that.

The 12 ms is in werkzeug/serving.py. After every response the development server drains whatever the client might still be sending, so that a client whose upload was too large sees the error page rather than a reset connection. It keeps reading until a select with a 10 ms timeout finds nothing more, so every connection stays open for at least 10 ms after its response. ab speaks HTTP/1.0 and counts a request as done when the server closes the connection. Eight connections that each take about 12 ms come to about 670 requests a second, whichever interpreter runs the Python. That’s the number CPython and PyPy both reached.

The Werkzeug documentation is clear that its server is for development, so none of this is a defect. It means the table above compares Codename One’s production server with Python’s development server.

In production a Flask application runs behind a WSGI server such as gunicorn, with several worker processes: each worker is a whole interpreter, and they handle connections in parallel. The rows below serve the same application with gunicorn -w 8, under the same load. Their footprint is the master process and all eight workers added together, because that’s what the machine pays for. GraalPy is missing: gunicorn imports the grp module, which GraalPy doesn’t provide.

Behind gunicorn, CPython serves 13 times as many requests as it did under app.run(). Codename One under its budget still serves 2.7 times as many, in 30% of CPython’s memory and 12% of PyPy’s. That’s the gap to plan around: about three times the throughput, not 37 times, and a fraction of the memory.

The difference comes from how each server is built, more than from how fast each runs Python:

PyPy and CPython reach the same throughput behind gunicorn too, although PyPy runs Flask’s own code about twice as fast, so with eight workers the Python code isn’t the limit for either of them. What PyPy does change is memory: its eight workers, each with its own JIT, use two and a half times CPython’s.

The deployed size is the interpreter’s installation plus Flask and its dependencies (and gunicorn, under 1 MB), against the one executable.

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: