WhakerKit Overview

This is the implementation of the WhakerKit library. WhakerKit is a versatile toolkit for building websites with both static and dynamic HTML pages. It was developed by Brigitte Bigi, CNRS.

WhakerKit is a seamless toolkit for managing dynamic websites and shared documents.

Use cases

WhakerKit is the ideal toolkit if you want to:

create a dynamic website with a few static pages,
share documents easily without having to manage a database,
restrict access to parts of your website using an existing LDAP directory,
keep full control of your HTML content without the overhead of a heavy framework like Django.

It’s designed for developers who want a lightweight, flexible solution with minimal configuration.

It’s easy to deploy, easy to understand, and highly adaptable.

WhakerKit provides easy management of public and authenticated access and simplifies document sharing in collaborative environments. It is based on the following technologies:

Python >= 3.9
(optional) PyJWT and ldap3 for authentication (install with pip)
WhakerPy >= 1.0: https://whakerpy.sourceforge.io (install with pip)
Whakerexa >= 0.7: https://whakerexa.sourceforge.io (download and unzip)
HTML5, CSS4, and JavaScript technologies

Why WhakerKit is Unique?

WhakerKit fills a real gap in the Python ecosystem by offering an all-in-one solution that sits between a static site generator, a lightweight CMS, and a micro-framework. Unlike general-purpose frameworks or static tools, WhakerKit provides:

Native document management based on files and folders, without requiring a database.
Seamless integration of static and dynamic HTML—flexible enough for both classic websites and collaborative applications.
Direct, transparent configuration via JSON files, enabling full control and easy customization.
Lightweight deployment that works equally well for local web applications and server-based websites.
No hidden abstraction layers—developers always have a clear view of what happens at each stage.

To our knowledge, there is no other open-source Python project combining these features in such a streamlined, transparent, and file-oriented way.

In summary: WhakerKit is an original toolkit, designed for developers and researchers who need simplicity, flexibility, and full control over their web applications—without the constraints of traditional frameworks.

Technical approach

The Apache server uses uWSGI to run a Python application, handled by the local wsgi.py file. The WSGI server looks for an application(environ, start_response) function, which is called whenever a request is received (via POST, GET, or any other method). This file defines a function that is an instance of the WSGIApplication class. It is instantiated with the following parameters:

The default page name is index.html
Page descriptions are stored in a .json file

Pages are dynamically generated using the WhakerPy library and are returned as either HTML or JSON, depending on the request. The dynamic HTML pages fall into two categories:

Fully dynamically generated pages
Partially dynamically generated pages

Partially dynamic pages are described in the JSON configuration file. The <head>, header, menu, and footer of these HTML pages are automatically added to a static HTML body located in the html folder. The dynamic parts are generated by Python classes.

Authors and contributors

See the accompanying file AUTHORS.md.

Get and install WhakerKit

Get it from its repository https://sourceforge.net/projects/whakerkit/, and get documentation https://whakerkit.sourceforge.io.

Download the latest ".zip" from the web page and unpack it:

> unzip WhakerKit-xxx.zip

Alternatively, you can clone the repository with git:

> git clone https://git.code.sf.net/p/whakerkit/code whakerkit-code
> python -m pip install .

Why WhakerKit?

WhakerKit was developed to address real-world needs for flexibility, control, and simplicity when building web applications and collaborative websites—both online and in local environments. While established frameworks such as Django or Flask are robust and widely adopted, WhakerKit offers a different philosophy, designed for projects where transparency, minimalism, and direct control are required.

Key Advantages

Lightweight and Transparent

WhakerKit avoids unnecessary abstraction layers. The entire web request/response cycle is easy to follow, debug, and customize. There is no “magic”: each step is explicit, making the codebase accessible and maintainable.

Full Control

You maintain complete control over the site’s structure, file management, and dynamic content generation. There are no imposed conventions or hidden behaviors—ideal for use cases that do not fit the patterns of large frameworks.

Minimal Dependencies

The toolkit requires only Python and a few well-documented libraries. There is no ORM, no complex plugin system, and no heavy runtime environment. This keeps deployments simple and reduces maintenance overhead.

Natural File Handling

WhakerKit makes document sharing and file management straightforward. The system is particularly suited for collaborative platforms and projects that rely on direct file access, rather than database-driven storage.

Perfect for Research, Teaching, and Custom Projects

Because of its transparency and modularity, WhakerKit is a strong choice for scientific projects, reproducible research, and teaching. Students and developers can clearly see and adapt the full process, from request handling to dynamic HTML generation.

Flexible Deployment

WhakerKit can be used for traditional websites, collaborative intranets, or local web applications via the embedded WhakerPy server—no need for complex server stacks or third-party hosting requirements.

Philosophy

WhakerKit is not intended to replace comprehensive frameworks such as Django or Flask. Those frameworks are excellent for large-scale applications, projects requiring extensive plugin ecosystems, or out-of-the-box administration features. Instead, WhakerKit focuses on transparency, direct control, and a streamlined experience, especially for specialized, internal, or research-oriented web projects.

In summary:

If your priority is a lightweight, adaptable toolkit that gives you full control over your web application—with minimal dependencies and maximum transparency—WhakerKit is an ideal solution. For many targeted use cases, it offers a unique and effective alternative to the mainstream web frameworks.

Creating a Custom Website

Starting a New Project

Required contents:

pyproject.toml: Python configuration file used to install dependencies
whakerkit: Contains the JavaScript package and the Python source code that handles requests, including headers, status codes, and content
whakerexa: CSS and JS

Optional content:

add_document.py: Script to add documents to the uploads folder

Get it:

Create a working directory
Download and unzip WhakerKit
Download and unzip Whakerexa
Create a virtual environment: python -m venv .venv
Activate the virtual environment
Run: python -m pip install . — this reads pyproject.toml and installs dependencies

Files and folders required to launch the sample:

wsgi.py: entry point for the application
whakerkit/whakerkit.json: General configuration file for any website
sample: folder with python source code
sample/sample.json: General configuration file for any website used by Whakerkit and list of dynamic pages for the sample used by WhakerPy
sample/statics: Contains static files such as icons, images, and CSS for the sample
sample/html: Contains all static components of the HTML pages of the sample
sample/uploads: Contains the document database. This folder should never be modified manually.

Editing the Sample

WhakerKit comes with a sample directory to help you get started. All the sample files are well-commented to help developers understand and adapt the logic to their own use case.

The whakerkit package also includes an error folder containing HTML error pages. Edit these files to customize error messages. The package also includes default icons that can be replaced as long as the file names remain the same.

Starts by editing the sample.json to configure your project, then edit the wsgi.py file. Since version 1.1, you must explicitly initialize WhakerKit with your configuration file in your project, after importing the package. It is usually done in the wsgi.py file:

>>> import whakerkit
>>> whakerkit.initialize('/path/to/your/config.json')

Warning: Always access the global settings with whakerkit.sg (not by importing sg directly). Example:

>>> import whakerkit
>>> whakerkit.sg.path

If you access 'sg' before calling initialize(), it will only use the default settings, not your custom configuration.

bakery.py

This file contains the CustomWebData class, which inherits from WebSiteData. It parses sample.json, stores data, and manages the "bakery" system — a concept from WhakerPy used to dynamically generate page content.

pages_resp.py

This file implements the CustomPagesResponse class. It is invoked when a requested page name is listed in sample.json. It reuses the same head, header, navigation bar, and footer, while changing only the main content, which is defined in a static HTML file.

head_node.py

Allows adding content to the <head> tag of dynamically created HTML files. You can include <meta>, <link>, or <script> elements.

nav_node.py

Allows defining the entire <nav> content of dynamically created HTML files.

Development and Debugging

Edit the file wsgi.py to adapt it to your project content. To enable debugging, modify the logging configuration, i.e. comment/uncomment the following lines:

LOG_LEVEL = 1    # Debug level
# LOG_LEVEL = 15   # Info level

Launch locally

Under any linux version or macOS, launch locally the application with:

> # install required external libraries:
> python3 -m pip install pycryptodome --break-system-packages
> python -m pip install uwsgi
> # launch with uwsgi service:
> uwsgi --http :9090 --wsgi-file wsgi.py

Then open http://localhost:9090/

Projects based on WhakerKit

The intranet of "Laboratoire Parole et Langage", Aix-en-Provence, France
https://auto-cuedspeech.org/
https://sppas.org/

Help

WhakerKit Documentation

See https://whakerkit.sourceforge.io or install the local one. Starting from Whakerexa 1.0, browsing the HTML documentation of WhakerKit requires running an HTTP server. This can easily be done with uWSGI (for instance, using WSL under Windows):

# Install the required external libraries:
python3 -m pip install pycryptodome --break-system-packages
python3 -m pip install uwsgi
# Launch the HTTP service:
uwsgi --http :9090 --wsgi-file wsgi.py

An example of such wsgi.py file is available in the docs folder.

uWSGI install

Windows : https://stackoverflow.com/questions/71092850/how-to-install-uwsgi-on-windows
macOS : python -m pip install wsgi
linux : python3 -m pip install pyuwsgi (it is installed in $HOME/.local/bin)

Deploy

Deploying WhakerKit on a production server depends on your hosting provider. A typical deployment uses an Apache server with uWSGI and Python support.

Help / How to contribute

If you want to report a bug, please send an e-mail to the author. Any and all constructive comments are welcome.

If you plan to contribute to the code, please read carefully and agree both the code of conduct and the code style guide. If you are contributing code or documentation to the WhakerPy project, you are agreeing to the DCO certificate http://developercertificate.org. Copy/paste the DCO, then you just add a line saying:


Signed-off-by: Random J Developer

Send this file by e-mail to the author.

License/Copyright

See the accompanying LICENSE.md and AUTHORS.md files for the full list of contributors.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Releases

WhakerKit - 1.0 - April, 4, 2025

Initial version.

WhakerKit - 1.1 - May, 28 2025

Migration from WhakerKit 1.0: - 'whakerkit.json' must now be outside the whakerkit package folder. - You must call 'whakerkit.initialize()' before any use of 'whakerkit.sg'. - Never use 'from whakerkit import sg', always use 'import whakerkit' instead.

Whakerkit - 1.2 - July, 4, 2025

Do not hard code path to "footer.htm" file in WhakerKitFooterNode
Solved problems of path in settings to get access to whakerkit statics content

Whakerkit - 1.3 - July, 18, 2025

Do not hard code path to "header.htm" file in WhakerKitHeaderNode
Setting language is now properly managed through 'get_msg()' function, allowing to get the messages from gettext in the expected language.