Skip to content

Commit abc54a0

Browse files
gon7187gon7187
authored
Initial public release: Python Path
Публичный релиз русскоязычной платформы для изучения Python.
1 parent 32606ad commit abc54a0

26 files changed

Lines changed: 4492 additions & 0 deletions

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
name: Сообщить об ошибке
3+
about: Помогите сделать Python Path надёжнее
4+
title: "bug: "
5+
labels: bug
6+
---
7+
8+
## Что произошло
9+
10+
<!-- Опишите фактическое поведение. -->
11+
12+
## Как повторить
13+
14+
1.
15+
2.
16+
3.
17+
18+
## Что ожидалось
19+
20+
<!-- Каким должен быть результат? -->
21+
22+
## Окружение
23+
24+
- ОС:
25+
- Python:
26+
- Браузер:

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
name: Предложить улучшение
3+
about: Новая тема, упражнение или функция приложения
4+
title: "feat: "
5+
labels: enhancement
6+
---
7+
8+
## Идея
9+
10+
<!-- Какую проблему решит улучшение? -->
11+
12+
## Предлагаемое решение
13+
14+
<!-- Как это должно работать? -->
15+
16+
## Альтернативы
17+
18+
<!-- Какие другие варианты рассматривались? -->

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
## Что изменилось
2+
3+
<!-- Коротко опишите пользовательский эффект. -->
4+
5+
## Почему
6+
7+
<!-- Какую проблему или возможность закрывает PR? -->
8+
9+
## Проверка
10+
11+
- [ ] `uv run ruff check app tests`
12+
- [ ] `uv run ruff format --check app tests`
13+
- [ ] `uv run pyright app tests`
14+
- [ ] `uv run pytest -q`
15+
16+
## Скриншоты / заметки
17+
18+
<!-- Добавьте скриншоты для изменений интерфейса. -->

‎.github/dependabot.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: github-actions
4+
directory: /
5+
schedule:
6+
interval: monthly
7+
- package-ecosystem: pip
8+
directory: /
9+
schedule:
10+
interval: monthly

‎.github/workflows/ci.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
permissions:
8+
contents: read
9+
10+
jobs:
11+
quality:
12+
name: Quality checks
13+
runs-on: ubuntu-latest
14+
steps:
15+
- name: Check out repository
16+
uses: actions/checkout@v4
17+
18+
- name: Set up Python
19+
uses: actions/setup-python@v5
20+
with:
21+
python-version: "3.12"
22+
23+
- name: Install uv
24+
uses: astral-sh/setup-uv@v5
25+
with:
26+
enable-cache: true
27+
28+
- name: Install dependencies
29+
run: uv sync --extra dev --locked
30+
31+
- name: Lint
32+
run: uv run ruff check app tests
33+
34+
- name: Check formatting
35+
run: uv run ruff format --check app tests
36+
37+
- name: Type check
38+
run: uv run pyright app tests
39+
40+
- name: Test
41+
run: uv run pytest -q

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.venv/
2+
__pycache__/
3+
.pytest_cache/
4+
.ruff_cache/
5+
python_path.db
6+
*.pyc

‎CONTRIBUTING.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Вклад в Python Path
2+
3+
Проект пока ориентирован на одного пользователя, но улучшения приветствуются после выбора лицензии.
4+
5+
## Локальная разработка
6+
7+
```powershell
8+
uv sync --extra dev
9+
uv run uvicorn app.main:app --reload
10+
```
11+
12+
## Перед pull request
13+
14+
```powershell
15+
uv run ruff check app tests
16+
uv run ruff format --check app tests
17+
uv run pyright app tests
18+
uv run pytest -q
19+
```
20+
21+
## Правила для контента
22+
23+
- Один урок вводит один основной концепт и опирается на предыдущие.
24+
- У каждого урока три теоретические карточки и три упражнения: выбор, короткий ответ, код.
25+
- Кодовые задания должны быть короткими, детерминированными и совместимыми с учебным раннером.
26+
- Не добавляйте большие заимствованные фрагменты чужих курсов. Пересказывайте идеи своими словами и ссылайтесь на первоисточник в PR.
27+
28+
## Коммиты и PR
29+
30+
- Делайте маленькие коммиты с действием в настоящем времени: `Добавить уроки по JSON`.
31+
- В PR укажите пользовательский эффект, затронутые части программы и результаты проверок.
32+
- Не включайте `python_path.db`, `.venv` и иные локальные артефакты.

‎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) 2026 gon7187
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.

