npm - pyfrilet - Versions diffs - 0.1.1 - Mend

pyfrilet 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,320 @@
+# pyfrilet — documentation
+pyfrilet est un petit système pour publier des animations Python interactives sur une page web.
+Il combine [p5.js](https://p5js.org/) (dessin 2D) et [Pyodide](https://pyodide.org/) (Python dans le navigateur) avec un éditeur de code intégré qu'on tire depuis le bas de la page.
+---
+## Écrire un sketch Python
+Un sketch est un fichier HTML minimal avec son code Python embarqué.
+```html
+<!doctype html>
+<html lang="fr">
+<head>
+  <meta charset="utf-8">
+  <title>Mon sketch</title>
+  <script src="pyfrilet.js"></script>
+</head>
+<body>
+<script type="text/python" data-sources="cdn">
+from p5 import *
+def setup():
+    size(400, 400)
+    frameRate(30)
+def draw():
+    background(20)
+    fill('#e0af68')
+    circle(mouseX, mouseY, 40)
+</script>
+</body>
+</html>
+```
+C'est tout. pyfrilet se charge de démarrer Pyodide, de monter le module `p5`, et de lancer le sketch.
+### API p5 disponible
+Le module `p5` expose **toute l'API p5.js** via introspection dynamique : au démarrage, pyfrilet instancie p5.js en arrière-plan, inspecte ses membres, et construit le module Python en conséquence. `from p5 import *` importe donc automatiquement toutes les fonctions et constantes de p5.js, à l'exception des builtins Python qui pourraient entrer en conflit (`map`, `filter`, `set`, `int`, `print`, etc.) et des hooks de cycle de vie (`setup`, `draw`…) que vous définissez vous-même.
+L'autocomplétion dans l'éditeur intégré connaît l'ensemble de ces symboles.
+Les fonctions ci-dessous sont un aperçu des plus couramment utilisées, à titre d'illustration :
+| Fonction | Description |
+|---|---|
+| `background(v)` | Efface le fond. Valeur grise (0–255) ou couleur CSS (`'#ff0000'`, `'red'`…). |
+| `fill(...)` | Couleur de remplissage. |
+| `stroke(...)` | Couleur de contour. |
+| `noStroke()` | Supprime le contour. |
+| `noFill()` | Supprime le remplissage. |
+| `rect(x, y, w, h)` | Rectangle. |
+| `circle(x, y, d)` | Cercle (x, y = centre, d = diamètre). |
+| `ellipse(x, y, w, h)` | Ellipse. |
+| `line(x1, y1, x2, y2)` | Segment. |
+| `text(s, x, y)` | Affiche une chaîne. |
+| `textSize(sz)` | Taille du texte en pixels. |
+| `textAlign(h, v)` | Alignement horizontal et vertical. |
+| `push()` / `pop()` | Sauvegarde / restaure l'état graphique. |
+| `translate(x, y)` | Déplace l'origine. |
+| `rotate(angle)` | Rotation (angle en radians). |
+| `scale(sx, sy)` | Mise à l'échelle. |
+| `image(img, x, y)` | Affiche une image. |
+| `loadImage(url)` | Charge une image (à appeler dans `preload()`). |
+| `random(min, max)` | Nombre aléatoire entre min et max. |
+| `noise(x)` | Bruit de Perlin. |
+Pour la référence complète, consulter la [documentation p5.js](https://p5js.org/reference/).
+#### Cycle de vie
+Ces fonctions sont définies par l'utilisateur et appelées automatiquement par pyfrilet :
+| Fonction | Rôle |
+|---|---|
+| `setup()` | Appelée une seule fois au démarrage. Obligatoire pour appeler `size()` ou `frameRate()`. |
+| `draw()` | Appelée à chaque frame. **Obligatoire.** |
+| `mousePressed()` | Appelée à chaque clic sur le canvas. |
+| `keyPressed()` | Appelée à chaque pression de touche. `keyCode` et `key` sont déjà à jour au moment de l'appel. |
+| `windowResized()` | Appelée quand la zone d'affichage change (redimensionnement de la fenêtre ou du tiroir éditeur). |
+#### Fonctions pyfrilet (hors p5.js standard)
+| Fonction | Description |
+|---|---|
+| `size(w, h)` | Crée ou redimensionne le canvas. Le canvas est mis à l'échelle CSS pour remplir l'écran sans déformation. |
+| `size('max')` | Canvas plein écran, redimensionné dynamiquement. |
+| `smooth()` | Active l'antialiasing (par défaut). |
+| `noSmooth()` | Désactive l'antialiasing (pixel art). Affecte formes **et** texte. |
+| `sketchTitle(s)` | Affiche un texte dans la barre de contrôle. À appeler dans `setup()`. |
+#### Propriétés dynamiques
+Ces variables sont mises à jour automatiquement avant chaque appel à `draw()`, `keyPressed()` et `mousePressed()`, y compris si elles ont été importées avec `from p5 import *` :
+```python
+mouseX, mouseY   # position de la souris dans le repère du canvas
+width, height    # dimensions logiques du canvas
+frameCount       # numéro de la frame courante
+key              # dernière touche appuyée (caractère)
+keyCode          # code numérique de la dernière touche
+```
+> **Note sur `keyCode`** : p5.js expose des constantes nommées (`LEFT_ARROW`, `RIGHT_ARROW`, `UP_ARROW`, `DOWN_ARROW`, `ENTER`, `BACKSPACE`…) directement importables avec `from p5 import *`.
+### Exemple : plein écran réactif
+```python
+from p5 import *
+def setup():
+    size('max')
+    frameRate(60)
+    sketchTitle("Mon sketch · Échap → éditeur")
+def windowResized():
+    size('max')   # redimensionne le canvas quand le tiroir bouge
+def draw():
+    background(0)
+    noStroke()
+    fill('#7aa2f7')
+    circle(width / 2, height / 2, min(width, height) * 0.4)
+```
+### Exemple : navigation clavier
+```python
+from p5 import *
+page = 0
+def setup():
+    size(400, 300)
+def keyPressed():
+    global page
+    if keyCode == RIGHT_ARROW: page += 1
+    if keyCode == LEFT_ARROW:  page -= 1
+def draw():
+    background(20)
+    smooth()
+    fill('#e0af68')
+    textSize(16)
+    text("page " + str(page), 160, 150)
+```
+### Note sur `smooth()` / `noSmooth()` et le texte
+Par défaut le canvas est rendu en mode antialiasé. `noSmooth()` bascule en mode pixel art — formes **et** texte sont pixelisés. Pour mélanger les deux dans le même `draw()` :
+```python
+noSmooth()
+rect(10, 10, 80, 80)   # bords nets
+smooth()
+textSize(14)
+text("lisible", 10, 120)  # texte antialiasé
+```
+---
+## Interface utilisateur
+La barre de contrôle est collée en bas de l'écran.
+| Élément | Action |
+|---|---|
+| ☰ (hamburger, à gauche) | Ouvre / ferme le tiroir éditeur |
+| Glisser la barre vers le haut/bas | Redimensionne le tiroir — relâcher sous 120 px le referme |
+| ▶ | Relance l'exécution du code (sans fermer l'éditeur) |
+| ✏️ | Ouvre l'éditeur en **plein écran** ; referme si déjà ouvert |
+| 💾 | Télécharge la page en HTML autonome (voir ci-dessous) |
+| ↻ | Réinitialise le code à la version d'origine (confirmation demandée) |
+### Raccourcis clavier
+| Raccourci | Action |
+|---|---|
+| `Shift+Entrée` | Relance l'exécution (depuis l'éditeur ou depuis le sketch) |
+| `Échap` | Ouvre le tiroir si fermé, ferme si ouvert |
+| `Ctrl+S` | Sauvegarde le code dans le localStorage |
+| `Ctrl+R` | Réinitialise le code à la version d'origine (confirmation demandée) |
+Quand le tiroir se ferme, le focus clavier est automatiquement donné au canvas — les événements `keyPressed()` du sketch fonctionnent sans clic préalable.
+Le code est **sauvegardé automatiquement** dans le `localStorage` à chaque modification. Il est restauré à l'ouverture de la page.
+### Télécharger
+Le bouton 💾 génère un fichier `sketch.html` autonome : pyfrilet.js y est embarqué sous forme de data URL base64, et le code Python est celui de l'éditeur au moment du clic. Le fichier produit charge p5.js et Pyodide depuis le CDN et n'a besoin d'aucun serveur pour fonctionner. On peut également télécharger l'export d'un export — le résultat est identique.
+---
+## Déploiement local (mode `vendor/`)
+Par défaut (`data-sources="cdn"`), pyfrilet charge ses dépendances depuis des CDN publics, ce qui nécessite une connexion internet. Pour un déploiement entièrement local — intranet, usage hors ligne, ou simplement pour ne pas dépendre de services tiers — on peut héberger les dépendances soi-même.
+### Utiliser une copie locale de pyfrilet.js
+Dans une page déployée en local, on remplace la balise CDN par une référence locale :
+```html
+<!-- au lieu de : <script src="https://…/pyfrilet.js"></script> -->
+<script src="pyfrilet.js"></script>
+```
+Le fichier `pyfrilet.js` est alors servi depuis le même répertoire que la page HTML. C'est utile pour modifier pyfrilet lui-même, ou pour un déploiement sans accès internet.
+### Structure de fichiers
+```
+mon-projet/
+├── pyfrilet.js
+├── mon-sketch.html
+└── vendor/
+    ├── p5.min.js
+    ├── ace.min.js
+    ├── mode-python.min.js
+    ├── theme-monokai.min.js
+    ├── ext-language_tools.min.js
+    ├── ext-searchbox.min.js
+    └── pyodide/
+        ├── pyodide.js
+        ├── pyodide.asm.wasm
+        ├── python_stdlib.zip
+        └── … (autres fichiers Pyodide)
+```
+### Télécharger les dépendances
+**p5.js**
+```
+https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.9.4/p5.min.js
+```
+**ACE editor** (5 fichiers)
+```
+https://cdnjs.cloudflare.com/ajax/libs/ace/1.36.5/ace.min.js
+https://cdnjs.cloudflare.com/ajax/libs/ace/1.36.5/mode-python.min.js
+https://cdnjs.cloudflare.com/ajax/libs/ace/1.36.5/theme-monokai.min.js
+https://cdnjs.cloudflare.com/ajax/libs/ace/1.36.5/ext-language_tools.min.js
+https://cdnjs.cloudflare.com/ajax/libs/ace/1.36.5/ext-searchbox.min.js
+```
+**Pyodide** — télécharger l'archive complète depuis les releases GitHub :
+```
+https://github.com/pyodide/pyodide/releases/tag/0.26.4
+```
+Extraire le contenu dans `vendor/pyodide/`.
+### Balise HTML
+```html
+<script type="text/python" data-sources="local" data-vendor="vendor/">
+  …code python…
+</script>
+```
+`data-vendor` indique le chemin vers le dossier `vendor/` **relatif à la page HTML**. La valeur par défaut est `vendor/` si l'attribut est absent.
+### Serveur local
+Les navigateurs bloquent le chargement de fichiers locaux (`file://`) pour des raisons de sécurité. Il faut donc un serveur HTTP minimal pour tester en local, même sans déploiement :
+```bash
+# Python 3
+python -m http.server 8000
+# Node.js
+npx serve .
+```
+Puis ouvrir `http://localhost:8000/mon-sketch.html`.
+---
+## Licence
+pyfrilet.js est distribué sous **GNU Lesser General Public License v2.1** (LGPL-2.1).
+En pratique cela signifie :
+- Tu peux l'utiliser dans un projet propriétaire ou open source sans contrainte.
+- Si tu modifies pyfrilet.js lui-même, tu dois publier ces modifications sous LGPL.
+- Tu n'as pas à inclure p5.js, Pyodide ou ACE dans ton dépôt : pyfrilet les charge dynamiquement, il n'y a pas de liaison statique.
+### Licences des dépendances
+pyfrilet ne contient aucun code de ces bibliothèques ; elles sont chargées séparément au moment de l'exécution. Leurs licences s'appliquent à elles seules :
+| Bibliothèque | Licence |
+|---|---|
+| [p5.js](https://p5js.org/) | LGPL 2.1 |
+| [Pyodide](https://pyodide.org/) | MPL 2.0 |
+| [ACE editor](https://ace.c9.io/) | BSD 3-Clause |
+### Contenu minimal d'un dépôt de distribution
+Pour distribuer un sketch sur un dépôt git de façon propre et conforme :
+```
+mon-sketch/
+├── LICENSE          ← texte de la LGPL 2.1
+├── README.md        ← cette doc, ou un résumé
+├── pyfrilet.js
+└── mon-sketch.html
+```
+Les dépendances (`vendor/`) n'ont pas à être versionnées si on utilise le mode CDN. Si on veut un déploiement hors ligne, on les ajoute au dépôt en respectant leurs licences respectives — un fichier `NOTICE` listant les bibliothèques tierces et leurs licences est une bonne pratique.
+---
+## Remerciements
+La gestion du module Python `p5` s'inspire du travail de [Basthon](https://basthon.fr/) (Romain Casati). L'idée d'instancier p5.js en arrière-plan pour en inspecter les membres dynamiquement, puis de construire le module Python par introspection plutôt qu'en listant les fonctions à la main, est directement issue de cette approche. Merci à Basthon pour ce travail pionnier sur Python dans le navigateur pour l'enseignement.

package/package.json ADDED Viewed

@@ -0,0 +1,15 @@
+{
+  "name": "pyfrilet",
+  "version": "0.1.1",
+  "main": "pyfrilet.js",
+  "files": [
+    "pyfrilet.js",
+    "pyfrilet.min.js"
+  ],
+  "scripts": {
+    "build": "terser pyfrilet.js -o pyfrilet.min.js --compress --mangle"
+  },
+  "devDependencies": {
+    "terser": "^5.46.0"
+  }
+}