Guides

The Pyjoyment Guide to the Galaxy.

Don’t panic!

The Pyjoyment documentation is structured into three parts. The tutorial everyone starts with, the guides that explain all major features in detail, and the API reference listing all available classes.

Some parts of the documentation only use the Pyjoyment.Lite micro web framework for examples, but that’s merely a convenience for the reader. Almost all features are exactly the same for full Pyjoyment applications.

Basics

Learning Python

If you are new to Python, we recommend the Python tutorial for an introduction to the language, which is part of the documentation of Python itself. For more books and documentation, check out the beginner’s guide of python.org.

Learning Web Technologies

All web development starts with HTML, CSS and JavaScript, to learn the basics we recommend the Mozilla Developer Network. And if you want to know more about how browsers and web servers actually communicate, there’s also a very nice introduction to HTTP.

Conventions

Modern Python

Pyjoyment uses a modern subset of Python exclusively, Python 3.12 and newer, and therefore all documentation assumes that the modules an example uses are imported, even if examples don’t specifically mention it.

import Pyjo.IOLoop
import Pyjo.UserAgent

Some modules, like Pyjoyment.Lite and Pyjo, will import the functions of their examples for you with from Pyjoyment.Lite import * and from Pyjo import *.

Type hints

Pyjoyment is annotated with type hints, which pyright checks in strict mode. They are left out of all examples for clarity, so the code of an example is the same with or without them.

Variable names

For brevity and clarity, example variables will reflect the type of data the API uses. For instance, data or chars to distinguish whether it is encoded bytes or decoded characters in a str, boolean if the value just indicates true or false, c to denote a Pyjoyment.Controller object, or app to denote the application object.

When the return value of a method is the object it was called on, this will be represented by using the same variable name in the example. This does not mean the return value needs to be assigned back to it, but indicates that further methods can be called in a chain, as the fluent interfaces of Pyjo.Base do.

Tutorial

Tutorial

A fast and fun way to get started developing web applications with Pyjoyment. The tutorial introduces the Pyjoyment.Lite micro web framework, which is only a thin wrapper around the full web framework. The simplified notation introduced in the tutorial is commonly used throughout the guides and is therefore considered a prerequisite, you should definitely take a look!

Guides

Growing

Starting a Pyjoyment.Lite prototype from scratch and growing it into a well-structured Pyjoyment application.

Routing

Simple and fun introduction to the Pyjoyment router.

Mounting

Running the applications of other frameworks, of Python, PHP, CGI and AWS Lambda, next to the routes of a Pyjoyment application.

Django

Serving a project of Django with the servers of Pyjoyment, in the place of gunicorn or uvicorn.

From gunicorn

The options, the worker model and the habits of a deployment of gunicorn in the pre-forking server.

Rendering

Generating content with the Pyjoyment renderer.

Testing

Powerful yet elegant testing techniques and tools for Pyjoyment and other web applications.

Cookbook

Cooking with Pyjoyment, recipes for every taste.

One-liners

Fun and useful one-liners with Pyjo, for web pages, JSON APIs, JSON and YAML files and the manifests of Kubernetes.

Contributing

Become a part of the ongoing Pyjoyment development.

FAQ

Answers to the most frequently asked questions.

Highlights

Pyjoyment and Pyjoyment.Lite are the sum of many parts, built on top of the Pyjo web development toolkit. Small building blocks that can be used independently for all kinds of applications, these are the most prominent ones.

Pyjo.UserAgent

Full featured non-blocking I/O HTTP and WebSocket user agent.

Pyjo.DOM

Very fun and minimalistic HTML/XML DOM parser with CSS selector support.

Pyjo.JSON

Minimalistic JSON implementation that just works.

Pyjo.Server.Daemon

Full featured, highly portable non-blocking I/O HTTP and WebSocket server, with self-restart support through Pyjo.Server.Reload, perfect for development and testing.

Pyjo.Server.Prefork

Full featured, UNIX optimized, preforking non-blocking I/O HTTP and WebSocket server with support for zero downtime software upgrades (hot deployment) through Pyjo.Server.Hot.

Pyjo.Server.Prethread

The same server with threads for its worker processes, which run at the same time on a free-threaded Python.

Pyjo.Server.CGI, Pyjo.Server.WSGI, Pyjo.Server.ASGI

Transparent CGI, WSGI and ASGI support out of the box.

Pyjo.Server.FastCGI, Pyjo.Server.Lambda

FastCGI behind a web server, and the event functions of AWS Lambda.

Pyjo.Server.Stdio

A protocol on the standard input and output, as the transport stdio of MCP or LSP.

Pyjo.IOLoop

A minimalistic event loop with support for multiple reactor backends, on the event loop of asyncio by default.

Pyjo.Template

Very Python-ish and minimalistic template system.

Pyjoyment.Plugin.PyRenderer

Templates of the template strings of Python, with auto-escaping and without a template language.

Pyjo.Test.Pyjo

Testing toolkit for web applications.

Pyjo

Fun one-liners using everything above.

API

This is the class hierarchy of the Pyjoyment distribution.

More

A lot more documentation and examples by many different authors can be found in the Mojolicious wiki, which Pyjoyment is ported from.

Ported from Mojolicious::Guides of Mojolicious 9.49.