‎README.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Python Path
2+
3+
[![CI](https://github.com/gon7187/python-path/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/gon7187/python-path/actions/workflows/ci.yml)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
5+
6+
> Русскоязычный тренажёр Python в духе Duolingo: короткая теория, проверяемая практика и плавный путь от первого `print()` до собственных проектов.
7+
8+
## Зачем этот проект
9+
10+
Python Path делает обучение практичным и последовательным. Ученик проходит материал маленькими шагами, получает мгновенную обратную связь по ответам и коду, возвращается к ошибочным заданиям и видит свой прогресс в XP, звёздах и серии занятий.
11+
12+
| | Сейчас в курсе |
13+
| --- | --- |
14+
| 📚 Программа | **31 раздел · 120 уроков · 360 заданий** |
15+
| 🧠 Практика | Выбор ответа, короткий ввод и исполняемый Python-код |
16+
| 🏆 Мотивация | XP, звёзды, стрик, достижения, повторение ошибок |
17+
| 📱 Интерфейс | Адаптивный, без фронтенд-сборки |
18+
| ⚙️ Технологии | FastAPI · SQLite · vanilla JavaScript · uv |
19+
20+
## Быстрый старт
21+
22+
Требуются Python 3.11+ и [uv](https://docs.astral.sh/uv/).
23+
24+
```powershell
25+
git clone https://github.com/gon7187/python-path.git
26+
cd python-path
27+
uv sync --extra dev
28+
uv run uvicorn app.main:app --reload
29+
```
30+
31+
Откройте [http://127.0.0.1:8000](http://127.0.0.1:8000). Прогресс сохраняется локально в `python_path.db`, который исключён из Git.
32+
33+
Чтобы открыть приложение с телефона в той же Wi-Fi-сети, запустите сервер так:
34+
35+
```powershell
36+
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000
37+
```
38+
39+
## Программа курса
40+
41+
Курс следует от базового синтаксиса к реальным инструментам разработки:
42+
43+
1. Первые программы, типы, условия, циклы, функции и коллекции.
44+
2. Строки, модули, файлы, JSON/CSV, исключения и ООП.
45+
3. Типы, стандартная библиотека, регулярные выражения, тесты и Git.
46+
4. CLI, окружения, HTTP/API, SQL, параллельность и async.
47+
5. Четыре выпускных мини-проекта: задачи, заметки, API-клиент и релиз приложения.
48+
49+
Полная последовательность из 31 раздела — в [карте курса](docs/CURRICULUM.md).
50+
51+
## Возможности
52+
53+
- Каждый урок содержит три карточки теории и три задания.
54+
- Следующий урок открывается после успешного прохождения предыдущего.
55+
- После каждого раздела открывается контрольная точка; для зачёта требуется 70% правильных ответов.
56+
- Режим практики отдаёт сначала задания, в которых ученик ошибался.
57+
- Код проверяется в изолированном Python-процессе с AST-фильтром и двухсекундным лимитом.
58+
- Один пользователь, локальный SQLite: можно заниматься без регистрации и облака.
59+
60+
## Разработка и проверки
61+
62+
```powershell
63+
uv run ruff check app tests
64+
uv run ruff format --check app tests
65+
uv run pyright app tests
66+
uv run pytest -q
67+
```
68+
69+
В репозитории есть GitHub Actions, которые выполняют эти проверки на каждом push и pull request.
70+
71+
## Структура
72+
73+
```text
74+
app/
75+
main.py # FastAPI-приложение и JSON API
76+
content.py # базовые уроки и объединение программы
77+
extended_curriculum.py # 108 уроков расширенной части
78+
evaluator.py # проверка ответов и учебного кода
79+
db.py # SQLite-прогресс
80+
static/ # адаптивный интерфейс
81+
tests/ # unit- и API-тесты
82+
docs/ # карта курса и архитектурные решения
83+
```
84+
85+
Подробнее о границах компонентов — в [архитектуре](docs/ARCHITECTURE.md). Как развивать проект — в [CONTRIBUTING.md](CONTRIBUTING.md).
86+
87+
## Безопасность учебного раннера
88+
89+
Встроенный редактор рассчитан на короткие учебные задачи: запрещены импорты и системные операции, решение запускается отдельным процессом и останавливается по таймауту. Это удобная защита для локального тренажёра, но **не** полноценный sandbox для публичного многоарендного сервиса. Перед публикацией в интернете нужен отдельный контейнерный раннер с лимитами CPU, памяти и сети. Детали — в [SECURITY.md](SECURITY.md).
90+
91+
## Лицензия
92+
93+
Распространяется по лицензии [MIT](LICENSE): проектом можно пользоваться, изменять его и распространять с сохранением текста лицензии.

‎SECURITY.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Security policy
2+
3+
## Учебный раннер
4+
5+
Python Path выполняет только короткий код для учебных задач. Перед запуском код проверяется по AST, выполняется отдельным Python-процессом с ограниченным набором встроенных функций и завершается по таймауту.
6+
7+
Это снижает риск для локального тренажёра, но не заменяет инфраструктурную изоляцию. Не размещайте текущую версию как публичный сервис, в котором чужие пользователи могут исполнять произвольный код.
8+
9+
Для публичного режима потребуются как минимум:
10+
11+
- отдельные контейнеры или microVM на каждое выполнение;
12+
- лимиты CPU, памяти, файловой системы, сети и числа процессов;
13+
- очереди заданий, rate limiting и аудит;
14+
- отдельное хранилище с аутентификацией пользователей.
15+
16+
## Сообщить о проблеме
17+
18+
Не публикуйте детали потенциальной уязвимости в Issue. Создайте приватное security advisory в GitHub или свяжитесь с владельцем репозитория напрямую.

0 commit comments

Comments
 (0)