capyy — tiny encrypted JSON-over-TCP APIs

Call a function in another Python program — on the same machine, on your Wi-Fi, or across the internet — with one line of code. Zero dependencies, Python 3.9+, encrypted with TLS by default.

pip install capyy

The package is published as capyy, but you import it as capy. Error messages are in French (the library was written for French speakers), and the full documentation, with examples, is at libs.zazac.link/capy.

Quick start

# server.py
import capy

api = capy.Server(4000)

@api.action("hello")
def hello(name="you"):
    return {"message": f"Hello {name}!"}

api.run()

# client.py
import capy

print(capy.call("localhost", 4000, "hello", name="Alice"))   # {'message': 'Hello Alice!'}

• An action returns a dict, or JSON written as text with capy.json('{"text": "Hello"}').
• Errors raised on the server come back as {"erreur": "..."} (unknown action, bad parameters, exceptions).
• capy.call raises ConnectionError when the server does not answer.

Reading a response

reply = {"city": "Paris", "temp": "18.5", "days": [{"name": "monday"}, {"name": "tuesday"}]}

capy.get(reply, "days.1.name")          # "tuesday"  (paths go through dicts and lists)
capy.get(reply, "wind", default=0)      # 0
capy.to_float(reply, "temp")            # 18.5
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 whole project once, then never repeat ports or hosts:

python3 -m capy new my-game     # folder + capy.config.json + server.py + client.py
cd my-game
cy run             # starts the server, runs the client, stops the server

{"name": "my-game", "version": "1.0", "mode": "local", "url": "127.0.0.1:2388", "tls": true,
 "files": {"server": "server.py", "client": "client.py"}}

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". Inside a project, the cy command runs its scripts like npm run (cy test, cy start) and its files (cy server); create a project with python3 -m capy new.

Encryption (TLS)

Everything is encrypted by default, with nothing to configure.

• Each machine running a server creates its own certificate on first launch (~/.capy, using openssl) and prints its fingerprint.
• Like SSH, a client remembers a server's fingerprint the first time (~/.capy/known_hosts.json) and raises capy.SecurityError if it ever changes.
• The server logs every request, but never secrets: parameters whose name contains password, pwd, mdp, secret or token are shown as "***".
• Use tls=False on both sides to talk in clear (faster on localhost).

capy.wifi — find each other on the same network

import capy.wifi

api = capy.wifi.Server("living-room")   # announces itself on the LAN, port chosen automatically
...
capy.wifi.call("living-room", "light", on=False)   # from any device on the same Wi-Fi
capy.wifi.scan()                                    # {'living-room': ('192.168.1.42', 51234)}

capy.network — across the internet, through a relay

A machine behind a home router cannot be reached from the internet, so capy.network goes through a relay running on a machine with a public IP (a VPS). Servers connect to it and register a name; clients call that name. Everything is encrypted, and the connection is kept open between calls.

python3 -m capy.network 3879 my-secret-key      # on the VPS (open the port in its firewall)

import capy.network

capy.network.use("my-vps.example:3879", key="my-secret-key")
capy.network.Server("home").run()        # at home, even behind a router
capy.network.call("home", "temperature") # from anywhere

capy.domo — home automation

One way to drive lights and plugs from Philips Hue, WiZ, Shelly, Yeelight and Home Assistant (and everything Home Assistant supports), on your local network, with zero dependencies:

import capy.domo

home = capy.domo.Home()        # devices, groups and scenes live in capy.domo.json
home.scan()                    # find devices on the network
home["salon"].color("orange")  # a device, a group, or "tout" (everything)
home.scene("film")
capy.domo.serve(home)          # control it remotely through capy / capy.wifi / capy.network

python3 -m capy.domo scan
python3 -m capy.domo pair hue
python3 -m capy.domo salon on 30% orange

License

MIT