Skip to main content

Workpeg SDK

Python SDK and CLI for building, packaging and submitting Workpeg Pegs.

Workpeg is a platform for developing portable applications called Pegs. Pegs can be built, packaged, distributed through the PegStore, and integrated into the broader Workpeg ecosystem.

The SDK covers:

  • Functions — serverless backend logic, Docker packaging, submitting to the registry
  • CDN — static asset uploads for Peg branding and distribution
  • UI Compiler — compile Python UI apps directly to browser JavaScript

Installation

pip install workpeg

Install locally from source:

pip install -e .

Verify:

workpeg --version

CLI

Workpeg uses a namespace-oriented CLI.

workpeg project ...
workpeg function ...
workpeg cdn ...
workpeg ui ...
Namespace Purpose
project Scaffold a whole peg — UI, function and manifest
function Create, build, run, and submit Workpeg Functions
cdn Upload public Peg assets to the CDN
ui Scaffold, compile, and serve Python Peg UI apps
workpeg --help
workpeg project --help
workpeg function --help
workpeg cdn --help
workpeg ui --help

Pegs

A peg is two halves and a manifest that binds them. Scaffold all three:

workpeg project create my-peg
Created my-peg/
  workpeg.json   namespace: my-peg
  ui/            the interface
  function/      the backend

The sections below cover each half on its own.

Full reference: docs/projects.md


Functions

Functions are the backend logic of a Peg. They are packaged as Docker images and submitted to the Workpeg Registry; Workpeg reviews each main version and publishes it.

Create a project:

workpeg function new hello
hello/
├── app/
│   ├── __init__.py
│   └── main.py
├── Dockerfile
├── requirements.txt
└── README.md

Write a function:

def main(context, payload):
    return {
        "message": "Hello from Workpeg",
        "payload": payload,
    }

Run locally (no Docker):

echo '{"context": {}, "payload": {"name": "world"}}' \
  | workpeg function runtime

Run with Docker:

workpeg function build
workpeg function run --with docker

Submit:

export WORKPEG_PK=<your-token>
workpeg function submit 1.0.0        # dev: development only, never installed
workpeg function submit main:1.0.0   # release: Workpeg reviews each version

A bare version goes to the dev branch. main is the release channel: Workpeg reviews each main version, and a main version is installed only once approved. No other branch is ever reviewed, installed or run on Workpeg.

Full reference: docs/functions.md


CDN

Upload static assets — logos, screenshots, banners — to the Peg CDN.

export WORKPEG_PK=<your-token>

# Single file
workpeg cdn submit logo.svg

# Directory
workpeg cdn submit ./assets

# With explicit CDN path
workpeg cdn submit ./assets --path brand

# Replace existing
workpeg cdn submit ./assets --overwrite

Full reference: docs/cdn.md


UI Compiler

Write Peg UI apps in Python. The SDK compiles them to vanilla JavaScript — no React, no Vue, no Python in the browser.

A peg is Python only. The SDK gives you no way to put your own JavaScript on a peg's page, or HTML that runs script: no API, flag, hook or escape hatch. The only JavaScript on a page is the SDK's own — the compiler's output, the runtime, rtc.js when the peg makes calls, and the chrome bundles (ai.js, scaffold.js, editor.js), which load from the CDN on every peg so the Workpeg team can update them everywhere at once. Every build carries a script policy naming exactly those CDN files, never all of cdn.workpeg.com. See docs/index.md.

Python App (single-page or multi-route Router)
    ↓  AST Parser
Workpeg IR (AppIR | RouterIR)
    ↓  JS Generator
app.js  +  workpeg-runtime.js  +  index.html

Scaffold, compile, and run in one command:

workpeg ui new counter
Creating counter...

  counter/main.py
  counter/dist/

  Serving  →  http://localhost:8080
  Watching →  main.py
  Stop     →  Ctrl+C

This creates a ready-to-run Counter app, compiles the Python to JavaScript, and opens a local dev server with live reload. Open http://localhost:8080 in any browser. Edit counter/main.py and save — the browser reloads automatically.

Project structure:

counter/
├── main.py              ← Router entry point
├── pages/
│   ├── __init__.py
│   ├── home.py          ← HomePage
│   └── counter.py       ← CounterPage
└── dist/
    ├── index.html
    ├── app.js
    └── workpeg-runtime.js

main.py — Router with routes declared:

