Skip to content

Commit 6adf0ce

Browse files
jsurreajsurrea
authored
Create Antares-Python project (#2)
Summary: - Renamed the naval radar simulator to antares - Created complete antares-python project: - Complete functionality - CLI - 100% coverage - Released in PyPI Details: * rename rust project to antares * scaffold the antares-python project with dev tools * fix ci issues * fix pip install in ci * add pytest-cov to ci * remove precommit config * Implement API calls and CLI * Improve CLI logging * improve tests coverage * reach 100% coverage * add tests for track model * update readme and bump version * update cli config and include start command * add support for ship types * add tests for different types of ships * update docs * add badges
1 parent 4e41f5c commit 6adf0ce

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

71 files changed

+1827
-0
lines changed

‎.github/workflows/python-ci.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: Antares Python CI
2+
3+
on:
4+
push:
5+
paths:
6+
- 'antares-python/**'
7+
pull_request:
8+
paths:
9+
- 'antares-python/**'
10+
11+
jobs:
12+
test:
13+
name: Run Tests, Lint, Type-check
14+
runs-on: ubuntu-latest
15+
16+
defaults:
17+
run:
18+
working-directory: antares-python
19+
20+
steps:
21+
- uses: actions/checkout@v4
22+
23+
- name: Set up Python
24+
uses: actions/setup-python@v5
25+
with:
26+
python-version: '3.13'
27+
28+
- name: Install uv
29+
run: |
30+
curl -Ls https://astral.sh/uv/install.sh | bash
31+
echo "$HOME/.cargo/bin" >> $GITHUB_PATH
32+
33+
- name: Install dependencies
34+
run: |
35+
uv pip install --system -e .
36+
uv pip install --system pytest pytest-cov pytest-mock mypy ruff build
37+
38+
39+
- name: Run linters
40+
run: python -m ruff check .
41+
42+
- name: Run formatters
43+
run: python -m ruff format --check .
44+
45+
- name: Run mypy
46+
run: mypy src/
47+
48+
- name: Run tests with coverage
49+
run: pytest --cov=src --cov-report=term-missing --cov-fail-under=80

‎.github/workflows/python-publish.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Publish antares-python to PyPI
2+
3+
on:
4+
push:
5+
tags:
6+
- "v*.*.*"
7+
8+
jobs:
9+
publish:
10+
name: Build and Publish
11+
runs-on: ubuntu-latest
12+
13+
defaults:
14+
run:
15+
working-directory: antares-python
16+
17+
steps:
18+
- name: Checkout repo
19+
uses: actions/checkout@v4
20+
21+
- name: Set up Python
22+
uses: actions/setup-python@v5
23+
with:
24+
python-version: "3.13"
25+
26+
- name: Install uv
27+
run: |
28+
curl -Ls https://astral.sh/uv/install.sh | bash
29+
echo "$HOME/.cargo/bin" >> $GITHUB_PATH
30+
31+
- name: Build package
32+
run: |
33+
uv venv
34+
source .venv/bin/activate
35+
uv pip install -U build
36+
python -m build
37+
38+
- name: Publish to PyPI
39+
uses: pypa/gh-action-pypi-publish@release/v1
40+
with:
41+
password: ${{ secrets.PYPI_API_TOKEN }}
42+
packages-dir: antares-python/dist/

‎antares-python/.gitignore‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
__pycache__/
2+
*.pyc
3+
.venv/
4+
dist/
5+
build/
6+
*.egg-info/
7+
.coverage
8+
.coverage.*
9+
htmlcov/
10+
antares.log

‎antares-python/.python-version‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
3.13

‎antares-python/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 The Software Design Lab
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎antares-python/README.md‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
# Antares Python Client
2+
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+
[![License](https://img.shields.io/github/license/TheSoftwareDesignLab/ANTARES)](LICENSE)
7+
8+
> ✨ A modern Python interface for the Antares simulation engine ✨
9+
10+
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.
11+
12+
- Provides a high-level Python API to control the simulation
13+
- Automatically maps Python objects to Antares-native requests
14+
- Supports configuration via `.env` and `.toml` files
15+
- Offers a CLI for scripting and manual control
16+
- Built with Pydantic 2, Typer, and fully type-annotated
17+
18+
Inspired by tools like PySpark, this library acts as a thin but powerful façade over the Antares backend.
19+
20+
---
21+
22+
## 🌟 Features
23+
24+
- Add ships with complex motion patterns to the simulation
25+
- Subscribe to live simulation events over TCP
26+
- Launch the Antares binary locally with config
27+
- Configure everything via `.env` or `.toml`
28+
- Clean CLI with rich output and JSON support
29+
30+
---
31+
32+
## 🚀 Installation
33+
34+
### Requirements
35+
36+
- Python >= 3.13 (tested with 3.13)
37+
- `uv` for isolated dev environments
38+
39+
### Install from PyPI
40+
41+
```bash
42+
pip install antares-python
43+
```
44+
45+
### Install in editable mode (for development)
46+
47+
```bash
48+
git clone https://github.com/TheSoftwareDesignLab/ANTARES.git
49+
cd ANTARES/antares-python
50+
uv venv
51+
source .venv/bin/activate
52+
uv pip install -e .
53+
```
54+
55+
---
56+
57+
## 🚧 CLI Usage (`antares-cli`)
58+
59+
After installing, the CLI tool `antares-cli` becomes available.
60+
61+
### Available Commands
62+
63+
| Command | Description |
64+
|---------------|--------------------------------------------------|
65+
| `add-ship` | Add a ship with specific motion type |
66+
| `reset` | Reset the simulation |
67+
| `subscribe` | Subscribe to simulation event stream |
68+
| `start` | Start the Antares binary with optional config |
69+
70+
### Common Options
71+
72+
| Option | Description |
73+
|---------------|-------------------------------------------------|
74+
| `--config` | Path to `.toml` config file |
75+
| `--verbose` | Enable detailed output |
76+
| `--json` | Output results in JSON format |
77+
78+
Example:
79+
80+
```bash
81+
antares-cli add-ship --type line --x 0 --y 0 --angle 0.5 --speed 5.0
82+
```
83+
84+
---
85+
86+
## 📚 Python Usage Example
87+
88+
```python
89+
import asyncio
90+
from antares.client import AntaresClient
91+
from antares.models.ship import LineShip, CircleShip, RandomShip, StationaryShip
92+
from antares.models.track import Track
93+
94+
95+
async def main():
96+
# Create the Antares client using environment config or .env file
97+
client = AntaresClient()
98+
99+
# Define ships of each supported type
100+
ships = [
101+
StationaryShip(initial_position=(0.0, 0.0), type="stationary"),
102+
RandomShip(initial_position=(10.0, -10.0), max_speed=15.0, type="random"),
103+
CircleShip(initial_position=(-30.0, 20.0), radius=25.0, speed=3.0, type="circle"),
104+
LineShip(initial_position=(5.0, 5.0), angle=0.78, speed=4.0, type="line"),
105+
]
106+
107+
# Add each ship to the simulation
108+
for ship in ships:
109+
client.add_ship(ship)
110+
print(f"✅ Added {ship.type} ship at {ship.initial_position}")
111+
112+
print("\n📡 Subscribing to simulation events...\n")
113+
114+
# Listen to simulation events (TCP stream)
115+
async for event in client.subscribe():
116+
if isinstance(event, Track):
117+
print(
118+
f"📍 Track #{event.id} - {event.name} at ({event.lat}, {event.long}) → {event.speed} knots"
119+
)
120+
121+
122+
if __name__ == "__main__":
123+
# Run the main async function
124+
asyncio.run(main())
125+
```
126+
127+
---
128+
129+
## 🧭 Ship Types
130+
131+
Ships are classified based on their motion pattern. The `type` field determines which parameters are required. Here's a summary:
132+
133+
| Type | Required Fields | Description |
134+
|-------------|---------------------------------------------|---------------------------------------------|
135+
| `stationary`| `initial_position` | Does not move at all |
136+
| `random` | `initial_position`, `max_speed` | Moves randomly, up to a max speed |
137+
| `circle` | `initial_position`, `radius`, `speed` | Moves in a circular pattern |
138+
| `line` | `initial_position`, `angle`, `speed` | Moves in a straight line |
139+
140+
Each ship type corresponds to a specific Pydantic model:
141+
142+
- `StationaryShip`
143+
- `RandomShip`
144+
- `CircleShip`
145+
- `LineShip`
146+
147+
You can also use the generic `ShipConfig` union to parse from dynamic input like TOML or JSON.
148+
149+
---
150+
151+
## ⚙️ Configuration
152+
153+
The client supports two configuration methods:
154+
155+
### `.env` File
156+
157+
The `.env` file allows you to define environment variables:
158+
159+
```dotenv
160+
ANTARES_HOST=localhost
161+
ANTARES_HTTP_PORT=9000
162+
ANTARES_TCP_PORT=9001
163+
ANTARES_TIMEOUT=5.0
164+
ANTARES_AUTH_TOKEN=
165+
```
166+
167+
➡️ See `template.env` for a complete example.
168+
169+
### `.toml` Config File
170+
171+
To configure the client and ships via a TOML file:
172+
173+
```toml
174+
[antares]
175+
host = "localhost"
176+
http_port = 9000
177+
tcp_port = 9001
178+
timeout = 5.0
179+
auth_token = ""
180+
181+
[[antares.ships.stationary]]
182+
initial_position = [50.0, 50.0]
183+
184+
[[antares.ships.random]]
185+
initial_position = [-20.0, 20.0]
186+
max_speed = 10.0
187+
188+
[[antares.ships.circle]]
189+
initial_position = [30.0, -30.0]
190+
radius = 20.0
191+
speed = 4.0
192+
193+
[[antares.ships.line]]
194+
initial_position = [0.0, 0.0]
195+
angle = 0.785
196+
speed = 5.0
197+
```
198+
199+
➡️ See `config.example.toml` for a full working example.
200+
201+
You can pass the config to any CLI command with:
202+
203+
```bash
204+
antares-cli add-ship --config path/to/config.toml
205+
```
206+
207+
Or use it in Python with:
208+
209+
```python
210+
from antares.config_loader import load_config
211+
settings = load_config("config.toml")
212+
```
213+
214+
---
215+
216+
## 🧪 Development & Testing
217+
218+
This project uses modern Python tooling for fast, isolated, and productive workflows.
219+
220+
### Setup
221+
222+
```bash
223+
uv venv
224+
source .venv/bin/activate
225+
uv pip install -e .[dev]
226+
```
227+
228+
### Available Tasks (via [`task`](https://taskfile.dev))
229+
230+
| Task | Description |
231+
|----------------|---------------------------------------------|
232+
| `task check` | Run linters (ruff, mypy) and formatter check |
233+
| `task test` | Run full test suite |
234+
| `task format` | Auto-format code with ruff + black |
235+
| `task build` | Build the wheel and source dist |
236+
| `task publish` | Publish to PyPI (requires version bump) |
237+
238+
### Run tests manually
239+
240+
```bash
241+
pytest
242+
```
243+
244+
### View test coverage
245+
246+
```bash
247+
pytest --cov=antares --cov-report=term-missing
248+
```
249+
250+
---
251+
252+
## 📄 License
253+
254+
This project is licensed under the MIT License. See the [LICENSE](../LICENSE) file for details.
255+
256+
---
257+
258+
## 🤝 Contributing
259+
260+
Contributions are welcome! To contribute:
261+
262+
1. Fork the repository
263+
2. Create a new branch (`git checkout -b feature/my-feature`)
264+
3. Make your changes
265+
4. Run `task check` and `task test` to ensure quality
266+
5. Submit a pull request 🚀
267+
268+
For significant changes, please open an issue first to discuss what you’d like to do.
269+
270+
Happy hacking! 🛠️

0 commit comments

Comments
 (0)