Whakerkit 2.1.1
The implementation of a WhakerKit project website.
Requires Python: >=3.9
Keywords: python, toolkit, web, html, documents, files, filters

![](./statics/whakerkit-banner.png)

# 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 >= 2.0: <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: 

```bash
> unzip WhakerKit-xxx.zip 
```

Alternatively, you can clone the repository with `git`:

```bash
> 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:

1. Create a working directory
2. Download and unzip **WhakerKit**
3. Download and unzip **Whakerexa**
4. Create a virtual environment: `python -m venv .venv`
5. Activate the virtual environment
6. 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:
```python
>>> import whakerkit
>>> whakerkit.initialize('/path/to/your/config.json')
```
*Warning: Always access the global settings with whakerkit.sg (not by importing sg directly).*
Example:
```python
>>> 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:

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

### Launch locally

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

```bash
> # 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 the local one located in the `docs` folder.

## 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 <random@developer.example.org>
```
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.

Copyright (C) 2024-2026 [Brigitte Bigi](https://sppas.org/bigi/), CNRS - <contact@sppas.org>
Laboratoire Parole et Langage, Aix-en-Provence, France

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.


## Whakerkit - 2.0 - October, 8, 2025

- Migrated to Whakerexa 1.0. This release is not compatible with earlier versions.


## Whakerkit - 2.1 - December, 21, 2025

- Migrated to Whakerexa 2.0. This release is not compatible with earlier versions.


### Whakerkit - 2.1.1 - January, 19, 2026

- Minor bug correction in Whakerexa 2.0 migration, for accessibility transfer of submit buttons.




# To do list:

- Manage languages in error files