cherrypy-foundation 1.0.0a16__tar.gz → 1.0.0a17__tar.gz

{cherrypy_foundation-1.0.0a16 → cherrypy_foundation-1.0.0a17}/.gitignore

@@ -8,3 +8,7 @@ coverage.xml
 pytestdebug.log
 xunit
 xunit.xml
+/.pybuild
+/build
+/debian/tmp
+/debian/debhelper-build-stamp

{cherrypy_foundation-1.0.0a16 → cherrypy_foundation-1.0.0a17}/.gitlab-ci.yml

@@ -26,6 +26,9 @@ isort:
 djlint:
   <<: *tox
 
+doc:
+  <<: *tox
+
 py3:
   <<: *tox
   artifacts:

{cherrypy_foundation-1.0.0a16/src/cherrypy_foundation.egg-info → cherrypy_foundation-1.0.0a17}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: cherrypy-foundation
-Version: 1.0.0a16
-Summary: CherryPy Foundation
+Version: 1.0.0a17
+Summary: Cherrypy-foundation
 Author-email: Patrik Dufresne <patrik@ikus-soft.com>
 License: GPLv3
 Project-URL: Homepage, https://gitlab.com/ikus-soft/cherrypy-foundation
@@ -48,12 +48,24 @@ Dynamic: license-file
 <a href="https://sonar.ikus-soft.com/dashboard?id=cherrypy-foundation"><img alt="Coverage" src="https://sonar.ikus-soft.com/api/project_badges/measure?project=cherrypy-foundation&metric=coverage"></a>
 </p>
 
-This project provides a collection of reusable utilities that simplify
-building web applications with CherryPy. It offers built-in integrations
-with SQLAlchemy for database access, Jinja2 for templating, WTForms for
-form handling, and Bootstrap for UI components, helping streamline
-application development.
+Cherrypy-foundation is a comprehensive toolkit that accelerates web application development with CherryPy. It provides a curated collection of utilities and integrations that handle common web development tasks, allowing you to focus on building your application's unique features.
 
-# Usage
+## What's Included
 
-TODO
+- **Database Integration**: Seamless SQLAlchemy integration for database operations
+- **Template Engine**: Jinja2 and JinjaX support for flexible, component-based templating
+- **Form Handling**: Enhanced WTForms integration with automatic validation and Bootstrap rendering
+- **URL Management**: Flexible URL generation with `url_for` utility
+- **Error Handling**: Smart error pages that adapt to response content type (HTML, JSON, plain text)
+- **UI Components**: Bootstrap-ready components for rapid interface development
+
+## Who Is This For?
+
+Cherrypy-foundation is designed for developers who:
+
+- Want to build modern web applications with CherryPy without reinventing the wheel
+- Need a lightweight alternative to full-stack frameworks while maintaining flexibility
+- Prefer convention over configuration but value customization options
+- Want battle-tested components that integrate seamlessly with CherryPy's architecture
+
+This documentation will guide you through all available features, from basic utilities to advanced integrations, with practical examples to help you get started quickly.

cherrypy_foundation-1.0.0a17/README.md

