html_cleanup/AGENTS.md

AGENTS.md

Project

Pyramid web app that uploads HTML files, strips unwanted tags, converts encoding to UTF-8, and serves cleaned files for download. UI is in French.

Quick Start

python3 -m venv env
env/bin/pip install --upgrade pip setuptools
env/bin/pip install -e ".[testing]"
env/bin/pserve development.ini   # localhost:9480

Commands

env/bin/pytest                     # run all tests
env/bin/pytest tests/test_views.py # single file
env/bin/pserve development.ini     # dev server (port 9480, template reload on)
env/bin/pserve production.ini      # production server (port 9480, HTTPS)

Architecture

html_cleanup/
├── __init__.py          # Pyramid app factory (main())
├── routes.py            # Two routes: / (home), /view_log
├── views/
│   ├── default.py       # Core logic: home(), process_file(), clean_html()
│   └── notfound.py      # 404 handler
├── templates/           # Jinja2 templates (layout.jinja2, home.jinja2, view_log.jinja2)
└── static/
    └── temp/            # Upload output dir — configured in INI files via temp_folder setting

• clean_html() in views/default.py is the core — it parses HTML tags and keeps only a whitelisted set (table, img, a, div, p, h1–h6, b, em, i, li, ol, ul, strong, sub, sup, u, s, del, ins, br, hr).
• The temp folder path is set via temp_folder in .ini files — development.ini uses an absolute local path (/Users/phuoc/pyramid/html_cleanup/html_cleanup/static/temp/).
• view_log view has a hardcoded user list for access control.

Config Files

File	Purpose
development.ini	Dev config — debugtoolbar, template reload, local temp path
production.ini	Prod config — HTTPS, warns only
testing.ini	Test config — used by pytest via conftest.py
pytest.ini	--strict-markers, test paths: html_cleanup + tests

Known Issues

• Tests are broken:
  • tests/test_views.py imports my_view — function was renamed to home and is no longer importable without a proper test request.
  • tests/test_functional.py asserts b'Pyramid' in response body, but the page title is "HTML cleanup".
• Do not rely on tests/ passing as-is; fix tests if modifying views.
• The clean_html regex for id attributes (id=\"\w+\") won't match hyphens despite a comment claiming hyphens are supported — only [a-zA-Z0-9_] is matched.

Conventions

• Templates use Jinja2 (not Mako). Extension: .jinja2.
• All user-facing strings are in French.
• Error logging goes to static/temp/errors_log (appended, not rotated).
• Tag whitelist in clean_html() is a series of if/elif chains — not a config or data structure.

Todo

• Analyze @html_cleanup/views/default.py .py for potential issues, bugs, and code quality problems