from workpeg.ui import Router, Route

from pages.home import HomePage
from pages.counter import CounterPage

class Counter(Router):
    routes = [
        Route("/", HomePage),
        Route("/counter", CounterPage),
    ]

pages/counter.py — counter logic:

from workpeg.ui import App, State, Column, Text, Button, Link

class CounterPage(App):
    count = State(0)

    def increment(self):
        self.count += 1

    def build(self):
        return Column(
            Text(f"Count: {self.count}"),
            Button("Increment", on_click=self.increment),
            Link("← Home", href="/"),
        )

Options for new:

# Custom port
workpeg ui new counter --port 3000

# Scaffold and compile only, no server
workpeg ui new counter --no-serve

# Overwrite an existing project
workpeg ui new counter --force

Multi-page apps with routing:

from workpeg.ui import App, Router, Route, Column, Text, Link

class Home(App):
    def build(self):
        return Column(Text("Home"), Link("About", href="/about"))

class About(App):
    def build(self):
        return Column(Text("About"), Link("Home", href="/"))

class MyApp(Router):
    routes = [
        Route("/", Home),
        Route("/about", About),
    ]

The compiler generates a History-API-based SPA. Clicking Link widgets with internal href values updates the URL and swaps the view — no full-page reload. The back and forward buttons work correctly.

Lists work too. State fields can hold lists, and Python list operations compile to idiomatic JavaScript — literals, slicing, comprehensions, map/filter/reduce, sorted/len/in, mutation (append/pop/sort/…), and for loops. Mutating a state list re-renders automatically:

class Todos(App):
    items = State(["Buy milk", "Walk dog"])

    def add(self):
        self.items.append(f"Task {len(self.items) + 1}")   # → push, re-renders

    def build(self):
        return Column(
            Text(f"{len(self.items)} tasks"),
            Text(f"sorted: {sorted(self.items)}"),
            Text(f"with a: {[t for t in self.items if 'a' in t]}"),
            Button("Add", on_click=self.add),
        )

See the full Python→JavaScript mapping in the Core concepts docs.

Serve an existing project (with live reload):

# Pass the project directory — main.py is found automatically
workpeg ui serve counter/

# Pin a port
workpeg ui serve counter/ --port 3000

# Explicit file form (same result)
workpeg ui serve counter/main.py

# Serve a pre-built dist directory directly (no recompile)
workpeg ui serve counter/dist/

Compile only, no server:

# Pass the project directory — output goes to counter/dist/ automatically
workpeg ui build counter/

# Custom output directory
workpeg ui build counter/ --out counter/build

# Explicit file form
workpeg ui build counter/main.py

Full reference: docs/getting-started.md and the rest of the Peg UI docs (Core concepts, Widgets, Routing, Data & realtime, Styling, Examples, Reference).


Schema-based UI

For cases where you want to define UI as a data structure (for use with the Workpeg platform renderer rather than the JS compiler), the SDK also ships a schema API:

from workpeg.ui import PegApp, Page, Column, Text, Button
from workpeg.ui import State, Binding, IncrementStateAction

state = State({"counter": 0})

app = PegApp(
    title="My Peg",
    state=state,
    child=Page(
        title="Dashboard",
        child=Column(
            children=[
                Text(Binding("counter")),
                Button("Increment", action=IncrementStateAction("counter")),
            ]
        ),
    ),
)

print(app.to_schema())

Full reference: docs/schema-ui.md


Documentation

Document Contents
docs/projects.md workpeg project create: the peg layout, the manifest, naming rules, working on each half
docs/functions.md Function contract, context, runtime, Docker, publishing
docs/cdn.md CDN uploads, paths, authentication, asset structure
docs/getting-started.md Peg UI: how it works, quick start, CLI, live reload
docs/dev-install.md Test a peg before release: workpeg ui serve --fake-cloud, workpeg ui dev-clean, the separate development account
docs/core-concepts.md App, State, build(), supported Python, lists, reactivity
docs/widgets.md Widget gallery + full per-widget reference
docs/routing.md · data-realtime.md · state-components.md · styling.md Routing, data/realtime, global state, theming
docs/reference.md · examples.md Internals (IR, JS, runtime, errors) + complete examples
docs/schema-ui.md Schema-based UI, PegApp, widgets, bindings, actions
docs/architecture.md Platform overview, pipeline diagrams, design decisions

Authentication