@@ -0,0 +1,30 @@
+# Cherrypy-foundation
+
+<p align="center">
+<a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-GPL--3.0-orange"></a>
+<a href="https://gitlab.com/ikus-soft/cherrypy-foundation/pipelines"><img alt="Build" src="https://gitlab.com/ikus-soft/cherrypy-foundation/badges/master/pipeline.svg"></a>
+<a href="https://sonar.ikus-soft.com/dashboard?id=cherrypy-foundation"><img alt="Quality Gate" src="https://sonar.ikus-soft.com/api/project_badges/measure?project=cherrypy-foundation&metric=alert_status"></a>
+<a href="https://sonar.ikus-soft.com/dashboard?id=cherrypy-foundation"><img alt="Coverage" src="https://sonar.ikus-soft.com/api/project_badges/measure?project=cherrypy-foundation&metric=coverage"></a>
+</p>
+
+Cherrypy-foundation is a comprehensive toolkit that accelerates web application development with CherryPy. It provides a curated collection of utilities and integrations that handle common web development tasks, allowing you to focus on building your application's unique features.
+
+## What's Included
+
+- **Database Integration**: Seamless SQLAlchemy integration for database operations
+- **Template Engine**: Jinja2 and JinjaX support for flexible, component-based templating
+- **Form Handling**: Enhanced WTForms integration with automatic validation and Bootstrap rendering
+- **URL Management**: Flexible URL generation with `url_for` utility
+- **Error Handling**: Smart error pages that adapt to response content type (HTML, JSON, plain text)
+- **UI Components**: Bootstrap-ready components for rapid interface development
+
+## Who Is This For?
+
+Cherrypy-foundation is designed for developers who:
+
+- Want to build modern web applications with CherryPy without reinventing the wheel
+- Need a lightweight alternative to full-stack frameworks while maintaining flexibility
+- Prefer convention over configuration but value customization options
+- Want battle-tested components that integrate seamlessly with CherryPy's architecture
+
+This documentation will guide you through all available features, from basic utilities to advanced integrations, with practical examples to help you get started quickly.

cherrypy_foundation-1.0.0a17/debian/TODO

@@ -0,0 +1,3 @@
+- Symlink for all vendor files - bootstrap, jquery, etc.
+- How to run the unit test with the symlink files
+- symlink for sphinxdoc warning: ignoring unknown JavaScript code: debian/python3-cherrypy-foundation/usr/share/doc/python3-cherrypy-foundation/_static/scripts/fontawesome.js

{cherrypy_foundation-1.0.0a16 → cherrypy_foundation-1.0.0a17}/debian/control

@@ -9,9 +9,13 @@ Build-Depends:
  pybuild-plugin-pyproject,
  python3,
  python3-all-dev,
+ python3-myst-parser,
  python3-pip,
+ python3-pydata-sphinx-theme,
  python3-setuptools,
  python3-setuptools-scm,
+ python3-sphinx,
+ sphinx-common,
 # Optional dependencies to execute the test test.
  chromium-driver <!nocheck>,
  libjs-bootstrap5 <!nocheck>,
@@ -61,3 +65,10 @@ Description: Common utilities and integrations for building CherryPy web applica
  with SQLAlchemy for database access, Jinja2 for templating, WTForms for
  form handling, and Bootstrap for UI components, helping streamline
  application development.
+
+Package: python3-cherrypy-foundation-doc
+Section: doc
+Architecture: all
+Depends: ${sphinxdoc:Depends}, ${misc:Depends}
+Description: Documentation for cherrypy-foundation
+ This package contains the HTML documentation for cherrypy-foundation.

{cherrypy_foundation-1.0.0a16 → cherrypy_foundation-1.0.0a17}/debian/copyright

@@ -6,7 +6,7 @@ Files-Excluded:
  src/cherrypy_foundation/components/vendor
 
 Files: *
-Copyright: 2019-2025 Patrik Dufresne <patrik@ikus-soft.com>
+Copyright: 2019-2026 IKUS Software <patrik@ikus-soft.com>
 License: GPL-3+
 
 License: GPL-3+

cherrypy_foundation-1.0.0a17/debian/python3-cherrpy-foundation-doc.install

@@ -0,0 +1 @@
+build/html/* usr/share/doc/python3-cherrypy-foundation-doc

cherrypy_foundation-1.0.0a17/debian/python3-cherrpy-foundation.install

@@ -0,0 +1 @@
+usr/lib/python3*/*

cherrypy_foundation-1.0.0a17/debian/rules

