Metadata-Version: 2.4
Name: robot-python
Version: 1.0
Summary: Керування роботом на карті: навчальна бібліотека з графічним інтерфейсом на Tkinter
Author: robot-python contributors
License: MIT
Keywords: robot,education,tkinter,visual-programming,energon
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Games/Entertainment :: Simulation
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=9.0
Provides-Extra: build
Requires-Dist: build>=1.0; extra == "build"
Requires-Dist: twine>=4.0; extra == "build"
Dynamic: license-file

# robot-python

Навчальна Python-бібліотека для керування роботом на клітинковій карті.
Містить готові карти, скіни, Energon, фарбування та графічне вікно на
Tkinter із кнопками «Виконати», «Крок», «Стоп» і «Скинути».

- **Назва пакета на PyPI:** `robot-python`
- **Модуль для імпорту:** `robot`
- **Версія:** 1.0
- **Залежність:** `Pillow` (Tkinter входить до стандартної бібліотеки Python)

## Встановлення

```bash
pip install robot-python
```

На Linux Tkinter може бути окремим системним пакетом:

```bash
sudo apt install python3-tk        # Debian / Ubuntu / Linux Mint
sudo dnf install python3-tkinter   # Fedora
```

## Швидкий старт

Створіть файл `example.py`:

```python
from robot import *

forward(2)
right()
forward(8)
right()
forward()
pickUp()
```

Запустіть його:

```bash
python example.py
```

Відкриється вікно з картою. Робот почне виконувати програму після натискання
кнопки **▶ Виконати**. Кнопка **Крок** виконує програму по одній команді,
**Стоп** зупиняє виконання, **Скинути** повертає робота на старт.

Можна також імпортувати модуль без `*`:

```python
import robot

if robot.frontIsClear():
    robot.forward()

print(robot.position())
print(robot.direction())
```

## Основні команди

### Рух

| Команда | Дія |
| --- | --- |
| `forward(steps=1)` | їхати вперед |
| `backward(steps=1)` | їхати назад |
| `left()` / `right()` | повернутися на 90° |
| `north(steps=1)`, `south(...)`, `east(...)`, `west(...)` | повернутися в напрямку й їхати |

Якщо попереду перешкода, виникає `CollisionError`; якщо робот виходить за межі
карти — `OutOfBoundsError`.

### Фарбування та Energon

```python
paintWhite()
forward(4)
stopPainting()

if frontIsEnergon():
    pickUp()

print(collected(), EnergonLeft(), EnergonTotal())
```

### Огляд

`frontIsObstacle()`, `frontIsClear()`, `frontIsEnergon()`, `frontIsWhite()`,
`frontIsBlack()` — те саме для `left...` і `right...`.

### Стан і налаштування

```python
print(position())     # (x, y)
print(direction())    # "north" / "east" / "south" / "west"
setSpeed(8)           # 0 — повільно, 10 — швидко
print(getSpeed())
print(isPainted(2, 3))
skin("grass")         # grass, desert, mind, lego, default
```

### Карти

```python
load_map("my_map.map")        # власна карта
load_map_text(map_text)       # карта з рядка
world = get_world()           # об'єкт World
done()                        # запустити головний цикл вікна
```

Формат карти — текст із секцією `map:`:

```text
map:
CHHHHHHHHHHHHHHD
G              I
G      @       I
G              I
BFFFFFFFFFFFFFFE
```

`@` — старт робота, `*` — Energon, великі латинські літери `A`–`Z` —
перешкоди, пробіл — вільна клітинка. Необов'язкові секції: `direction:`,
`paint:` та `extra:`.

## Скіни та ресурси

У пакет входять 27 вбудованих карт (`robot/maps`), скіни `default`, `grass`,
`desert`, `mind`, `lego` (`robot/skins`) та іконки інтерфейсу (`robot/icons`).
Усі ресурси встановлюються разом із бібліотекою.

## Автоматичний запуск вікна

Під час `from robot import *` бібліотека читає файл головного скрипта,
відкриває вікно й чекає на кнопку «Виконати». Це зручно для навчальних
програм, але небажано для тестів та інструментів. Вимкнення:

```bash
ROBOT_NO_AUTO_MAINLOOP=1 python script.py
```

Також автоматичний запуск вимикається, якщо в процесі вже імпортовано
`pytest` або `doctest`.

## Збірка та публікація на PyPI

```bash
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
python -m twine upload dist/*
```

Для тестового сховища TestPyPI:

```bash
python -m twine upload --repository testpypi dist/*
```

Готові файли з'являться в `dist/`.

## Ліцензія

MIT. Деталі — у файлі [LICENSE](LICENSE).