Both function submit and cdn submit require a Workpeg token:

export WORKPEG_PK=<your-token>

Optional API override:

export WORKPEG_API_BASE=https://repo.workpeg.com

Configuration

Optional workpeg.json in your project root. namespace records the peg the project belongs to — workpeg project create writes it, workpeg function new does not:

{
  "namespace": "my-peg",
  "function": {
    "entrypoint": "app.main:main"
  },
  "runtime": {
    "default": "docker",
    "docker": {
      "port": 8000
    }
  },
  "build": {
    "image": "workpeg-fn-hello"
  },
  "cdn": {
    "assets_path": "assets"
  }
}

Roadmap

Feature Status
Function runtime (local) Available
Function runtime (Docker) Available
Function submit Available
CDN asset uploads Available
UI Compiler (Python → JS) Available
workpeg project create (scaffold UI + function + manifest) Available
workpeg ui new (scaffold + serve + live reload) Available
Schema-based UI Available
Firecracker runtime Planned
Peg packaging workflows Planned
PegStore publishing Planned
Additional widgets Planned
UI widget library Planned
Multi-page routing (History API SPA) Available
Method expressions (arithmetic, comparisons, ternary, min/max/abs) Available
Control flow — if / elif / else, for loops Available
Conditional rendering in build() (if/else → different widget trees) Available
Reusable Component classes — props, optional own State (independent per instance), per-instance handlers, callback props Available
Layout widgets — Column/Row, Center/Align (single-child), GridView (multi-child), ListView; custom single-child component slots Available
Async data loading — async/await, http.get/post/put/patch/delete, on_mount, try/except Available
http.* blocked from Workpeg domains (compile + runtime); reach the platform via the namespaced workpeg.* client Available
workpeg.get/post/put/patch/delete — Workpeg-domains-only client; resolves paths against apiBase Available
workpeg.* sends a Namespace whoami header (explicit > serving host > baked peg-namespace meta) Available
Method local variables (step = 5; self.count += step) Available
Console logging (print() → console.log()) Available
Dev error overlay (compile + runtime errors in the browser) Available
Dev install (workpeg ui serve --fake-cloud: the release build at https://<namespace>.dev.workpeg.com, from your own computer, to it only, reaching the API on the same domain as a released peg; guide) Available
Widget categories — layout / display / interactive (Flutter-style) Available
ListView with lazy, virtualized ListView.builder Available
Center layout widget Available
Image widget (object-fit, rounding, lazy loading, reactive src) Available
TextInput widget (two-way binding, on_change/on_submit, focus-preserving) Available
List support — literals, slicing, comprehensions, map/filter/reduce, mutation, for loops Available
Reactive state arrays (in-place append/sort/… re-render) Available

Contributing

External contributions follow GitLab Flow — fork, feature branch, merge request against main at https://gitlab.com/workpeg/workpeg-sdk. See CONTRIBUTING.md for the workflow, commit message format, and development setup.


License

MIT — see LICENSE.

Metadata

Release files for workpeg 0.167.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for workpeg 0.167.0
File Size Uploaded Provenance Actions
workpeg-0.167.0.tar.gz 3.0 MB Without provenance Details for workpeg-0.167.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for workpeg 0.167.0
File Interpreter ABI Platform Actions
workpeg-0.167.0-py3-none-any.whl Python 3 none any Details for workpeg-0.167.0-py3-none-any.whl

Total release size: 5.9 MB

Release files / workpeg-0.167.0.tar.gz

Download URL workpeg-0.167.0.tar.gz
Size 3.0 MB
Tags Source
SHA-256 checksum
How to use checksums
9310aea69b7639262f090159f34387dd73546b273617c6c88e6d26de55c0bf0e
BLAKE2b-256 checksum
How to use checksums
81e4a76116a9ae27537604613bbb02cead557c43ca2449d089ca200b38f3b85d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / workpeg-0.167.0-py3-none-any.whl

Download URL workpeg-0.167.0-py3-none-any.whl
Size 2.9 MB
Tags Python 3
SHA-256 checksum
How to use checksums
44f56cba6a727aef6818fbe52749098f1aec0e6049815097a7b3d8adc5cbcce0
BLAKE2b-256 checksum
How to use checksums
5f33eebff25ecfdc715f2b083f107ad2add8339ae95c413595161442de1e737b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Security for workpeg 0.167.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.167.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page