@@ -0,0 +1,35 @@
+#!/usr/bin/make -f
+
+include /usr/share/dpkg/pkg-info.mk
+
+export SETUPTOOLS_SCM_PRETEND_VERSION_FOR_CHERRYPY_FOUNDATION := $(DEB_VERSION_UPSTREAM)
+
+# Force use of pyproject.toml
+export PYBUILD_SYSTEM=pyproject
+
+%:
+	dh $@ --with python3,sphinxdoc --buildsystem=pybuild --test-tox
+
+# Generate documentation
+execute_after_dh_auto_build:
+ifeq (,$(findstring nodoc, $(DEB_BUILD_OPTIONS)))
+	PYTHONPATH=. python3 -m sphinx -N -b html doc build/html
+endif
+
+# For testing, we need a timezone
+override_dh_auto_test:
+	TZ=UTC dh_auto_test
+
+# Remove tests files
+execute_after_dh_auto_install:
+	find debian/tmp/usr/lib/python$(PYTHON3_DEFAULT)/dist-packages/cherrypy_foundation -type d -name "tests" -exec rm -rf {} +
+
+execute_before_dh_auto_clean:
+	rm -rf *.egg-info
+# Clean Sphinx build artifacts
+	rm -rf build/html docs/_build
+
+# Generate orig.tar.gz
+gentarball:
+	git archive --format=tar HEAD --prefix=$(DEB_SOURCE)-$(DEB_VERSION_UPSTREAM)/ | gzip -9 > ../$(DEB_SOURCE)_$(DEB_VERSION_UPSTREAM).orig.tar.gz
+	mk-origtargz --compression gzip ../$(DEB_SOURCE)_$(DEB_VERSION_UPSTREAM).orig.tar.gz

cherrypy_foundation-1.0.0a17/doc/_templates/version.html

@@ -0,0 +1,2 @@
+<!-- This will display the version of the docs -->
+cherrypy-foundation {{ version }}

cherrypy_foundation-1.0.0a17/doc/conf.py

@@ -0,0 +1,69 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# -- Project information -----------------------------------------------------
+
+project = 'Cherrypy-foundation'
+copyright = 'Copyright (C) 2026 IKUS Software'
+author = 'Patrik Dufresne'
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'myst_parser',
+    'sphinx.ext.autosectionlabel',
+]
+
+autosectionlabel_prefix_document = True
+
+# Enable anchors for cross references
+myst_heading_anchors = 2
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'pydata_sphinx_theme'
+# Ref: https://alabaster.readthedocs.io/en/latest/customization.html#theme-options
+html_theme_options = {
+    "footer_start": ["copyright"],
+    "footer_end": ["version"],
+    'use_edit_page_button': True,
+}
+html_context = {
+    "gitlab_user": "ikus-soft",
+    "gitlab_repo": "cherrypy-foundation",
+    "gitlab_version": "main",
+    "doc_path": "doc",
+}
+html_show_sourcelink = False
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['_static']

cherrypy_foundation-1.0.0a17/doc/error_page.md

