Install & Compatibility
Where this runs
tested against v2.5.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 28.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.1s · import 0.000s · 31MB
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Server
✓ from wslink import server
✗ from wslink import Server
register
✓ from wslink import register
schedule_callback
✓ from wslink import schedule_callback
This quickstart demonstrates how to create a basic `wslink` Python server with two Remote Procedure Call (RPC) methods: `my.hello` for greetings and `my.add` for adding numbers. It defines a custom protocol and handler, then uses `run_wslink` to start the server. Clients can connect via WebSocket to `ws://127.0.0.1:8080` and call the exposed methods.
import asyncio
import logging
from wslink import Server
from wslink.websocket import WslinkHandler, run_wslink
from wslink.protocols import WslinkServerProtocol
# Configure logging for better visibility
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
logger = logging.getLogger(__name__)
class MyProtocol(WslinkServerProtocol):
"""A simple protocol demonstrating RPC."""
def initialize(self):
# Register this protocol for RPC calls
self.registerVtkWebProtocol(self)
logger.info("MyProtocol initialized.")
@Server.expose("my.hello")
def hello_world(self, name="World"):
"""An RPC method that returns a greeting."""
logger.info(f"RPC 'my.hello' called with name='{name}'.")
return f"Hello, {name} from wslink!"
@Server.expose("my.add")
def add_numbers(self, a, b):
"""An RPC method that adds two numbers."""
logger.info(f"RPC 'my.add' called with a={a}, b={b}.")
return a + b
class MyWslinkHandler(WslinkHandler):
"""Custom wslink handler to use our protocol."""
protocol_class = MyProtocol
async def main():
# Set the host and port for the WebSocket server
host = "127.0.0.1"
port = 8080
logger.info(f"Starting wslink server on ws://{host}:{port}")
logger.info("Press Ctrl+C to stop the server.")
# Run the wslink server
await run_wslink(
port=port,
host=host,
ws=MyWslinkHandler,
# Optionally, set a secret for client authentication:
# secret=os.environ.get('WSLINK_SECRET', 'your_default_secret')
)
if __name__ == "__main__":
try:
asyncio.run(main())
except KeyboardInterrupt:
logger.info("Server stopped by user (KeyboardInterrupt).")
except Exception as e:
logger.error(f"An unexpected error occurred: {e}")
Debug
Known issues
gotchaThe wslink server may not reliably detect all forms of client disconnections (e.g., abrupt network loss). This can lead to `ConnectionResetError` exceptions in server logs or the server continuing to manage stale connections indefinitely, potentially impacting stability and resource usage.fixImplement robust client-side reconnection logic. On the server, consider implementing application-level heartbeats or more aggressive session timeout mechanisms. Monitor server logs for `ConnectionResetError` and potentially integrate graceful server restarts or more sophisticated session cleanup strategies.
affects: All versions relying on `aiohttp` for transport (observed in `v2.x`).
gotchaProtocol compatibility between the Python server and the JavaScript/C++ client is crucial. Mismatched `wslink` library versions or incompatible RPC method signatures between client and server can lead to communication failures or unexpected behavior.fixEnsure that the `wslink` library versions used on both the client and server sides are compatible. Always consult the official documentation and changelog when upgrading either component to verify protocol changes or API updates.
affects: All versions.
gotchaThis PyPI package (`wslink`) provides the Python server-side implementation. The corresponding client-side library for web browsers (JavaScript) is distributed separately via npm under the name `@kitware/wslink`. Attempting to use Python server modules directly in a browser environment or vice-versa will result in errors.fixUse `pip install wslink` for your Python backend services. For web-based frontends, install the client library using `npm install @kitware/wslink`.
affects: All versions.
Upgrade
Version history
2.5.7latest on PyPI · released May 15, 2026
Audit
Dependencies
No dependency data recorded yet.