capy.config.json v0.5.4

Le fichier qui décrit tout un projet capy : son nom, comment joindre le serveur (local, wifi ou internet), le chiffrement, et les fichiers du projet. Le serveur et le client le lisent avec capy.project(), et la commande cy lance ses scripts et ses fichiers, comme npm avec package.json.

Le fichier complet#

Toutes les clés sont facultatives, sauf celles que demande le mode (port en local, relay en network).

{
    "$schema": "https://libs.zazac.link/capy.config.schema.json",
    "name": "mon-jeu",
    "description": "Un petit jeu en réseau",
    "version": "1.0",
    "author": "Izac",
    "mode": "local",
    "url": "127.0.0.1",
    "port": 2388,
    "tls": true,
    "files": {
        "server": "server.py",
        "client": "client.py",
        "admin": "outils/admin.py"
    },
    "scripts": {
        "start": "cy run",
        "test": "python3 -m unittest discover -s tests",
        "deploy": "rsync -az . mon-vps:/srv/mon-jeu/"
    }
}

Toutes les clés#

Les trois modes#

local : sur la même machine, ou vers une IP connue#

{
    "name": "mon-jeu",
    "mode": "local",
    "url": "127.0.0.1:2388"
}

Le serveur écoute sur le port 2388 ; le client appelle 127.0.0.1:2388. Pour qu'un autre ordi joigne le serveur, mets l'IP du serveur dans url (ex : "192.168.1.42:2388") dans le fichier du client.

wifi : par un nom, sur le même wifi#

{
    "name": "salon",
    "mode": "wifi"
}

Pas d'IP ni de port : le serveur s'annonce sous le nom salon, le client le trouve tout seul. Un port reste possible si tu veux toujours le même.

network : à travers internet, par un relais#

{
    "name": "maison",
    "mode": "network",
    "relay": "mon-vps.fr:3879",
    "key": "$CAPY_KEY",
    "fingerprint": "9b734c758696262e758f8664db40fafe3601f3804ced5dc331527704319f3049"
}

Le serveur se connecte au relais sous le nom maison ; le client l'appelle par ce nom, depuis n'importe où. Toujours chiffré : "tls": false est refusé. Voir le guide de capy.network pour installer le relais.

Écrire les valeurs#

Les secrets : $VARIABLE#

Un texte qui commence par $ est lu dans les variables d'environnement. Marche pour toutes les clés, même dans files.

{ "name": "maison", "relay": "$CAPY_RELAY", "key": "$CAPY_KEY" }

export CAPY_RELAY='mon-vps.fr:3879'
export CAPY_KEY='ma-longue-cle-secrete'

Les fichiers : files#

files donne un nom à chaque fichier du projet. Les chemins partent du **dossier de capy.config.json**, et ~ marche aussi.

"files": {
    "server": "server.py",
    "client": "client.py",
    "admin": "outils/admin.py",
    "tests": "tests/test_jeu.py"
}

• cy server, cy client, cy admin… lancent le fichier de ce nom.
• cy run utilise server et client.
• Dans le code : app.file("admin") donne le chemin complet, et app.files tous les fichiers.

Les commandes : scripts#

Comme les scripts de package.json chez npm : tu donnes un nom à une commande du terminal, et cy NOM la lance, depuis le dossier du projet, où que tu sois.

"scripts": {
    "start": "cy run",
    "test": "python3 -m unittest discover -s tests",
    "format": "python3 -m black .",
    "deploy": "rsync -az --exclude .git . mon-vps:/srv/mon-jeu/",
    "salut": "echo Bonjour depuis $CAPY_NAME, port $CAPY_PORT"
}

cy test

> python3 -m unittest discover -s tests
....
Ran 4 tests in 0.012s
OK

• La commande passe par le shell : &&, |, > et les $VARIABLES marchent comme dans le terminal.
• python3 (ou python) au début est remplacé par le Python qui lance capy : pas de surprise entre deux Python installés.
• cy au début ("start": "cy run") lance capy avec ce même Python, même si cy n'est pas dans le PATH.
• Les arguments en plus sont ajoutés à la fin : cy test -k login lance … discover -s tests -k login.
• Le script reçoit les infos du projet en variables d'environnement : CAPY_NAME, CAPY_MODE, CAPY_PROJECT (le dossier), et en mode local CAPY_HOST et CAPY_PORT.
• Le code de sortie du script devient celui de cy : un script qui échoue fait échouer la commande.
• cy scripts les liste. Dans le code : app.scripts et app.run_script("test").

Où capy cherche le fichier#

capy.project() cherche capy.config.json :

1. dans le dossier du script lancé (pas celui du terminal) ;
2. puis dans les dossiers au-dessus, jusqu'à la racine (comme git).

Un client/client.py ou un outils/admin.py trouvent donc le fichier du projet. cy, lui, part du dossier du terminal. Pour un autre fichier : capy.project("autre.json") ou capy.project("~/projets/jeu").

Dans le code#

import capy

app = capy.project()

app.name, app.version, app.author, app.description   # Les infos du projet
app.mode, app.host, app.port, app.tls                # Comment le joindre
app.folder                                           # Le dossier du projet
app.file("server")                                   # Le chemin d'un fichier de "files"
print(app.describe())                                # Tout, en texte (comme cy)

server = app.server()                                # Côté serveur : déjà réglé
reponse = app.call("hello", nom="Izac")              # Côté client : sans IP ni port

Les erreurs#

capy vérifie tout le fichier au chargement et dit quoi corriger :

L'autocomplétion dans VS Code#

Ajoute la ligne "$schema" en haut du fichier : VS Code propose alors les clés, explique chacune au survol, et souligne les erreurs (mauvais mode, port en texte bizarre, clé inconnue…) pendant que tu écris.

{
    "$schema": "https://libs.zazac.link/capy.config.schema.json",
    "name": "mon-jeu"
}

Les commandes#

**cy est la commande d'un projet capy : elle s'installe avec capy, et ne marche que dans un projet** (un dossier qui a un capy.config.json, ou un de ses sous-dossiers). Pour créer un projet, c'est capy new ou capy init.

$ cy
mon-jeu v1.0 par Izac
  Un petit jeu en réseau
  mode     local (127.0.0.1:2388)
  tls      oui (chiffré)
  server   server.py  ✓
  client   client.py  ✓
  admin    outils/admin.py  ✗ introuvable
  script   start    cy run
  script   test     python3 -m unittest discover -s tests
  fichier  /Users/izac/projets/mon-jeu/capy.config.json