docs: mention the new WokwiClientSync + update changelog

Author: urish

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.1.0 - 2025-08-22
+
+- feat: add WokwiClientSync - a synchronous Wokwi client (#9)
+
 ## 0.0.9 - 2025-08-21
 
 - feat: add gpio_list method to retrieve all GPIO pins in WokwiClient (#6)

README.md

@@ -1,19 +1,24 @@
 # Wokwi Python Client 🚀
 
-Typed, asyncio-friendly Python SDK for the **Wokwi Simulation API**
+Typed Python SDK for the **Wokwi Simulation API** with both async and synchronous interfaces
 
 [![PyPI version](https://img.shields.io/pypi/v/wokwi-client?logo=pypi)](https://pypi.org/project/wokwi-client/)
 [![Python versions](https://img.shields.io/pypi/pyversions/wokwi-client)](https://pypi.org/project/wokwi-client/)
 [![CI](https://github.com/wokwi/wokwi-python-client/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/wokwi/wokwi-python-client/actions/workflows/ci.yaml)
 [![License: MIT](https://img.shields.io/github/license/wokwi/wokwi-python-client)](LICENSE)
 
-> **TL;DR:** Run and control your Wokwi simulations from Python with first-class type hints and zero boilerplate.
+> **TL;DR:** Run and control your Wokwi simulations from Python with first-class type hints, zero boilerplate, and both async and synchronous APIs.
 
 ---
 
 Wokwi is a platform for creating and running simulations of electronic circuits and embedded systems. It supports a wide range of hardware platforms, including ESP32 family, Arduino, Raspberry Pi, STM32 and more.In addition, it supports a [wide range of peripherals](https://docs.wokwi.com/getting-started/supported-hardware), including sensors, displays, motors, and debugging tools.
 
-Wokwi Python Client is a Python SDK for the Wokwi Simulation API. It allows you to run and control your Wokwi simulations from Python in a typed, asyncio-friendly way. You can use it to automate your embedded testing and development workflows.
+Wokwi Python Client is a Python SDK for the Wokwi Simulation API. It provides two client interfaces:
+
+- **`WokwiClient`**: Async client with full asyncio support for modern Python applications
+- **`WokwiClientSync`**: Synchronous client that mirrors the async API for traditional blocking code
+
+Both clients allow you to run and control your Wokwi simulations from Python in a typed, easy-to-use way. You can use them to automate your embedded testing and development workflows.
 
 ## Installation requirements
 
@@ -27,20 +32,31 @@ pip install wokwi-client
 
 ## Running the examples
 
-The basic example is in the [examples/hello_esp32/main.py](examples/hello_esp32/main.py) file. It shows how to:
+### Async Example
+
+The basic async example is in the [examples/hello_esp32/main.py](examples/hello_esp32/main.py) file. It shows how to:
 
 - Connect to the Wokwi Simulator
 - Upload a diagram and firmware files
 - Start a simulation
 - Monitor serial output asynchronously
 
-You can run the example with:
+You can run the async example with:
 
 ```bash
 pip install -e .[dev]
 python -m examples.hello_esp32.main
 ```
 
+### Sync Example
+
+The synchronous example is in the [examples/hello_esp32_sync/main.py](examples/hello_esp32_sync/main.py) file. It demonstrates the same functionality using the blocking `WokwiClientSync`:
+
+```bash
+pip install -e .[dev]
+python -m examples.hello_esp32_sync.main
+```
+
 For more examples, see the [examples](examples) directory.
 
 ## Documentation

docs/index.md

@@ -1,6 +1,6 @@
 # Wokwi Python Client Library
 
-Typed, asyncio-friendly Python SDK for the **Wokwi Simulation API**.
+Typed Python SDK for the **Wokwi Simulation API** with both async and synchronous interfaces.
 
 ## Features
 
@@ -9,7 +9,8 @@ Typed, asyncio-friendly Python SDK for the **Wokwi Simulation API**.
 - Start, pause, resume, and restart simulations
 - Monitor serial output asynchronously and write to them
 - Control peripherals and read GPIO pins
-- Fully type-annotated and easy to use with asyncio
+- Fully type-annotated
+- Two client interfaces: `WokwiClient` (async) and `WokwiClientSync` (sync)
 
 ## Installation
 
@@ -23,7 +24,9 @@ pip install wokwi-client
 
 Get your API token from [https://wokwi.com/dashboard/ci](https://wokwi.com/dashboard/ci).
 
-## Quickstart Example
+## Quickstart Examples
+
+### Async Client (WokwiClient)
 
 ```python
 import asyncio
@@ -55,7 +58,41 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-See the [examples/hello_esp32/main.py](https://github.com/wokwi/wokwi-python-client/blob/main/examples/hello_esp32/main.py) for a full example including serial monitoring, and [examples/micropython_esp32/main.py](https://github.com/wokwi/wokwi-python-client/blob/main/examples/micropython_esp32/main.py) for an example of running MicroPython on a simulated ESP32 board.
+For a complete example, see [examples/hello_esp32/main.py](https://github.com/wokwi/wokwi-python-client/blob/main/examples/hello_esp32/main.py).
+
+### Sync Client (WokwiClientSync)
+
+```python
+import os
+from wokwi_client import WokwiClientSync, GET_TOKEN_URL
+
+
+def main():
+    token = os.getenv("WOKWI_CLI_TOKEN")
+    if not token:
+        raise SystemExit(
+            f"Set WOKWI_CLI_TOKEN in your environment. You can get it from {GET_TOKEN_URL}."
+        )
+
+    client = WokwiClientSync(token)
+    client.connect()
+    client.upload_file("diagram.json")
+    client.upload_file("firmware.bin")
+    client.start_simulation(firmware="firmware.bin")
+    client.serial_monitor_cat()  # Stream serial output
+    client.wait_until_simulation_time(10)  # Run simulation for 10 seconds
+    client.disconnect()
+
+
+if __name__ == "__main__":
+    main()
+```
+
+For a complete example, see [examples/hello_esp32_sync/main.py](https://github.com/wokwi/wokwi-python-client/blob/main/examples/hello_esp32_sync/main.py).
+
+### MicroPython Example
+
+See [examples/micropython_esp32/main.py](https://github.com/wokwi/wokwi-python-client/blob/main/examples/micropython_esp32/main.py) for an example of running MicroPython on a simulated ESP32 board.
 
 ## API Reference
 

docs/reference/wokwi_client.md

@@ -1 +1,3 @@
-::: wokwi_client
+::: wokwi_client.WokwiClient
+
+::: wokwi_client.WokwiClientSync

mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: Wokwi Python Client Library
-site_description: Typed, asyncio-friendly Python SDK for the Wokwi Simulation API
+site_description: Typed Python SDK for the Wokwi Simulation API with both async and synchronous interfaces
 site_url: https://wokwi.github.io/wokwi-python-client/
 
 repo_url: https://github.com/wokwi/wokwi-python-client

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "wokwi-client"
 dynamic = ["version"]
-description = "Typed, asyncio-friendly Python SDK for the Wokwi Simulation API"
+description = "Typed Python SDK for the Wokwi Simulation API with both async and synchronous interfaces"
 readme = "README.md"
 authors = [{ name = "Uri Shaked", email = "uri@wokwi.com" }]
 license = "MIT"

src/wokwi_client/__init__.py

@@ -1,9 +1,10 @@
 """
 Wokwi Python Client Library
 
-Typed, asyncio-friendly Python SDK for the Wokwi Simulation API.
+Typed Python SDK for the Wokwi Simulation API with both async and synchronous interfaces.
 
-Provides the WokwiClient class for connecting to, controlling, and monitoring Wokwi simulations from Python.
+Provides both WokwiClient (async) and WokwiClientSync (sync) classes for connecting to,
+controlling, and monitoring Wokwi simulations from Python.
 """
 
 # SPDX-FileCopyrightText: 2025-present CodeMagic LTD

src/wokwi_client/client.py

@@ -31,7 +31,7 @@ class WokwiClient:
 
     This class provides methods to connect to the Wokwi simulator, upload files, control simulations,
     and monitor serial output. It is designed to be asyncio-friendly and easy to use in Python scripts
-    and applications.
+    and applications. For a synchronous interface, see WokwiClientSync.
     """
 
     version: str