pygbag

Package Python Pygame apps for web

TLDR

Package a Pygame project and start a local test server

$ pygbag [path/to/project_folder]

Package using Python module syntax

$ python -m pygbag [path/to/project_folder]

Package and build without starting the test server

$ pygbag [path/to/project_folder] --build

Package with a specific template

$ pygbag [path/to/project_folder] --template [template_name.tmpl]

Package and create a ZIP archive for

$ pygbag [path/to/project_folder] --archive

Package with optimization turned off

$ pygbag [path/to/project_folder] --no_opt

Specify a custom port for the test server

$ pygbag [path/to/project_folder] --port [8080]

Display help

$ pygbag [[-h|--help]]

PARAMETERS

--build
Initiates the build process to generate the web application.

--target
Specifies the output directory where the built web app files will be saved.

--bind

    Sets the IP address for the local development server (e.g., 0.0.0.0 for all interfaces).

--port
    Defines the port number for the local development server.

--debug
    Enables verbose debug output and potentially debug-specific features during build/run.

--template
    Allows using a custom HTML template file for the web application.

--title
    Sets the title for the generated HTML page and PWA.

--icon
    Specifies the path to an icon file to be used for the PWA and browser favicon.

--add
    Includes additional files or directories into the web application package.

--install
    Installs additional Python packages (e.g., from PyPI) into the WASM environment during build.

--upgrade
    Attempts to upgrade the pygbag package itself before performing the build.

--fast
    Activates optimizations to speed up the build process, potentially skipping some checks.

--pwa
    Explicitly enables Progressive Web App features (often enabled by default).

--verbose
    Provides more detailed output during the command execution.

--version
    Displays the current version of pygbag.

DESCRIPTION

pygbag is a powerful Python package and command-line tool designed to simplify the deployment of Python applications, particularly those utilizing the Pygame library, onto the web. It acts as a comprehensive toolchain, taking your Python source code and its dependencies, compiling them into WebAssembly (WASM), and packaging them alongside HTML, CSS, and JavaScript into a distributable web application. The primary goal of pygbag is to enable Pygame games and other Python GUI applications to run directly within a standard web browser, eliminating the need for users to have a local Python installation.

It handles the complexities associated with Emscripten compilation and JavaScript integration, abstracting these technical details from the developer. The output is a self-contained web application, frequently configured as a Progressive Web App (PWA), which can be served from any web server or even run offline, offering a native-like experience. This significantly broadens the accessibility and reach of Python projects by making them available to anyone with a modern web browser.

CAVEATS

Certain Python features requiring direct native system access, specific C extensions, or advanced file system operations outside pygbag's virtual environment might not function as expected or require specialized porting. Performance for graphically intensive applications may differ from native desktop builds. Debugging applications deployed to the web via WASM can be more intricate than traditional Python debugging. Browser security policies (e.g., CORS, sandboxing) can impose limitations on functionality.

PROGRESSIVE WEB APP (PWA) CAPABILITIES

Projects built with pygbag often result in Progressive Web Apps. These PWAs can be 'installed' on user devices, appearing and behaving more like native applications. They leverage browser technologies like service workers to cache assets, enabling the application to run even when offline, providing a robust and reliable user experience without a constant internet connection.

CROSS-PLATFORM WEB DEPLOYMENT

The fundamental advantage of pygbag is its ability to facilitate true cross-platform deployment. A Python application compiled with pygbag can run on any device (desktop, mobile, tablet) that supports a modern web browser, dramatically increasing the potential audience and accessibility of Python-based projects without requiring platform-specific builds.

HISTORY

pygbag was developed by pmp-p to address a growing need for a streamlined method to deploy Pygame projects directly to the web. Before its advent, achieving this often involved complex manual setups with Emscripten and Pyodide, which presented a steep learning curve. Since its initial release, pygbag has steadily gained popularity as a more accessible and user-friendly alternative. Its development continues with a focus on enhancing compatibility with a broader range of Python modules, improving build times, and optimizing the performance of WebAssembly output.