capyy 0.3.2__tar.gz → 0.4.0__tar.gz

{capyy-0.3.2/capyy.egg-info → capyy-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capyy
-Version: 0.3.2
+Version: 0.4.0
 Summary: Tiny encrypted JSON-over-TCP APIs: call a function in another program, on your Wi-Fi or across the internet
 Author: Izac
 License-Expression: MIT
@@ -73,6 +73,23 @@ capy.to_int("42"), capy.to_bool("yes")  # 42, True
 `to_str`, `to_int`, `to_float`, `to_bool`, `to_list` and `to_dict` raise a `ValueError` that says exactly
 what could not be converted.
 
+## Project file: capy.config.json
+
+Describe the project once (`python3 -m capy init my-game` creates it), then never repeat ports or hosts:
+
+```json
+{"name": "my-game", "mode": "local", "host": "localhost", "port": 4000, "tls": true}
+```
+
+```python
+app = capy.project()            # finds capy.config.json next to the script, or in a parent folder
+server = app.server()           # server side
+app.call("hello", nom="Izac")   # client side
+```
+
+`mode` can be `local`, `wifi` or `network` (with `relay`, `key`, `fingerprint`). Strings starting with `$` are read
+from environment variables, e.g. `"key": "$CAPY_KEY"`.
+
 ## Encryption (TLS)
 
 Everything is encrypted by default, with nothing to configure.

{capyy-0.3.2 → capyy-0.4.0}/README.md

@@ -51,6 +51,23 @@ capy.to_int("42"), capy.to_bool("yes")  # 42, True
 `to_str`, `to_int`, `to_float`, `to_bool`, `to_list` and `to_dict` raise a `ValueError` that says exactly
 what could not be converted.
 
+## Project file: capy.config.json
+
+Describe the project once (`python3 -m capy init my-game` creates it), then never repeat ports or hosts:
+
+```json
+{"name": "my-game", "mode": "local", "host": "localhost", "port": 4000, "tls": true}
+```
+
+```python
+app = capy.project()            # finds capy.config.json next to the script, or in a parent folder
+server = app.server()           # server side
+app.call("hello", nom="Izac")   # client side
+```
+
+`mode` can be `local`, `wifi` or `network` (with `relay`, `key`, `fingerprint`). Strings starting with `$` are read
+from environment variables, e.g. `"key": "$CAPY_KEY"`.
+
 ## Encryption (TLS)
 
 Everything is encrypted by default, with nothing to configure.

{capyy-0.3.2 → capyy-0.4.0}/capy/__init__.py

@@ -6,6 +6,7 @@ import threading
 from typing import Any
 
 from . import _tls
+from ._project import Project, project  # noqa: F401  (capy.project() : lire capy.config.json)
 from ._tls import SecurityError  # noqa: F401  (capy.SecurityError)
 
 
@@ -51,7 +52,7 @@ class Server:
                 line = conn.makefile(encoding="utf-8").readline()
                 if not line.strip():  # Connexion ouverte puis fermée sans rien demander
                     return
-                conn.sendall((jsonlib.dumps(self.handle(line), ensure_ascii=False) + "\n").encode())
+                conn.sendall((_dumps(self.handle(line)) + "\n").encode())
             except (OSError, ValueError):
                 return
             print(f"{addr[0]} → {_hide(line)}")
@@ -76,6 +77,15 @@ class Server:
 
 
 # Renvoyer du JSON écrit en texte depuis une action
+# Réponse d'une action -> texte JSON (une réponse impossible à mettre en JSON devient une erreur claire)
+# Ex : return {1, 2} (un set) -> {"erreur": "réponse pas en JSON : Object of type set is not JSON serializable"}
+def _dumps(response):
+    try:
+        return jsonlib.dumps(response, ensure_ascii=False)
+    except (TypeError, ValueError) as e:
+        return jsonlib.dumps({"erreur": f"réponse pas en JSON : {e}"}, ensure_ascii=False)
+
+
 # Paramètres jamais affichés dans le journal du serveur (mots de passe, tokens…)
 SECRETS = ("password", "passwd", "pwd", "mdp", "motdepasse", "secret", "token")
 
@@ -284,6 +294,8 @@ def _call(host, port, action, params, tls, label, who="capy"):
         error = e
     except (OSError, ValueError) as e:
         error = e
+    if connected and isinstance(error, socket.timeout):  # Connecté, mais l'action met trop longtemps
+        raise ConnectionError(f"{who} : le serveur {host}:{port} n'a pas répondu à temps (3 s) : l'action est sans doute trop lente") from None
     if connected:  # Il a décroché puis coupé : souvent un serveur chiffré appelé en clair
         raise ConnectionError(f"{who} : le serveur {host}:{port} a coupé la connexion sans répondre{hint}") from None
     raise ConnectionError(f"{who} : le serveur {host}:{port} ne répond pas ({type(error).__name__})") from None

capyy-0.4.0/capy/__main__.py

@@ -0,0 +1,36 @@
+# python3 -m capy : petites commandes pour un projet capy
+#
+#   python3 -m capy init [nom] [local|wifi|network]   -> crée capy.config.json ici
+#   python3 -m capy                                   -> montre le projet trouvé (capy.config.json)
+
+import sys
+
+from ._project import FILE_NAME, MODES, find, init, project
+
+
+def main(args):
+    if args[:1] == ["init"]:
+        rest = args[1:]
+        mode = next((a for a in rest if a in MODES), "local")
+        name = next((a for a in rest if a not in MODES), None)
+        try:
+            path = init(name=name, mode=mode)
+        except (FileExistsError, ValueError) as e:
+            sys.exit(str(e))
+        print(f"Créé : {path}")
+        print(path.read_text(encoding="utf-8"), end="")
+        if mode == "network":
+            print("Pense à : export CAPY_KEY='la clé du relais'  (dans ~/.zshrc), et à mettre l'adresse de ton relais")
+        return
+    if args:
+        sys.exit(f"Usage : python3 -m capy init [nom] [{'|'.join(MODES)}]   ou   python3 -m capy")
+    path = find(".")
+    if path is None:
+        sys.exit(f"Pas de {FILE_NAME} ici ni au-dessus. Crée-le avec : python3 -m capy init")
+    try:
+        print(project(path), "\n ", path)
+    except ValueError as e:
+        sys.exit(str(e))
+
+
+main(sys.argv[1:])

capyy-0.4.0/capy/_project.py

@@ -0,0 +1,188 @@
+# capy.project() : décrire un projet une fois dans capy.config.json, puis ne plus répéter port, IP, relais...
+#
+#   capy.config.json   {"name": "maison", "mode": "local", "host": "localhost", "port": 4000}
+#   serveur.py         app = capy.project();  server = app.server();  ...;  server.run()
+#   client.py          app = capy.project();  app.call("hello", nom="Izac")
+#
+# mode "local"   -> capy.Server(port) / capy.call(host, port, ...)
+# mode "wifi"    -> capy.wifi.Server(name) / capy.wifi.call(name, ...)
+# mode "network" -> capy.network.Server(name) / capy.network.call(name, ...) via "relay"
+# Un texte qui commence par $ est lu dans les variables d'environnement : "key": "$CAPY_KEY"
+
+import difflib
+import json as jsonlib
+import os
+import pathlib as pth
+import sys
+from typing import Any
+
+FILE_NAME = "capy.config.json"
+MODES = ("local", "wifi", "network")
+
+# Ce qu'on peut mettre dans le fichier : clé -> (types acceptés, explication)
+FIELDS = {
+    "name": ((str,), "nom du projet (le nom du serveur en wifi et en network)"),
+    "mode": ((str,), "local, wifi ou network"),
+    "host": ((str,), "adresse du serveur pour le client, en local (ex : localhost, 192.168.1.42)"),
+    "port": ((int,), "port du serveur (0 = un port libre au hasard)"),
+    "tls": ((bool,), "chiffrement, true par défaut"),
+    "relay": ((str,), "relais capy.network, ex : mon-vps.fr:3879"),
+    "key": ((str,), "clé du relais (mieux : \"$CAPY_KEY\", lue dans les variables d'environnement)"),
+    "fingerprint": ((str,), "empreinte du relais, affichée à son démarrage"),
+    "description": ((str,), "une phrase pour toi, capy ne s'en sert pas"),
+}
+
+EXAMPLE = {"name": "mon-projet", "mode": "local", "host": "localhost", "port": 4000, "tls": True}
+
+
+# Dossier du script lancé (comme simplesuit.json) ; sans script (python3 -c, REPL) -> dossier actuel
+def _main_dir():
+    file = getattr(sys.modules.get("__main__"), "__file__", None)
+    return pth.Path(file).resolve().parent if file else pth.Path.cwd()
+
+
+# Chercher capy.config.json dans le dossier du script, puis dans les dossiers au-dessus (comme git)
+def find(start=None):
+    folder = pth.Path(start or _main_dir()).resolve()
+    for place in (folder, *folder.parents):
+        if (place / FILE_NAME).is_file():
+            return place / FILE_NAME
+    return None
+
+
+# Un projet capy, lu depuis capy.config.json
+# Ex : app = capy.project() puis app.server() côté serveur, app.call("hello") côté client
+class Project:
+    def __init__(self, path):
+        self.path = pth.Path(path)
+        try:
+            data = jsonlib.loads(self.path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            raise FileNotFoundError(f"capy.project : pas de fichier {self.path}") from None
+        except ValueError as e:
+            raise ValueError(f"capy.project : {self.path.name} n'est pas du JSON valide ({e})") from None
+        if not isinstance(data, dict):
+            raise ValueError(f"capy.project : {self.path.name} doit contenir un objet {{...}}")
+        self.config = _check(data, self.path.name)
+        get = self.config.get
+        self.name = get("name") or self.path.parent.name
+        self.mode = get("mode") or ("network" if get("relay") else "local")
+        self.host = get("host", "localhost")
+        self.port = get("port")
+        self.tls = get("tls", True)
+        self.relay, self.key, self.fingerprint = get("relay"), get("key"), get("fingerprint")
+        self._require()
+
+    def __repr__(self):
+        where = {"local": f"local, {self.host}:{self.port}", "wifi": "sur le wifi", "network": f"via le relais {self.relay}"}[self.mode]
+        return f"<capy.Project {self.name!r} ({where}, {'chiffré' if self.tls else 'en clair'})>"
+
+    # Vérifier qu'il ne manque rien pour ce mode
+    def _require(self):
+        if self.mode not in MODES:
+            raise ValueError(f"capy.project : mode {self.mode!r} inconnu dans {self.path.name}, choisis parmi : {', '.join(MODES)}")
+        if self.mode == "local" and self.port is None:
+            raise ValueError(f'capy.project : il manque "port" dans {self.path.name} (ex : "port": 4000)')
+        if self.mode == "network" and not self.relay:
+            raise ValueError(f'capy.project : il manque "relay" dans {self.path.name} (ex : "relay": "mon-vps.fr:3879")')
+        if self.mode == "network" and not self.tls:
+            raise ValueError("capy.project : capy.network est toujours chiffré, enlève \"tls\": false")
+
+    # Le serveur de ce projet, déjà réglé (port, nom, chiffrement, relais)
+    # Ex : server = app.server() ; @server.action("hello") ... ; server.run()
+    def server(self):
+        import capy
+        if self.mode == "local":
+            return capy.Server(self.port, tls=self.tls)
+        if self.mode == "wifi":
+            import capy.wifi
+            return capy.wifi.Server(self.name, port=self.port or 0, tls=self.tls)
+        self._use_relay()
+        import capy.network
+        return capy.network.Server(self.name)
+
+    # Appeler une action du serveur de ce projet (sans redonner l'IP, le port ni le relais)
+    # Ex : app.call("hello", nom="Izac") -> {"message": "Bonjour Izac !"}
+    def call(self, action, /, **params) -> Any:
+        import capy
+        if self.mode == "local":
+            return capy.call(self.host, self.port, action, tls=self.tls, **params)
+        if self.mode == "wifi":
+            import capy.wifi
+            return capy.wifi.call(self.name, action, tls=self.tls, **params)
+        self._use_relay()
+        import capy.network
+        return capy.network.call(self.name, action, **params)
+
+    # Régler capy.network sur le relais du projet (seulement s'il a changé : use() ferme les connexions ouvertes)
+    def _use_relay(self):
+        import capy.network
+        wanted = {"relay": self.relay, "key": self.key, "fingerprint": self.fingerprint}
+        if capy.network._config != wanted:
+            capy.network.use(self.relay, key=self.key, fingerprint=self.fingerprint)
+
+
+# Vérifier le contenu du fichier : clés connues, bons types, variables d'environnement
+def _check(data, file):
+    result = {}
+    for key, value in data.items():
+        if key not in FIELDS:
+            close = difflib.get_close_matches(key, FIELDS, n=1)
+            hint = f" (tu voulais dire {close[0]!r} ?)" if close else f" (clés possibles : {', '.join(FIELDS)})"
+            raise ValueError(f"capy.project : clé {key!r} inconnue dans {file}{hint}")
+        types, help_text = FIELDS[key]
+        if isinstance(value, str) and value.startswith("$") and len(value) > 1:
+            env = value[1:]
+            if env not in os.environ:
+                raise ValueError(f"capy.project : {key!r} vaut {value!r} mais la variable d'environnement {env} n'existe pas"
+                                 f" (ajoute export {env}='...' dans ~/.zshrc)")
+            value = os.environ[env]
+            if int in types and value.isdigit():
+                value = int(value)
+        if value is None:
+            continue
+        if not isinstance(value, types) or (bool not in types and isinstance(value, bool)):
+            raise ValueError(f"capy.project : {key!r} doit être {_type_name(types)} dans {file} : {help_text}")
+        result[key] = value
+    return result
+
+
+def _type_name(types):
+    return {str: "un texte", int: "un nombre", bool: "true ou false"}[types[0]]
+
+
+# Lire le capy.config.json du projet -> Project
+# Sans chemin : cherché à côté du script lancé, puis dans les dossiers au-dessus
+# Ex : app = capy.project() / capy.project("autre.json") / capy.project("~/projets/jeu")
+def project(path=None) -> Project:
+    if path is None:
+        found = find()
+        if found is None:
+            raise FileNotFoundError(
+                f"capy.project : aucun {FILE_NAME} trouvé dans {_main_dir()} ni au-dessus.\n"
+                f"  Crée-le avec : python3 -m capy init\n"
+                f"  ou écris-le toi-même, par exemple : {jsonlib.dumps(EXAMPLE, ensure_ascii=False)}"
+            )
+        return Project(found)
+    path = pth.Path(path).expanduser()
+    if not path.is_absolute():
+        path = _main_dir() / path
+    return Project(path / FILE_NAME if path.is_dir() else path)
+
+
+# Écrire un capy.config.json de départ (python3 -m capy init [nom] [mode])
+def init(folder=None, name=None, mode="local"):
+    if mode not in MODES:
+        raise ValueError(f"capy init : mode {mode!r} inconnu, choisis parmi : {', '.join(MODES)}")
+    folder = pth.Path(folder or pth.Path.cwd())
+    path = folder / FILE_NAME
+    if path.exists():
+        raise FileExistsError(f"capy init : {path} existe déjà (supprime-le d'abord pour en refaire un)")
+    data = {"name": name or folder.resolve().name, "mode": mode}
+    if mode == "local":
+        data.update(host="localhost", port=4000)
+    elif mode == "network":
+        data.update(relay="mon-vps.fr:3879", key="$CAPY_KEY")
+    data["tls"] = True
+    path.write_text(jsonlib.dumps(data, indent=4, ensure_ascii=False) + "\n", encoding="utf-8")
+    return path

{capyy-0.3.2 → capyy-0.4.0}/capy/network.py

@@ -296,7 +296,7 @@ class Relay:
         except ConnectionError:
             return
         if reply["capy"] == "ok":
-            _log(f"  {name} ← {jsonlib.dumps(request, ensure_ascii=False)}")
+            _log(f"  {name} ← {capy._hide(request)}")
 
     def run(self):
         self.context, fingerprint = _relay_context()

{capyy-0.3.2 → capyy-0.4.0/capyy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capyy
-Version: 0.3.2
+Version: 0.4.0
 Summary: Tiny encrypted JSON-over-TCP APIs: call a function in another program, on your Wi-Fi or across the internet
 Author: Izac
 License-Expression: MIT
@@ -73,6 +73,23 @@ capy.to_int("42"), capy.to_bool("yes")  # 42, True
 `to_str`, `to_int`, `to_float`, `to_bool`, `to_list` and `to_dict` raise a `ValueError` that says exactly
 what could not be converted.
 
+## Project file: capy.config.json
+
+Describe the project once (`python3 -m capy init my-game` creates it), then never repeat ports or hosts:
+
+```json
+{"name": "my-game", "mode": "local", "host": "localhost", "port": 4000, "tls": true}
+```
+
+```python
+app = capy.project()            # finds capy.config.json next to the script, or in a parent folder
+server = app.server()           # server side
+app.call("hello", nom="Izac")   # client side
+```
+
+`mode` can be `local`, `wifi` or `network` (with `relay`, `key`, `fingerprint`). Strings starting with `$` are read
+from environment variables, e.g. `"key": "$CAPY_KEY"`.
+
 ## Encryption (TLS)
 
 Everything is encrypted by default, with nothing to configure.

{capyy-0.3.2 → capyy-0.4.0}/capyy.egg-info/SOURCES.txt

@@ -2,6 +2,8 @@ LICENSE
 README.md
 pyproject.toml
 capy/__init__.py
+capy/__main__.py
+capy/_project.py
 capy/_tls.py
 capy/network.py
 capy/wifi.py

{capyy-0.3.2 → capyy-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "capyy"
-version = "0.3.2"
+version = "0.4.0"
 description = "Tiny encrypted JSON-over-TCP APIs: call a function in another program, on your Wi-Fi or across the internet"
 readme = "README.md"
 requires-python = ">=3.9"

{capyy-0.3.2 → capyy-0.4.0}/tests/test_capy.py

@@ -1,5 +1,7 @@
 # Tests de capy : python3 -m unittest discover -s tests
 
+import json
+import os
 import pathlib
 import socket
 import tempfile
@@ -48,6 +50,15 @@ def demo_server(server):
     def text():
         return capy.json('{"text": "Hello"}')
 
+    @server.action("not_json")
+    def not_json():
+        return {1, 2}  # Un set : impossible en JSON
+
+    @server.action("slow")
+    def slow():
+        time.sleep(3.5)
+        return {"ok": True}
+
     return server
 
 
@@ -127,6 +138,14 @@ class TestCall(unittest.TestCase):
         with self.assertRaises(ConnectionError):
             capy.call("localhost", free_port(), "hello")
 
+    def test_not_json_reply(self):
+        reply = capy.call("localhost", self.tls.port, "not_json")
+        self.assertIn("réponse pas en JSON", reply["erreur"])
+
+    def test_too_slow(self):
+        with self.assertRaisesRegex(ConnectionError, "pas répondu à temps"):
+            capy.call("localhost", self.plain.port, "slow", tls=False)
+
     def test_bad_arguments(self):
         with self.assertRaises(TypeError):
             capy.call(4000, "hello", "localhost")
@@ -203,5 +222,82 @@ class TestNetwork(unittest.TestCase):
             capy.network.call("maison", "hello")
 
 
+class TestProject(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.dir = pathlib.Path(self.tmp.name)
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def write(self, data, folder=None):
+        path = (folder or self.dir) / "capy.config.json"
+        path.write_text(json.dumps(data))
+        return path
+
+    def test_local_server_and_call(self):
+        port = free_port()
+        self.write({"name": "demo", "mode": "local", "host": "localhost", "port": port})
+        app = capy.project(self.dir)
+        self.assertEqual((app.name, app.mode, app.port, app.tls), ("demo", "local", port, True))
+        start(demo_server(app.server()))
+        self.assertEqual(app.call("hello", name="Zoe"), {"message": "Bonjour Zoe"})
+
+    def test_find_in_parent_folder(self):
+        self.write({"port": 4000})
+        sub = self.dir / "client" / "src"
+        sub.mkdir(parents=True)
+        self.assertEqual(capy._project.find(sub), (self.dir / "capy.config.json").resolve())
+        app = capy.project(self.dir / "capy.config.json")
+        self.assertEqual((app.name, app.mode, app.host), (self.dir.name, "local", "localhost"))  # Valeurs par défaut
+
+    def test_env_variables(self):
+        os.environ["CAPY_TEST_KEY"], os.environ["CAPY_TEST_PORT"] = "s3cret", "4100"
+        self.write({"relay": "mon-vps.fr:3879", "key": "$CAPY_TEST_KEY", "port": "$CAPY_TEST_PORT"})
+        app = capy.project(self.dir)
+        self.assertEqual((app.mode, app.key, app.port), ("network", "s3cret", 4100))  # relay -> mode network
+        self.write({"relay": "mon-vps.fr:3879", "key": "$CAPY_PAS_LA"})
+        with self.assertRaisesRegex(ValueError, "CAPY_PAS_LA n'existe pas"):
+            capy.project(self.dir)
+
+    def test_errors(self):
+        with self.assertRaisesRegex(FileNotFoundError, "pas de fichier"):
+            capy.project(self.dir / "absent.json")
+        for data, message in (
+            ({"prot": 4000}, "tu voulais dire 'port'"),
+            ({"port": "4000"}, "doit être un nombre"),
+            ({"port": True}, "doit être un nombre"),
+            ({"mode": "local"}, 'il manque "port"'),
+            ({"mode": "bluetooth"}, "mode 'bluetooth' inconnu"),
+            ({"mode": "network"}, 'il manque "relay"'),
+            ({"tls": "oui", "port": 1}, "true ou false"),
+        ):
+            self.write(data)
+            with self.assertRaisesRegex(ValueError, message):
+                capy.project(self.dir)
+        (self.dir / "capy.config.json").write_text("{pas du json")
+        with self.assertRaisesRegex(ValueError, "pas du JSON valide"):
+            capy.project(self.dir)
+
+    def test_wifi_and_network_servers(self):
+        self.write({"name": "salon", "mode": "wifi", "tls": False})
+        server = capy.project(self.dir).server()
+        self.assertIsInstance(server, capy.wifi.Server)
+        self.assertEqual((server.name, server.port, server.tls), ("salon", 0, False))
+        self.write({"name": "garage", "relay": "127.0.0.1:1", "key": "k"})
+        self.assertIsInstance(capy.project(self.dir).server(), capy.network.Server)
+        self.assertEqual(capy.network._config["relay"], "127.0.0.1:1")
+
+    def test_init(self):
+        path = capy._project.init(self.dir, name="jeu")
+        self.assertEqual(json.loads(path.read_text())["name"], "jeu")
+        self.assertEqual(capy.project(path).port, 4000)
+        with self.assertRaises(FileExistsError):
+            capy._project.init(self.dir)
+        (self.dir / "net").mkdir()
+        path = capy._project.init(self.dir / "net", mode="network")
+        self.assertEqual(json.loads(path.read_text())["key"], "$CAPY_KEY")
+
+
 if __name__ == "__main__":
     unittest.main()