@@ -0,0 +1,163 @@
+# Error Pages
+
+The `error_page` utility replaces CherryPy's default error pages with a more flexible error handler.  
+It generates error responses based on the response `Content-Type`, returning either:
+
+- an HTML page (default),
+- a JSON error response for `application/json`
+- plain text for `text/plain`.
+
+If available, the HTML error page is rendered using Jinja2 with a template named `error_page.html`.
+
+⚠️ **Note:** For 404 errors, the error handler sanitizes the error message to avoid leaking path information. A generic message is returned instead of exposing the requested path.
+
+## Setup
+
+```python
+from cherrypy_foundation.error_page import error_page
+
+cherrypy.config.update({
+    'error_page.default': error_page,
+})
+```
+
+## Features
+
+### Content Negotiation
+
+The error handler automatically detects the expected response format:
+
+**HTML Response** (default for browsers):
+```http
+GET /invalid-page HTTP/1.1
+Accept: text/html
+
+HTTP/1.1 404 Not Found
+Content-Type: text/html
+
+<!DOCTYPE html>
+<html>
+  <head><title>404 Not Found</title></head>
+  <body>
+    <h2>404 Not Found</h2>
+    <p>Nothing matches the given URI</p>
+  </body>
+</html>
+```
+
+**JSON Response** (for API clients):
+```http
+GET /api/invalid HTTP/1.1
+Accept: application/json
+
+HTTP/1.1 404 Not Found
+Content-Type: application/json
+
+{"message": "Nothing matches the given URI", "status": "404 Not Found"}
+```
+
+**Plain Text Response**:
+```http
+GET /invalid HTTP/1.1
+Accept: text/plain
+
+HTTP/1.1 404 Not Found
+Content-Type: text/plain
+
+Nothing matches the given URI
+```
+
+### Server Error Logging
+
+All internal server error 500 are automatically logged with full traceback information:
+
+```python
+@cherrypy.expose
+def broken(self):
+    raise ValueError("Something went wrong!")
+    
+# Logs: error page status=500 Internal Server Error message=ValueError: Something went wrong!
+#       [full traceback]
+```
+
+### Custom Error Pages with Jinja2
+
+To use custom error page templates, create an `error_page.html` template in your Jinja2 environment:
+
+The following variables are available in the `error_page.html` template:
+
+- `status` (str): HTTP status code and message (e.g., "404 Not Found")
+- `message` (str): Detailed error message
+- `traceback` (str): Stack trace (only for server errors when debug mode is enabled)
+- `version` (str): CherryPy version
+
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>{{ status }}</title>
+    <link rel="stylesheet" href="/static/css/bootstrap.min.css">
+  </head>
+  <body>
+    <div class="container mt-5">
+      <div class="alert alert-danger">
+        <h1>{{ status }}</h1>
+        <p>{{ message }}</p>
+        
+        {% if traceback %}
+        <details>
+          <summary>Technical Details</summary>
+          <pre>{{ traceback }}</pre>
+        </details>
+        {% endif %}
+      </div>
+    </div>
+  </body>
+</html>
+```
+
+## Complete Example
+
+```python
+import cherrypy
+from cherrypy_foundation.error_page import error_page
+
+# Setup Jinja2
+env = cherrypy.tools.jinja2.create_env(
+    package_name=__package__,
+)
+
+# Configure error handler
+cherrypy.config.update({
+    'error_page.default': error_page,
+})
+
+@cherrypy.tools.jinja2(env=env)
+class Root:
+    
+    @cherrypy.expose
+    @cherrypy.tools.jinja2(template='index.html')
+    def index(self):
+        return {}
+    
+    @cherrypy.expose
+    def not_found(self):
+        # Will trigger 404 error page
+        raise cherrypy.NotFound()
+    
+    @cherrypy.expose
+    def server_error(self):
+        # Will trigger 500 error page with logging
+        raise ValueError("Database connection failed")
+    
+    @cherrypy.expose
+    @cherrypy.tools.json_out()
+    def api_endpoint(self):
+        # API errors will return JSON
+        raise cherrypy.HTTPError(400, "Invalid request parameters")
+
+if __name__ == '__main__':
+    cherrypy.quickstart(Root())
+```

cherrypy_foundation-1.0.0a17/doc/flash.md

@@ -0,0 +1,200 @@
+# Flash Messages
+
+Flash messages are used to display informational, warning, or error messages to the user.  
+They are especially useful for reporting success or validation errors after form submissions.
+
+⚠️ **Important:** Flash messages require the CherryPy **sessions tool** to be enabled, as messages are stored in the user session.
+
+## How It Works
+
+1. **Storage**: Flash messages are stored in the user's session under the `flash` key
+2. **Retrieval**: `get_flashed_messages()` retrieves all messages and clears them from the session
+3. **One-time display**: Messages are automatically removed after being retrieved, ensuring they only display once
+
+This makes flash messages perfect for post-redirect-get patterns where you want to show a message after a form submission.
+
+## Setup
+
+### 1. Enable Sessions and Configure Jinja2
+
+```python
+import cherrypy
+from cherrypy_foundation.flash import get_flashed_messages
+
+# Create Jinja2 environment with get_flashed_messages available
+env = cherrypy.tools.jinja2.create_env(
+    package_name=__package__,
+    globals={'get_flashed_messages': get_flashed_messages},
+)
+
+@cherrypy.tools.sessions(locking='explicit')  # Required for flash messages
+@cherrypy.tools.jinja2(env=env)
+class Root:
+    pass
+```
+
+### 2. Display Messages in Templates
+
+Call `get_flashed_messages()` in your Jinja2 template to retrieve and display flash messages:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>My Page</title>
+    <link rel="stylesheet" href="/static/css/bootstrap.min.css">
+  </head>
+  <body>
+    <!-- Display flash messages -->
+    {% for message in get_flashed_messages() %}
+      <div class="alert alert-{{ message.level }} alert-dismissible fade show">
+        {{ message.message }}
+        <button type="button" class="btn-close" data-bs-dismiss="alert"></button>
+      </div>
+    {% endfor %}
+    
+    <!-- Page content -->
+    <h1>Welcome!</h1>
+  </body>
+</html>
+```
+
+## Usage
+
+### Adding Flash Messages
+
+Use the `flash()` function to add messages in your handler:
+
+```python
+from cherrypy_foundation.flash import flash
+
+@cherrypy.expose
+def save_profile(self, **kwargs):
+    # Save user profile...
+    flash('Profile updated successfully!', level='success')
+    raise cherrypy.HTTPRedirect('/profile')
+```
+
+### Message Levels
+
+Flash messages support four severity levels:
+
+- `info` - Informational messages (default)
+- `success` - Success confirmations
+- `warning` - Warning messages
+- `error` - Error messages
+
+```python
+flash('Account created successfully', level='success')
+flash('Please verify your email address', level='info')
+flash('Your session will expire in 5 minutes', level='warning')
+flash('Failed to save changes', level='error')
+```
+
+### HTML Markup Support
+
+Flash messages support both plain strings and HTML markup:
+
+```python
+from markupsafe import Markup
+
+# Plain text
+flash('Simple message', level='info')
+
+# HTML markup (safe HTML)
+flash(Markup('Click <a href="/help">here</a> for help'), level='info')
+```
+
+### Using the JinjaX Flash Component
+
+If you have JinjaX installed, you can use the built-in `<Flash />` component for easier rendering:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>My Page</title>
+  </head>
+  <body>
+    <Flash
+      messages="{{ get_flashed_messages() }}"
+      class="mb-2"
+      style="min-height: 100px"
+    />
+    
+    <h1>Welcome!</h1>
+  </body>
+</html>
+```
+
+The `<Flash />` component automatically handles:
+- Rendering messages with appropriate Bootstrap alert classes
+- Dismiss buttons for each message
+- Custom styling via `class` and `style` attributes
+
+## Complete Example
+
+```python
+import cherrypy
+import cherrypy_foundation.tools.jinja2
+from cherrypy_foundation.flash import flash, get_flashed_messages
+
+# Setup Jinja2
+env = cherrypy.tools.jinja2.create_env(
+    package_name=__package__,
+    globals={'get_flashed_messages': get_flashed_messages},
+)
+
+@cherrypy.tools.sessions(locking='explicit')
+@cherrypy.tools.jinja2(env=env)
+class Root:
+    
+    @cherrypy.expose
+    @cherrypy.tools.jinja2(template='index.html')
+    def index(self):
+        return {}
+    
+    @cherrypy.expose
+    def submit(self, name=None):
+        if not name:
+            flash('Name is required', level='error')
+        else:
+            flash(f'Welcome, {name}!', level='success')
+        
+        raise cherrypy.HTTPRedirect('/')
+
+if __name__ == '__main__':
+    cherrypy.quickstart(Root())
+```
+
+**Template: `form.html`**
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Registration Form</title>
+    <link rel="stylesheet" href="/static/css/bootstrap.min.css">
+  </head>
+  <body>
+    <div class="container mt-5">
+      <!-- Flash messages -->
+      {% for message in get_flashed_messages() %}
+        <div class="alert alert-{{ message.level }} alert-dismissible">
+          {{ message.message }}
+          <button type="button" class="btn-close" data-bs-dismiss="alert"></button>
+        </div>
+      {% endfor %}
+      
+      <!-- Form -->
+      <form method="post" action="/submit">
+        <div class="mb-3">
+          <label for="name" class="form-label">Name</label>
+          <input type="text" class="form-control" id="name" name="name">
+        </div>
+        <button type="submit" class="btn btn-primary">Submit</button>
+      </form>
+    </div>
+  </body>
+</html>
+```