WhakerKit Code

A seamless toolkit to manage dynamic websites and shared documents

Brought to you by: brigittebigi

Tree [2ab074] master /

History

HTTPS access

File	Date	Author	Commit
docs	2025-07-04	Brigitte Bigi	[6e733b] Release 1.2
sample	2025-07-04	Brigitte Bigi	[20822c] whakerkit.sample: solved problem with CustomPag...
whakerexa	2025-04-05	Brigitte Bigi	[fd84f7] Initial commit
whakerkit	2025-07-04	Brigitte Bigi	[620bba] whakerkit.nodes: A cleaner solution to deal wit...
.gitignore	2025-04-06	Brigitte Bigi	[c03596] Refactored: any file to launch the sample is lo...
AUTHORS.md	2025-05-28	Brigitte Bigi	[e5aab8] Added makedoc.py and generated the documentation.
CODE_OF_CONDUCT.md	2025-04-05	Brigitte Bigi	[fd84f7] Initial commit
CODE_STYLE_GUIDE.md	2025-04-05	Brigitte Bigi	[fd84f7] Initial commit
README.md	2025-07-04	Brigitte Bigi	[6e733b] Release 1.2
add_document.py	2025-05-23	Brigitte Bigi	[d49e73] Use of the migrated package instead of WhintPy,...
make_release.bash	2025-07-04	Brigitte Bigi	[2ab074] documented the use of twine
makedoc.py	2025-07-04	Brigitte Bigi	[6e733b] Release 1.2
pyproject.toml	2025-07-04	Brigitte Bigi	[172b15] Released 1.2
wsgi.py	2025-07-04	Brigitte Bigi	[e8f8c4] whakerkit.config: Finished to debug the way to ...

Read Me

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

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.

Contact

Contact the author by e-mail to get help or to provide help.
See: https://sppas.org/bigi/

Releases

WhakerKit - 1.0 - April, 4th, 2025

Initial version.

WhakerKit - 1.1 - May, 28th 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, 04th, 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 - development

To do list:

Manage languages in error files
Do not hard code path to "header.htm" file