Установка и запуск
Установка и запуск
English · Руководство · Справочник
Содержание
Проект переносимый: он не устанавливается в систему, не пишет в реестр и целиком живёт в своей папке. Скопировать папку на другую машину — достаточная «установка».
Требования
Windows. Программа рассчитана на Windows: перенос колонок по адресу работает через Excel, а окно поднимается на системном движке Edge WebView2.
Excel. Нужен только команде «Перенести колонки по адресу»: именно через него сохраняются формулы, оформление и порядок строк основной книги. Остальные команды без Excel работают.
Интернет. Нужен один раз для сборки окружения и потом изредка — для скачивания реестра ОКТМО.
Собранный portable-проект ничего больше не требует: Python лежит внутри, в папке runtime.
Запуск
| Способ | Что делает |
|---|---|
Start.exe | Открыть окно программы |
launcher_gui.cmd | То же самое |
launcher_project_ru.cmd | Меню проекта на русском: прогоны, настройки, сборка |
launcher_project.cmd | То же меню на английском |
launcher_tools.cmd | Служебное меню: проверка окружения, лицензии, релиз |
builder_main.cmd | Сборка portable-окружения |
Launcher окна ищет Python в этом порядке:
runtime\pythonw.exeruntime\python.exeruntime\python\pythonw.exeruntime\python\python.exe- системный
py -3.12
Найденный интерпретатор поднимает локальный сервер на 127.0.0.1:8080 и открывает окно на движке Edge WebView2. Идентификатор процесса окна пишется в logs/gui_server.pid.
Если окно не открылось
Задайте AUDION_GUI_CONSOLE=1 и запустите launcher снова — он откроется в консоли, и сообщения об ошибках будут видны:
set AUDION_GUI_CONSOLE=1 && launcher_gui.cmdЧастые причины:
- Окружение не собрано. В
runtimeнетpython.exe— соберите окружение. - Порт 8080 занят. Окно поднимается на другом порту или не поднимается
вовсе; освободите порт.
- Нет WebView2. Компонент входит в состав современной Windows; на старых
сборках его ставят отдельно. Как обходной путь окно открывается в браузере.
Сборка окружения
Нужна только если вы получили проект без папки runtime или пересобираете его.
builder_main.cmd — меню сборки:
| Пункт | Что делает |
|---|---|
[01] PYTHON ENV CMD | Собрать portable-окружение (основной путь) |
[02] PYTHON ENV PS | То же через PowerShell |
[03] FZF | Установить или обновить system_core\fzf.exe для меню launcher-ов |
[09] PORTABLE OFFLINE | Установка из локального wheelhouse без сети |
[70] CLEAN INSTALL CACHE | Очистить кэш сборки; собранный runtime остаётся |
[71] VERIFY / DOCTOR | Проверить окружение и импорты |
[77] MAKE RELEASE ARCHIVE | Собрать релизный архив |
Установка без интернета
Если в проекте есть папка wheelhouse с колёсами зависимостей, окружение собирается из неё: install\install_portable_offline.cmd или пункт [09] PORTABLE OFFLINE.
Проверка
[71] VERIFY / DOCTOR — или install\verify_portable_env.cmd — проверяет интерпретатор и импорт всех зависимостей. Это первое, что стоит запустить, если что-то не работает.
Зависимости
| Пакет | Зачем |
|---|---|
pandas | Табличные операции |
openpyxl | Чтение и запись XLSX |
rapidfuzz | Приблизительное сравнение названий улиц |
pymorphy3, pymorphy3-dicts-ru | Падежные формы названий населённых пунктов |
PyMuPDF | Текстовый слой PDF |
pywin32 | Работа с Excel при переносе колонок |
nicegui, pywebview | Окно программы |
pyyaml | Файлы настроек |
tqdm, rich | Прогресс и вывод в журнал |
pytest, beautifulsoup4 | Тесты |
Тексты лицензий всех сторонних компонентов лежат в licenses/.
Папки проекта
| Папка | Что в ней | Можно чистить |
|---|---|---|
system_core | Исходный код | Нет |
config | Настройки, ключи и пины ОКТМО | Нет |
data | Реестр ОКТМО и справочник регионов | Реестр скачивается заново |
runtime | Portable Python | Пересобирается |
wheelhouse | Колёса для офлайн-установки | Да |
input | Исходные файлы | Да |
output | Результаты | Да |
report | Отчёты прогонов | Да |
logs | Журналы | Да |
workspace | Промежуточные файлы | Да |
release | Архивы результатов | Да |
docs | Документация | Нет |
licenses | Лицензии сторонних компонентов | Нет |
tests | Тесты | Нет |
Первичное создание рабочих папок — install\init_folders.cmd.
Обслуживание
Очистка проекта. cleanup_project.cmd удаляет наработанные артефакты: кэши, временные конвертации, журналы, отчёты и пересобираемый runtime. Код, настройки, документация, исходники, результаты и утверждённые эталоны сохраняются.
Кодировка CMD-файлов. После правки любого .cmd запускайте install\Check-CmdEncoding.cmd: файлы должны остаться UTF-8 без BOM с переносами CRLF. Иначе кириллица в меню превратится в мусор.
Обновление зависимостей. install\Update-Requirements-Lock.cmd перегенерирует lock-файл.
Реестр ОКТМО обновляется не отсюда, а кнопкой в окне — см. ОКТМО.
Перед большим прогоном
Проверьте окружение (VERIFY / DOCTOR), работайте с копиями важных таблиц и держите источники, эталон и результаты в разных папках.
Первый прогон на новом наборе данных делайте на десятке строк, ответ для которых известен заранее.