Growing¶
Growing Pyjoyment applications.
This document explains the process of starting a Pyjoyment.Lite
prototype from scratch and growing it into a well-structured
Pyjoyment application. The final result of this guide is also
available as an example application.
Concepts¶
Essentials every Pyjoyment developer should know.
Model View Controller¶
MVC is a software architectural pattern for graphical user interface programming originating in Smalltalk-80, that separates application logic, presentation and input.
flowchart LR
Input --> Controller --> Model --> View --> Output
classDef plain fill:none,stroke:none
class Input,Output plain
A slightly modified version of the pattern moving some application logic into
the controller is the foundation of pretty much every web framework these
days, including Pyjoyment.
%%{init: {'class': {'hideEmptyMembersBox': true}}}%%
classDiagram
direction LR
class Request
class Response
class Controller
class Model
class View
Request --> Controller
Response <-- Controller
Controller <--> Model
Controller <--> View
style Request fill:none,stroke:none
style Response fill:none,stroke:none
The controller receives a request from a user, passes incoming data to the model and retrieves data from it, which then gets turned into an actual response by the view. But note that this pattern is just a guideline that most of the time results in cleaner more maintainable code, not a rule that should be followed at all costs.
REpresentational State Transfer¶
REST is a software architectural style for distributed hypermedia systems
such as the web. While it can be applied to many protocols it is most
commonly used with HTTP these days. In REST terms, when you are opening a URL
like http://mojolicious.org/foo with your browser, you are basically
asking the web server for the HTML representation of the
http://mojolicious.org/foo resource.
sequenceDiagram
participant C as Client
participant S as Server
C->>S: http://mojolicious.org/foo
S-->>C: #lt;html#gt;Mojo rocks!#lt;/html#gt;
The fundamental idea here is that all resources are uniquely addressable with URLs and every resource can have different representations such as HTML, RSS or JSON. User interface concerns are separated from data storage concerns and all session state is kept client-side.
sequenceDiagram
participant B as Browser
participant S as Web Server
B->>S: PUT /foo<br/>Hello World!
S-->>B: 201 CREATED
B->>S: GET /foo
S-->>B: 200 OK<br/>Hello World!
B->>S: DELETE /foo
S-->>B: 200 OK
While HTTP methods such as PUT, GET and DELETE are not directly
part of REST they go well with it and are commonly used to manipulate
resources.
Sessions¶
HTTP was designed as a stateless protocol, web servers don’t know anything about previous requests, which makes user-friendly login systems tricky. Sessions solve this problem by allowing web applications to keep stateful information across several HTTP requests.
GET /login?user=sebastian&pass=s3cret HTTP/1.1
Host: mojolicious.org
HTTP/1.1 200 OK
Set-Cookie: sessionid=987654321
Content-Length: 16
Hello sebastian.
GET /protected HTTP/1.1
Host: mojolicious.org
Cookie: sessionid=987654321
HTTP/1.1 200 OK
Set-Cookie: sessionid=987654321
Content-Length: 22
Hello again sebastian.
Traditionally all session data was stored on the server-side and only session IDs were exchanged between browser and web server in the form of cookies.
Set-Cookie: session=hmac-sha256(base64(json($session)))
In Pyjoyment however we are taking this concept one step further by
storing everything JSON serialized and Base64 encoded in HMAC-SHA256 signed
cookies, which is more compatible with the REST philosophy and reduces
infrastructure requirements.
Test-Driven Development¶
TDD is a software development process where the developer starts writing
failing test cases that define the desired functionality and then moves on to
producing code that passes these tests. There are many advantages such as
always having good test coverage and code being designed for testability,
which will in turn often prevent future changes from breaking old code. Much
of Pyjoyment was ported using TDD, with the tests of Mojolicious
first.
Prototype¶
One of the main differences between Pyjoyment and other web
frameworks is that it also includes Pyjoyment.Lite, a micro web
framework optimized for rapid prototyping.
Differences¶
You likely know the feeling, you’ve got a really cool idea and want to try it
as quickly as possible, that’s exactly why Pyjoyment.Lite applications
don’t need more than a single file.
myapp.py # Templates and even static files can be inlined
Full Pyjoyment applications on the other hand are much closer to a
well organized Python project to maximize maintainability.
treeView-beta
my_app ## Application directory
MyApp ## Application package
__init__.py ## Application class
__main__.py ## Application script
Controller ## Controller package
Example.py ## Controller class
my_app.yml ## Configuration file
pyproject.toml ## Project file with the dependencies
AGENTS.md ## Guide of coding agents
CLAUDE.md ## Import of AGENTS.md for Claude Code
t ## Test directory
basic.py ## Random test
public ## Static file directory (served automatically)
assets ## Static assets created by bundlers
*generated assets*
index.html ## Static HTML file
templates ## Template directory
layouts ## Template directory for layouts
default.html.ep ## Layout template
example ## Template directory for "Example" controller
welcome.html.ep ## Template for "welcome" action
Both application skeletons can be automatically generated with the commands
Pyjoyment.Command.Author.generate.lite_app and
Pyjoyment.Command.Author.generate.app.
$ pyjo generate lite-app myapp.py
$ pyjo generate app MyApp
Feature-wise both are almost equal, the only real differences are organizational, so each one can be gradually transformed into the other.
Foundation¶
We start our new application with a single executable Python script.
$ mkdir myapp
$ cd myapp
$ touch myapp.py
$ chmod 744 myapp.py
This will be the foundation for our login manager example application.
#!/usr/bin/env python
from Pyjoyment.Lite import *
@get('/')
def index(c):
c.render(text='Hello World!')
app.start()
The built-in development web server makes working on your application a lot of fun thanks to automatic reloading.
$ pyjo-reload ./myapp.py
Web application available at http://127.0.0.1:3000
Just save your changes and they will be automatically in effect the next time you refresh your browser.
A bird’s-eye view¶
It all starts with an HTTP request like this, sent by your browser.
GET / HTTP/1.1
Host: localhost:3000
Once the request has been received by the web server through the event loop,
it will be passed on to Pyjoyment, where it will be handled in a few
simple steps.
Check if a static file exists that would meet the requirements.
Try to find a route that would meet the requirements.
Dispatch the request to this route, usually reaching one or more actions.
Process the request, maybe generating a response with the renderer.
Return control to the web server, and if no response has been generated yet, wait for a non-blocking operation to do so through the event loop.
With our application the router would have found an action in step 2, and rendered some text in step 4, resulting in an HTTP response like this being sent back to the browser.
HTTP/1.1 200 OK
Content-Length: 12
Hello World!
Model¶
In Pyjoyment we consider web applications simple frontends for
existing business logic. That means Pyjoyment is by design entirely
model layer agnostic, and you just use whatever Python modules you like
most.
$ mkdir -p MyApp/Model
$ touch MyApp/Model/Users.py
$ chmod 644 MyApp/Model/Users.py
Our login manager will use a plain old Python class abstracting away all
logic related to matching usernames and passwords. The name
MyApp.Model.Users is an arbitrary choice, and is simply used to make the
separation of concerns more visible.
from Pyjo.Util import secure_compare
USERS = {'joel': 'las3rs', 'marcus': 'lulz', 'sebastian': 'secr3t'}
class Users:
def check(self, user, password):
# Success
if user in USERS and secure_compare(USERS[user], password):
return True
# Fail
return False
A simple helper can be registered with the function helper of
Pyjoyment.Lite to make our model available to all actions and
templates. The directory of a script is the first one of sys.path, so
the script imports the model without any setup.
#!/usr/bin/env python
from Pyjoyment.Lite import *
from MyApp.Model.Users import Users
# Helper to store our model object
users = Users()
helper('users', lambda c: users)
# /?user=sebastian&pass=secr3t
@any('/')
def index(c):
# Query parameters
user = c.param('user') or ''
password = c.param('pass') or ''
# Check password
if c.users().check(user, password):
return c.render(text=f'Welcome {user}.')
# Failed
c.render(text='Wrong username or password.')
app.start()
The method param() is used
to access query parameters, POST parameters, file uploads and route
placeholders, all at once.
Testing¶
In Pyjoyment we take testing very seriously and try to make it a
pleasant experience.
$ mkdir t
$ touch t/login.py
$ chmod 644 t/login.py
Pyjo.Test.Pyjo is a scriptable HTTP user agent designed specifically
for testing, with many fun state-of-the-art features such as CSS selectors
based on Pyjo.DOM.
import Pyjo.File
import Pyjo.Test.Pyjo
from Pyjo.Test import *
import re
# Include application
script = Pyjo.File.curfile().dirname().sibling('myapp.py')
# Allow 302 redirect responses
t = Pyjo.Test.Pyjo.new(script)
t.ua.max_redirects = 1
# Test if the HTML login form exists
(
t.get_ok('/')
.status_is(200)
.element_exists('form input[name="user"]')
.element_exists('form input[name="pass"]')
.element_exists('form input[type="submit"]')
)
# Test login with valid credentials
(
t.post_ok('/', form={'user': 'sebastian', 'pass': 'secr3t'})
.status_is(200)
.text_like('html body', re.compile(r'Welcome sebastian'))
)
# Test accessing a protected page
t.get_ok('/protected').status_is(200).text_like('a', re.compile(r'Logout'))
# Test if HTML login form shows up again after logout
(
t.get_ok('/logout')
.status_is(200)
.element_exists('form input[name="user"]')
.element_exists('form input[name="pass"]')
.element_exists('form input[type="submit"]')
)
done_testing()
Your application won’t pass these tests, but from now on you can use them to check your progress.
$ pyjo-prove -l
$ pyjo-prove -l t/login.py
$ pyjo-prove -l -v t/login.py
Or perform quick requests right from the command line with
Pyjoyment.Command.get.
$ ./myapp.py get /
Wrong username or password.
$ ./myapp.py get -v '/?user=sebastian&pass=secr3t'
GET /?user=sebastian&pass=secr3t HTTP/1.1
Accept-Encoding: gzip
Host: 127.0.0.1:59472
User-Agent: Pyjoyment (Python)
HTTP/1.1 200 OK
Content-Length: 18
Content-Type: text/html;charset=UTF-8
Date: Sun, 18 Oct 2026 16:24:42 GMT
Server: Pyjoyment (Python)
Welcome sebastian.
State keeping¶
Sessions in Pyjoyment pretty much just work out of the box once you
start using the method session(),
there is no setup required, but we suggest setting a more secure passphrase
with secrets.
app.secrets = ['Pyjoyment rocks']
This passphrase is used by the HMAC-SHA256 algorithm to make signed cookies tamper resistant and can be changed at any time to invalidate all existing sessions.
c.session(user='sebastian')
user = c.session('user')
By default all sessions expire after one hour, for more control you can use
the expiration session value to set an expiration date in seconds from
now.
c.session(expiration=3600)
And the whole session can be deleted by using the expires session value
to set an absolute expiration date in the past.
c.session(expires=1)
For data that should only be visible on the next request, like a
confirmation message after a 302 redirect performed with the helper
redirect_to of Pyjoyment.Plugin.DefaultHelpers, you can use the
flash, accessible through its helper flash.
c.flash(message='Everything is fine.')
c.redirect_to('goodbye')
Just remember that all session data gets serialized with Pyjo.JSON and
stored in HMAC-SHA256 signed cookies, which usually have a 4096 byte
(4KiB) limit, depending on browser.
Final prototype¶
A final myapp.py prototype passing all of the tests above could look like
this.
#!/usr/bin/env python
"""
__DATA__
@@ index.html.ep
% layout('default')
%= form_for('index', begin
% if param('user'):
<b>Wrong name or password, please try again.</b><br>
% end
Name:<br>
%= text_field('user')
<br>Password:<br>
%= password_field('pass')
<br>
%= submit_button('Login')
% end)
@@ protected.html.ep
% layout('default')
% if (msg := flash('message')):
<b><%= msg %></b><br>
% end
Welcome <%= session('user') %>.<br>
%= link_to('Logout', 'logout')
@@ layouts/default.html.ep
<!DOCTYPE html>
<html>
<head><title>Login Manager</title></head>
<body><%= content() %></body>
</html>
"""
from Pyjoyment.Lite import *
from MyApp.Model.Users import Users
# Make signed cookies tamper resistant
app.secrets = ['Pyjoyment rocks']
users = Users()
helper('users', lambda c: users)
# Main login action
@any('/', 'index')
def index(c):
# Query or POST parameters
user = c.param('user') or ''
password = c.param('pass') or ''
# Check password and render "index.html.ep" if necessary
if not c.users().check(user, password):
return c.render()
# Store username in session
c.session(user=user)
# Store a friendly message for the next page in flash
c.flash(message='Thanks for logging in.')
# Redirect to protected page with a 302 response
c.redirect_to('protected')
# Make sure user is logged in for actions in this group
with group():
@under
def logged_in(c):
# Redirect to main page with a 302 response if user is not logged in
if c.session('user'):
return True
c.redirect_to('index')
return None
# A protected page auto rendering "protected.html.ep"
get('/protected')
# Logout action
@get('/logout')
def logout(c):
# Expire and in turn clear session automatically
c.session(expires=1)
# Redirect to main page with a 302 response
c.redirect_to('index')
app.start()
And the directory structure should be looking like this now.
treeView-beta
myapp
myapp.py
MyApp
Model
Users.py
t
login.py
Our templates are using quite a few features of the renderer, Rendering explains them all in great detail.
Well-structured application¶
Due to the flexibility of Pyjoyment there are many variations of the
actual growing process, but this should give you a good overview of the
possibilities.
Inflating templates¶
All templates and static files inlined in the __DATA__ section of the
docstring can be automatically turned into separate files in the
templates and public directories with the command
Pyjoyment.Command.Author.inflate.
$ ./myapp.py inflate
Those directories have a higher precedence, so inflating can also be a great way to allow your users to customize their applications.
Simplified application class¶
This is the heart of every full Pyjoyment application and always gets
instantiated during server startup.
$ touch MyApp/__init__.py
$ chmod 644 MyApp/__init__.py
We will start by extracting all actions from myapp.py and turn them into
simplified hybrid routes in the Pyjoyment.Routes router, none of the
actual action code needs to be changed. A route is a decorator of its action
here too.
import Pyjoyment
from MyApp.Model.Users import Users
class MyApp(Pyjoyment.object):
def startup(self):
self.secrets = ['Pyjoyment rocks']
users = Users()
self.helper('users', lambda c: users)
r = self.routes
@r.any('/', 'index')
def index(c):
user = c.param('user') or ''
password = c.param('pass') or ''
if not c.users().check(user, password):
return c.render()
c.session(user=user)
c.flash(message='Thanks for logging in.')
c.redirect_to('protected')
@r.under
def logged_in(c):
if c.session('user'):
return True
c.redirect_to('index')
return None
logged_in.get('/protected')
@r.get('/logout')
def logout(c):
c.session(expires=1)
c.redirect_to('index')
new = MyApp.new
object = MyApp
The startup method gets called right after instantiation and is the place
where the whole application gets set up. Since full Pyjoyment
applications can use nested routes they have no need for group blocks.
Simplified application script¶
myapp.py itself can now be turned into a simplified application script
to allow running tests again.
#!/usr/bin/env python
import Pyjoyment.Commands
# Start command line interface for application
Pyjoyment.Commands.start_app('MyApp')
And the directory structure of our hybrid application should be looking like this.
treeView-beta
myapp
myapp.py
MyApp
__init__.py
Model
Users.py
t
login.py
templates
layouts
default.html.ep
index.html.ep
protected.html.ep
Controller class¶
Hybrid routes are a nice intermediate step, but to maximize maintainability it makes sense to split our action code from its routing information.
$ mkdir MyApp/Controller
$ touch MyApp/Controller/Login.py
$ chmod 644 MyApp/Controller/Login.py
Once again the actual action code does not need to change, we just rename
c to self since the controller is now the invocant.
import Pyjoyment.Controller
class MyApp_Controller_Login(Pyjoyment.Controller.object):
def index(self):
user = self.param('user') or ''
password = self.param('pass') or ''
if not self.users().check(user, password):
return self.render()
self.session(user=user)
self.flash(message='Thanks for logging in.')
self.redirect_to('protected')
def logged_in(self):
if self.session('user'):
return True
self.redirect_to('index')
return None
def logout(self):
self.session(expires=1)
self.redirect_to('index')
object = MyApp_Controller_Login
All Pyjoyment.Controller controllers are plain old Python classes and
get instantiated on demand. The module names its class with object, as
the modules of Pyjoyment do.
Application class¶
The application class MyApp/__init__.py can now be reduced to model and
routing information.
import Pyjoyment
from MyApp.Model.Users import Users
class MyApp(Pyjoyment.object):
def startup(self):
self.secrets = ['Pyjoyment rocks']
users = Users()
self.helper('users', lambda c: users)
r = self.routes
r.any('/', 'index').to('login#index')
logged_in = r.under('/').to('login#logged_in')
logged_in.get('/protected').to('login#protected')
r.get('/logout').to('login#logout')
new = MyApp.new
object = MyApp
The router allows many different route variations, Routing explains them all in great detail.
Templates¶
Templates are our views, and usually bound to controllers, so they need to be moved into the appropriate directories.
$ mkdir templates/login
$ mv templates/index.html.ep templates/login/index.html.ep
$ mv templates/protected.html.ep templates/login/protected.html.ep
Script¶
Finally myapp.py can be moved into the package of the application as
MyApp/__main__.py, as Pyjoyment.Command.Author.generate.app has
it.
$ mv myapp.py MyApp/__main__.py
The script stays the same, and python -m MyApp starts it, as -m puts
the current directory, the one of the project, on sys.path.
import Pyjoyment.Commands
# Start command line interface for application
Pyjoyment.Commands.start_app('MyApp')
$ python -m MyApp daemon
Web application available at http://127.0.0.1:3000
Simplified tests¶
Full Pyjoyment applications are a little easier to test, so
t/login.py can be simplified.
import Pyjo.Test.Pyjo
from Pyjo.Test import *
import re
t = Pyjo.Test.Pyjo.new('MyApp')
t.ua.max_redirects = 1
with subtest('Test login workflow'):
(
t.get_ok('/')
.status_is(200)
.element_exists('form input[name="user"]')
.element_exists('form input[name="pass"]')
.element_exists('form input[type="submit"]')
)
(
t.post_ok('/', form={'user': 'sebastian', 'pass': 'secr3t'})
.status_is(200)
.text_like('html body', re.compile(r'Welcome sebastian'))
)
t.get_ok('/protected').status_is(200).text_like('a', re.compile(r'Logout'))
(
t.get_ok('/logout')
.status_is(200)
.element_exists('form input[name="user"]')
.element_exists('form input[name="pass"]')
.element_exists('form input[type="submit"]')
)
done_testing()
And our final directory structure should be looking like this.
treeView-beta
myapp
MyApp
__init__.py
__main__.py
Controller
Login.py
Model
Users.py
t
login.py
templates
layouts
default.html.ep
login
index.html.ep
protected.html.ep
Test-driven development takes a little getting used to, but can be a very powerful tool.
More¶
You can continue with Guides now or take a look at the Mojolicious wiki, which contains a lot more documentation and examples by many different authors.
Ported from Mojolicious::Guides::Growing of Mojolicious 9.49.