encadre a sa documentation (et a déménagé)

 · 2 min read
 · Jean Schurger

English version below.

encadre, mon petit framework web en Python, a enfin une documentation : schurger.org/pages/encadre.html.

Le principe tient en trois lignes : une classe dérivée de Controller est un contrôleur, ses méthodes sont les routes (show(self, book_id) répond sur /books/show/<book_id>), et une nouvelle version d'une API est une sous-classe (Books_1(Books)), choisie par le client avec un en-tête HTTP. Le reste — validation par schéma JSON, points d'accroche avant et après chaque requête, erreurs en JSON, tests attachés aux contrôleurs — est dans la page.

En l'écrivant, j'ai tout revérifié sur le code plutôt que sur l'ancien README, qui avait vieilli : il décrivait encore un setup.py, et montait ses exemples au mauvais endroit (un contrôleur qui hérite directement de Controller répond à la racine, pas sous son nom). La page dit aussi ce qui ne marche pas encore : une route inconnue répond 500 au lieu de 404 tant qu'on ne traduit pas l'erreur soi-même, et le mode de version « préfixe » ne sait pas servir la version 0.

Au passage, encadre a quitté GitHub. Son dépôt vit maintenant chez moi, avec tout son historique :

git clone https://git.schurger.org/encadre.git

git.schurger.org est volontairement minimaliste : des pages HTML statiques générées par stagit à chaque git push, et un clonage HTTPS servi directement par nginx. Rien ne s'exécute quand on visite. Les versions publiées restent sur PyPI (pip install encadre).

English version

encadre, my small Python web framework, finally has documentation, in English and in French: schurger.org/pages/encadre-en.html.

The idea fits in three lines: a class derived from Controller is a controller, its methods are the routes (show(self, book_id) answers on /books/show/<book_id>), and a new API version is a subclass (Books_1(Books)), picked by the client with an HTTP header. The rest — JSON schema validation, hooks before and after each request, JSON errors, tests attached to the controllers — is on the page.

While writing it I checked everything against the code rather than the old README, which had aged: it still described a setup.py, and mounted its examples in the wrong place (a controller inheriting directly from Controller answers at the root, not under its name). The page also says what does not work yet: an unknown route answers 500 instead of 404 unless you translate the error yourself, and the "prefix" versioning mode cannot serve version 0.

On the way, encadre left GitHub. Its repository now lives on my server, with its whole history:

git clone https://git.schurger.org/encadre.git

git.schurger.org is deliberately minimal: static HTML pages generated by stagit on every git push, and HTTPS cloning served directly by nginx. Nothing runs when you visit. Releases stay on PyPI (pip install encadre).