Skip to content

Commit f040728

Browse files
jsurreajsurrea
committed
update docs
1 parent 5acfdd3 commit f040728

File tree

7 files changed

+326
-35
lines changed

7 files changed

+326
-35
lines changed

‎antares-python/README.md‎

Lines changed: 225 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,68 +1,265 @@
1-
# antares-python
1+
# Antares Python Client
22

3-
[![CI](https://github.com/TheSoftwareDesignLab/ANTARES/actions/workflows/python-ci.yml/badge.svg)](https://github.com/TheSoftwareDesignLab/ANTARES/actions/workflows/python-ci.yml)
4-
[![codecov](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/TheSoftwareDesignLab/ANTARES)
5-
[![PyPI version](https://img.shields.io/pypi/v/antares-python.svg)](https://pypi.org/project/antares-python/)
6-
[![Python version](https://img.shields.io/pypi/pyversions/antares-python)](https://pypi.org/project/antares-python/)
7-
[![License](https://img.shields.io/github/license/TheSoftwareDesignLab/ANTARES)](LICENSE)
3+
> ✨ A modern Python interface for the Antares simulation engine ✨
84
9-
> Python interface for the [Antares](https://github.com/TheSoftwareDesignLab/ANTARES) simulation software
5+
Antares Python Client is a developer-friendly library and CLI tool that allows you to interact with the Antares simulation engine via HTTP and TCP protocols.
106

11-
`antares-python` is a facade library that allows Python developers to interact with the Antares simulation engine via HTTP. It provides a clean, user-friendly API for submitting simulations, retrieving results, and managing scenarios — similar to how `pyspark` interfaces with Apache Spark.
7+
- Provides a high-level Python API to control the simulation
8+
- Automatically maps Python objects to Antares-native requests
9+
- Supports configuration via `.env` and `.toml` files
10+
- Offers a CLI for scripting and manual control
11+
- Built with Pydantic 2, Typer, and fully type-annotated
12+
13+
Inspired by tools like PySpark, this library acts as a thin but powerful façade over the Antares backend.
1214

1315
---
1416

15-
## 🚀 Features
17+
## 🌟 Features
1618

17-
- 🔁 Async + sync HTTP client
18-
- 🔒 Typed schema validation (coming soon)
19-
- 📦 Built-in support for data serialization
20-
- 🧪 Fully testable with mocks
21-
- 🛠️ First-class CLI support (planned)
19+
- Add ships with complex motion patterns to the simulation
20+
- Subscribe to live simulation events over TCP
21+
- Launch the Antares binary locally with config
22+
- Configure everything via `.env` or `.toml`
23+
- Clean CLI with rich output and JSON support
2224

2325
---
2426

25-
## 📦 Installation
27+
## 🚀 Installation
28+
29+
### Requirements
30+
31+
- Python >= 3.13 (tested with 3.13)
32+
- `uv` for isolated dev environments
33+
34+
### Install from PyPI
2635

2736
```bash
2837
pip install antares-python
2938
```
3039

40+
### Install in editable mode (for development)
41+
42+
```bash
43+
git clone https://github.com/TheSoftwareDesignLab/ANTARES.git
44+
cd ANTARES/antares-python
45+
uv venv
46+
source .venv/bin/activate
47+
uv pip install -e .
48+
```
49+
50+
---
51+
52+
## 🚧 CLI Usage (`antares-cli`)
53+
54+
After installing, the CLI tool `antares-cli` becomes available.
55+
56+
### Available Commands
57+
58+
| Command | Description |
59+
|---------------|--------------------------------------------------|
60+
| `add-ship` | Add a ship with specific motion type |
61+
| `reset` | Reset the simulation |
62+
| `subscribe` | Subscribe to simulation event stream |
63+
| `start` | Start the Antares binary with optional config |
64+
65+
### Common Options
66+
67+
| Option | Description |
68+
|---------------|-------------------------------------------------|
69+
| `--config` | Path to `.toml` config file |
70+
| `--verbose` | Enable detailed output |
71+
| `--json` | Output results in JSON format |
72+
73+
Example:
74+
75+
```bash
76+
antares-cli add-ship --type line --x 0 --y 0 --angle 0.5 --speed 5.0
77+
```
78+
3179
---
3280

33-
## ⚡ Quickstart
81+
## 📚 Python Usage Example
3482

3583
```python
36-
from antares import AntaresClient
84+
import asyncio
85+
from antares.client import AntaresClient
86+
from antares.models.ship import LineShip, CircleShip, RandomShip, StationaryShip
87+
from antares.models.track import Track
88+
89+
90+
async def main():
91+
# Create the Antares client using environment config or .env file
92+
client = AntaresClient()
3793

38-
client = AntaresClient(base_url="http://localhost:8000")
94+
# Define ships of each supported type
95+
ships = [
96+
StationaryShip(initial_position=(0.0, 0.0), type="stationary"),
97+
RandomShip(initial_position=(10.0, -10.0), max_speed=15.0, type="random"),
98+
CircleShip(initial_position=(-30.0, 20.0), radius=25.0, speed=3.0, type="circle"),
99+
LineShip(initial_position=(5.0, 5.0), angle=0.78, speed=4.0, type="line"),
100+
]
39101

40-
# Submit a simulation
41-
result = client.run_simulation(config={...})
42-
print(result.metrics)
102+
# Add each ship to the simulation
103+
for ship in ships:
104+
client.add_ship(ship)
105+
print(f"✅ Added {ship.type} ship at {ship.initial_position}")
106+
107+
print("\n📡 Subscribing to simulation events...\n")
108+
109+
# Listen to simulation events (TCP stream)
110+
async for event in client.subscribe():
111+
if isinstance(event, Track):
112+
print(
113+
f"📍 Track #{event.id} - {event.name} at ({event.lat}, {event.long}) → {event.speed} knots"
114+
)
115+
116+
117+
if __name__ == "__main__":
118+
# Run the main async function
119+
asyncio.run(main())
43120
```
44121

45122
---
46123

47-
## 📚 Documentation
124+
## 🧭 Ship Types
125+
126+
Ships are classified based on their motion pattern. The `type` field determines which parameters are required. Here's a summary:
127+
128+
| Type | Required Fields | Description |
129+
|-------------|---------------------------------------------|---------------------------------------------|
130+
| `stationary`| `initial_position` | Does not move at all |
131+
| `random` | `initial_position`, `max_speed` | Moves randomly, up to a max speed |
132+
| `circle` | `initial_position`, `radius`, `speed` | Moves in a circular pattern |
133+
| `line` | `initial_position`, `angle`, `speed` | Moves in a straight line |
134+
135+
Each ship type corresponds to a specific Pydantic model:
136+
137+
- `StationaryShip`
138+
- `RandomShip`
139+
- `CircleShip`
140+
- `LineShip`
141+
142+
You can also use the generic `ShipConfig` union to parse from dynamic input like TOML or JSON.
143+
144+
---
145+
146+
## ⚙️ Configuration
147+
148+
The client supports two configuration methods:
149+
150+
### `.env` File
48151

49-
_Work in progress — full API docs coming soon._
152+
The `.env` file allows you to define environment variables:
153+
154+
```dotenv
155+
ANTARES_HOST=localhost
156+
ANTARES_HTTP_PORT=9000
157+
ANTARES_TCP_PORT=9001
158+
ANTARES_TIMEOUT=5.0
159+
ANTARES_AUTH_TOKEN=
160+
```
161+
162+
➡️ See `template.env` for a complete example.
163+
164+
### `.toml` Config File
165+
166+
To configure the client and ships via a TOML file:
167+
168+
```toml
169+
[antares]
170+
host = "localhost"
171+
http_port = 9000
172+
tcp_port = 9001
173+
timeout = 5.0
174+
auth_token = ""
175+
176+
[[antares.ships.stationary]]
177+
initial_position = [50.0, 50.0]
178+
179+
[[antares.ships.random]]
180+
initial_position = [-20.0, 20.0]
181+
max_speed = 10.0
182+
183+
[[antares.ships.circle]]
184+
initial_position = [30.0, -30.0]
185+
radius = 20.0
186+
speed = 4.0
187+
188+
[[antares.ships.line]]
189+
initial_position = [0.0, 0.0]
190+
angle = 0.785
191+
speed = 5.0
192+
```
193+
194+
➡️ See `config.example.toml` for a full working example.
195+
196+
You can pass the config to any CLI command with:
197+
198+
```bash
199+
antares-cli add-ship --config path/to/config.toml
200+
```
201+
202+
Or use it in Python with:
203+
204+
```python
205+
from antares.config_loader import load_config
206+
settings = load_config("config.toml")
207+
```
50208

51209
---
52210

53-
## 🧪 Development
211+
## 🧪 Development & Testing
212+
213+
This project uses modern Python tooling for fast, isolated, and productive workflows.
54214

55-
To set up a local development environment:
215+
### Setup
56216

57217
```bash
58218
uv venv
59219
source .venv/bin/activate
60220
uv pip install -e .[dev]
61-
task check
221+
```
222+
223+
### Available Tasks (via [`task`](https://taskfile.dev))
224+
225+
| Task | Description |
226+
|----------------|---------------------------------------------|
227+
| `task check` | Run linters (ruff, mypy) and formatter check |
228+
| `task test` | Run full test suite |
229+
| `task format` | Auto-format code with ruff + black |
230+
| `task build` | Build the wheel and source dist |
231+
| `task publish` | Publish to PyPI (requires version bump) |
232+
233+
### Run tests manually
234+
235+
```bash
236+
pytest
237+
```
238+
239+
### View test coverage
240+
241+
```bash
242+
pytest --cov=antares --cov-report=term-missing
62243
```
63244

64245
---
65246

66-
## 🧾 License
247+
## 📄 License
248+
249+
This project is licensed under the MIT License. See the [LICENSE](../LICENSE) file for details.
250+
251+
---
252+
253+
## 🤝 Contributing
254+
255+
Contributions are welcome! To contribute:
256+
257+
1. Fork the repository
258+
2. Create a new branch (`git checkout -b feature/my-feature`)
259+
3. Make your changes
260+
4. Run `task check` and `task test` to ensure quality
261+
5. Submit a pull request 🚀
262+
263+
For significant changes, please open an issue first to discuss what you’d like to do.
67264

68-
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
265+
Happy hacking! 🛠️

‎antares-python/antares.log‎

Whitespace-only changes.

‎antares-python/config.example.toml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# ============================
2+
# Antares Simulation Config
3+
# Example TOML configuration
4+
# ============================
5+
6+
[antares]
7+
host = "localhost"
8+
http_port = 9000
9+
tcp_port = 9001
10+
timeout = 5.0
11+
auth_token = ""
12+
13+
# ============================
14+
# Ships to add at startup
15+
# ============================
16+
17+
[[antares.ships.line]]
18+
initial_position = [0.0, 0.0]
19+
angle = 0.785 # radians (approx. 45 degrees)
20+
speed = 5.0
21+
22+
[[antares.ships.circle]]
23+
initial_position = [30.0, -30.0]
24+
radius = 20.0
25+
speed = 4.0
26+
27+
[[antares.ships.random]]
28+
initial_position = [-20.0, 20.0]
29+
max_speed = 10.0
30+
31+
[[antares.ships.stationary]]
32+
initial_position = [50.0, 50.0]

‎antares-python/main.py‎

Lines changed: 43 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,46 @@
1-
def main():
2-
print("Hello from antares-python!")
1+
import asyncio
2+
3+
from antares import AntaresClient, CircleShip, LineShip, RandomShip, StationaryShip
4+
5+
6+
async def main() -> None:
7+
"""
8+
Example of how to use the Antares Python client to add ships and subscribe to events.
9+
This example demonstrates how to create different types of ships and add them to the Antares
10+
simulation. It also shows how to subscribe to simulation events and print the track information.
11+
"""
12+
13+
# Initialize the Antares client
14+
client = AntaresClient(
15+
host="localhost",
16+
http_port=9000,
17+
tcp_port=9001,
18+
timeout=5.0,
19+
auth_token="my_secret_auth_token",
20+
)
21+
22+
# Add ships
23+
ships = [
24+
StationaryShip(initial_position=(0.0, 0.0), type="stationary"),
25+
RandomShip(initial_position=(10.0, -10.0), max_speed=15.0, type="random"),
26+
CircleShip(initial_position=(-30.0, 20.0), radius=25.0, speed=3.0, type="circle"),
27+
LineShip(initial_position=(5.0, 5.0), angle=0.78, speed=4.0, type="line"),
28+
]
29+
30+
for ship in ships:
31+
client.add_ship(ship)
32+
print(f"✅ Added {ship.type} ship at {ship.initial_position}")
33+
34+
print("📡 Subscribing to simulation events...\n")
35+
36+
try:
37+
async for track in client.subscribe():
38+
print(
39+
f"📍 Track #{track.id} - {track.name} @ ({track.lat}, {track.long}) → {track.speed} knots" # noqa: E501
40+
)
41+
except KeyboardInterrupt:
42+
print("\n🛑 Subscription interrupted by user.")
343

444

545
if __name__ == "__main__":
6-
main()
46+
asyncio.run(main())

‎antares-python/pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "antares-python"
3-
version = "0.1.1"
3+
version = "0.1.2"
44
description = "Python interface for the Antares simulation software"
55
authors = [
66
{ name = "Juan Sebastian Urrea-Lopez", email = "[email protected]" },

‎antares-python/src/antares/__init__.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
from .client import AntaresClient
2-
from .models.ship import ShipConfig
2+
from .models.ship import CircleShip, LineShip, RandomShip, StationaryShip
33

4-
__all__ = ["AntaresClient", "ShipConfig"]
4+
__all__ = ["AntaresClient", "LineShip", "RandomShip", "StationaryShip", "CircleShip"]

0 commit comments

Comments
 (0)