Metadata-Version: 2.4
Name: neoomir-pypole
Version: 1.0.0
Summary: Official Python API client for Pole / NeoMir educational IDE
Author: NeoMir Team
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Dynamic: requires-python

# PyPole

**PyPole** is the official Python API binding and client library for the **Pole** (NeoMir) educational IDE.

It allows students and developers to write Python algorithms in their favorite IDEs (**PyCharm**, **VS Code**, **Jupyter**, or system terminal) and control the performers (**Robot** and **Turtle**) running in the Pole graphical window in real time, with instant diagnostic state streaming straight into your IDE run console.

---

## Key Features

- **Real-Time Visual Execution:** Commands execute in the Pole canvas with smooth animation, step tracking, and visual feedback.
- **Instant IDE Console Output:** Calling performer methods automatically logs formatted status updates, coordinates, and sensor metrics directly to your PyCharm / terminal console (`verbose=True` by default).
- **Full Bilingual Support:** Supports both standard English API names and Russian algorithmic keywords matching the KuMir educational syllabus:
  - `robot.right()` and `робот.вправо()`
  - `turtle.forward(100)` and `черепаха.вперёд(100)`
- **Zero Configuration:** Automatically locates and establishes Unix Domain Socket or Windows Named Pipe connections to the active Pole instance.
- **Built-in Safety & Diagnostics:** Raises structured exceptions such as `RobotCrashError` when colliding with walls, with exact coordinates of the collision.

---

## Installation

### From PyPI
```bash
pip install pypole
```

### From Local Source (Development Mode)

If you are inside the `python/` directory:
```bash
pip install -e .
```

If you are at the project root directory:
```bash
pip install -e ./python
```

> [!TIP]
> In managed environments (or without a virtual environment), use `pip install --user -e .` without `sudo`.

---

## Quick Start in PyCharm / VS Code

### 1. Controlling the Robot (English Syntax)

```python
from pypole import robot

# Reset field to starting position
robot.reset()

# Move along corridor and paint cells
while robot.free_right():
    robot.right()
    robot.paint()

# Check wall sensors
if robot.wall_up():
    print("Wall detected above the robot!")
```

### 2. Controlling the Robot (Russian Syntax / KuMir Style)

```python
from pypole import робот

робот.сброс()

while робот.справа_свободно():
    робот.вправо()
    робот.закрасить()

if робот.сверху_стена():
    print("Обнаружена стена сверху!")
```

### 3. Controlling the Turtle (Vector Graphics)

```python
from pypole import turtle

turtle.home()
turtle.clear()
turtle.pen_down()

# Draw an equilateral triangle
for _ in range(3):
    turtle.forward(100)
    turtle.left(120)

print(f"Current turtle position: {turtle.get_state()}")
```

---

## Real-Time Console Output in PyCharm

When running commands from PyCharm, each step prints detailed diagnostic information directly to the Run Tool Window:

```text
[Pole Robot] RESET      -> [Робот] Позиция: (1, 1) | Закрашено: Нет | Стены: ↑← | Статус: ОК
[Pole Robot] ВПРАВО     -> [Робот] Позиция: (2, 1) | Закрашено: Нет | Стены: ↑  | Статус: ОК
[Pole Robot] ЗАКРАСИТЬ  -> [Робот] Позиция: (2, 1) | Закрашено: Да  | Стены: ↑  | Статус: ОК
[Pole Turtle] ВПЕРЁД(100) -> [Черепаха] Позиция: (100.0, 0.0) | Угол: 90° | Перо: рисует
```

To mute automatic console printing, pass `verbose=False` or call `set_verbose(False)`:
```python
from pypole import robot, set_verbose

set_verbose(False)
robot.right(5)  # Executes silently in Pole without printing to IDE console
```

---

## API Reference

### Robot Performer (`pypole.Robot`)

| Method (EN) | Method (RU) | Description |
| :--- | :--- | :--- |
| `robot.up(n=1)` | `робот.вверх(n=1)` | Move up by *n* cells |
| `robot.down(n=1)` | `робот.вниз(n=1)` | Move down by *n* cells |
| `robot.left(n=1)` | `робот.влево(n=1)` | Move left by *n* cells |
| `robot.right(n=1)` | `робот.вправо(n=1)` | Move right by *n* cells |
| `robot.paint()` | `робот.закрасить()` | Paint current cell |
| `robot.reset()` | `робот.сброс()` | Reset performer to starting point |
| `robot.step_back()` | `робот.шаг_назад()` | Undo last action |
| `robot.get_state()` | `робот.состояние()` | Returns `RobotState` object |
| `robot.wall_up()` | `робот.стена_сверху()` | `True` if obstacle above |
| `robot.wall_down()` | `робот.стена_снизу()` | `True` if obstacle below |
| `robot.wall_left()` | `робот.стена_слева()` | `True` if obstacle to the left |
| `robot.wall_right()` | `робот.стена_справа()` | `True` if obstacle to the right |
| `robot.free_up()` | `робот.сверху_свободно()` | `True` if upward direction is open |
| `robot.free_down()` | `робот.снизу_свободно()` | `True` if downward direction is open |
| `robot.free_left()` | `робот.слева_свободно()` | `True` if left direction is open |
| `robot.free_right()` | `робот.справа_свободно()` | `True` if right direction is open |
| `robot.is_painted()` | `робот.клетка_закрашена()` | `True` if current cell is painted |
| `robot.is_clean()` | `робот.клетка_чистая()` | `True` if current cell is clean |

### Turtle Performer (`pypole.Turtle`)

| Method (EN) | Method (RU) | Description |
| :--- | :--- | :--- |
| `turtle.forward(d=50)` | `черепаха.вперёд(d=50)` | Move forward along heading |
| `turtle.backward(d=50)` | `черепаха.назад(d=50)` | Move backward |
| `turtle.left(a=90)` | `черепаха.влево(a=90)` | Turn counter-clockwise by *a* degrees |
| `turtle.right(a=90)` | `черепаха.вправо(a=90)` | Turn clockwise by *a* degrees |
| `turtle.pen_down()` | `черепаха.опустить_хвост()` | Lower pen (draw path) |
| `turtle.pen_up()` | `черепаха.поднять_хвост()` | Raise pen (move without drawing) |
| `turtle.home()` | `черепаха.домой()` | Return to center (0, 0) |
| `turtle.clear()` | `черепаха.очистить()` | Clear canvas drawings |
| `turtle.step_back()` | `черепаха.шаг_назад()` | Undo last turtle step |

---

## Exception Handling

```python
from pypole import robot, RobotCrashError, PoleConnectionError

try:
    robot.up(10)
except PoleConnectionError as e:
    print(f"Pole application is not running: {e}")
except RobotCrashError as e:
    print(f"Robot crashed into wall at ({e.x}, {e.y})!")
```

---

## License

MIT License. Part of the **Pole (NeoMir)** educational platform.
