Настройка Python-проекта с build123d и uv

Здравствуйте! Добро пожаловать на наш курс по созданию параметрических 3D-моделей с помощью build123d. Наша цель — научиться проектировать и печатать полезные предметы, в частности, корпуса для ваших электронных устройств.

Сегодняшнее первое занятие закладывает фундамент для всей нашей дальнейшей работы. Мы сфокусируемся на создании чистого и воспроизводимого рабочего окружения для Python-проекта. Вы узнаете, как настроить проект с помощью uv — современного и очень быстрого менеджера зависимостей, который вы выбрали для этого курса. К концу этого урока у вас будет полностью настроенный проект, готовый к работе с build123d.

Зачем мы используем uv?

Поскольку вы имеете большой опыт в Python-разработке, вы знаете, насколько важен правильный менеджмент зависимостей и окружений. uv — это инструмент от создателей ruff, написанный на Rust, который стремится объединить и значительно ускорить работу, традиционно выполняемую связкой pip, venv, pip-tools и другими.

Для быстрого знакомства с основными идеями uv предлагаю посмотреть короткое видео.

Для более глубокого понимания, какие именно проблемы в экосистеме Python решает uv, вы можете прочитать следующий материал. Он хорошо объясняет мотивацию создания такого инструмента.

Шаг 1: Установка uv

Если uv у вас еще не установлен, это можно сделать одной командой. В вашей Linux-среде наиболее удобным способом будет использование curl.

Выполните в терминале:

curl -LsSf https://astral.sh/uv/install.sh | sh

После установки убедитесь, что uv доступен в вашей системе, проверив его версию:

uv --version

Вы должны увидеть что-то вроде uv 0.2.10.

Шаг 2: Создание и инициализация проекта

Теперь давайте создадим директорию для нашего проекта и инициализируем в ней uv.

1. Создайте папку для проекта и перейдите в нее:

   mkdir b3d-enclosures
   cd b3d-enclosures
   

2. Инициализируйте проект с помощью uv:

   uv init
   

Эта команда создаст несколько файлов, формирующих каркас проекта:

• pyproject.toml: Центральный конфигурационный файл проекта, соответствующий современным стандартам (PEP 621). Здесь будут перечислены зависимости, метаданные проекта и т.д.
• .gitignore: Стандартный файл для Git, исключающий из репозитория ненужные файлы, например, виртуальное окружение.
• README.md: Файл для описания проекта.
• hello.py и .python-version: Вспомогательные файлы, которые можно проигнорировать или удалить.

Шаг 3: Установка build123d

Теперь, когда у нас есть структура проекта, добавим нашу основную библиотеку — build123d.

Выполните команду:

uv add build123d

Обратите внимание на то, что произошло:

1. uv обнаружил, что виртуальное окружение еще не создано, и автоматически создал его в папке .venv.
2. build123d и все его зависимости были скачаны и установлены в это окружение. Вы наверняка заметите, насколько быстро это происходит.
3. Файл pyproject.toml был автоматически обновлен. Зависимость build123d теперь прописана в секции [project.dependencies].

Откройте pyproject.toml в Helix, чтобы увидеть изменения:

[project]
name = "b3d-enclosures"
version = "0.1.0"
description = "Add your description here"
authors = [
    { name = "<Your Name>", email = "<your@email.com>" },
]
dependencies = [
    "build123d>=0.9.3", # Ваша версия может отличаться
]
readme = "README.md"
requires-python = ">=3.9" # Ваша версия Python

# ... остальной файл

Этот подход обеспечивает декларативное и воспроизводимое управление зависимостями, что является ключевым для поддержания порядка в проекте.

Шаг 4: Проверка установки

Чтобы убедиться, что все настроено правильно, создадим минимальный скрипт, использующий build123d, и запустим его.

1. Создайте файл lesson1_box.py.

2. Добавьте в него следующий код:

   # lesson1_box.py
   from build123d import Box
   
   # Создаем простой параллелепипед размерами 10x20x30 мм
   my_box = Box(10, 20, 30)
   
   print("Скрипт выполнен успешно! Объект Box создан.")
   print(f"Тип объекта: {type(my_box)}")
   

3. Теперь запустим этот скрипт с помощью uv. Команда uv run автоматически активирует виртуальное окружение .venv для выполнения скрипта.

   uv run lesson1_box.py
   

Если вы видите в консоли сообщение Скрипт выполнен успешно!, значит, окружение настроено верно, build123d установлена, и Python может импортировать её модули.

Проверьте себя!

Предположим, для анализа геометрии или других вычислений в будущем вам может понадобиться библиотека numpy, но только на этапе разработки, а не как основная зависимость проекта.

Задание:

1. Добавьте numpy в проект как "dev" зависимость.
2. Убедитесь, что она появилась в pyproject.toml в отдельной секции.
3. Затем удалите numpy из проекта.

Показать решение

1. Добавление "dev" зависимости:
   Используйте флаг --dev, чтобы указать, что это зависимость для разработки.

   uv add numpy --dev
   

2. Проверка pyproject.toml:
   Откройте файл. Вы увидите новую секцию [tool.uv.dev-dependencies], содержащую numpy.

   # ...
   [tool.uv.dev-dependencies]
   numpy = "*"
   

3. Удаление зависимости:
   Команда uv remove удаляет пакет и очищает pyproject.toml. Для "dev" зависимостей нужно также указать флаг --dev.

   uv remove numpy --dev
   

   После этого секция [tool.uv.dev-dependencies] должна исчезнуть из pyproject.toml.

Ключевые выводы

Поздравляю! Вы успешно настроили профессиональное окружение для нашего CAD-проекта. Сегодня мы:

• Разобрались с назначением uv и его преимуществами.
• Создали новый Python-проект с помощью uv init.
• Научились добавлять и управлять зависимостями командой uv add.
• Установили build123d и проверили, что всё работает, запустив скрипт через uv run.

Эта прочная основа позволит нам сосредоточиться на самом интересном — 3D-моделировании.

Что дальше?

В следующем уроке мы сделаем наш первый видимый шаг в 3D. Мы научимся:

• Интегрировать 3D-вьювер OCP CAD Viewer в ваш рабочий процесс с tmux и Helix.
• Создавать первый параметрический объект и изменять его размеры через переменные.
• Экспортировать модель в STL-файл, готовый для 3D-принтера.