feat: migrate from Poetry to UV

- Replace Poetry with UV for dependency management
- Update workflows, configs, and documentation
- Switch to hatchling build backend
- Improve performance and modernize toolchain

Author: HosseinNejatiJavaremi

.github/ISSUE_TEMPLATE/bug_report.md

@@ -13,7 +13,7 @@ A clear and concise description of the bug.
 ## Reproduction Steps
 Steps to reproduce the behavior:
 1. Install '...'
-2. Configure '...' 
+2. Configure '...'
 3. Run code '...'
 4. See error
 

.github/workflows/deploy-docs.yml

@@ -26,26 +26,19 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: '3.13'
-          cache: 'pip'
 
-      - name: Install Poetry
-        uses: snok/install-poetry@v1
-        with:
-          version: 2.0.0
-          virtualenvs-create: true
-          virtualenvs-in-project: true
+      - name: Install UV
+        uses: astral-sh/setup-uv@v4
 
-      - name: Load cached dependencies
-        id: cached-poetry-dependencies
+      - name: Cache UV
         uses: actions/cache@v4
         with:
-          path: .venv
-          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
+          path: ~/.cache/uv
+          key: uv-${{ runner.os }}-docs-${{ hashFiles('uv.lock') }}
 
       - name: Install dependencies
-        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
         run: |
-          poetry install --with docs
+          uv sync --extra docs
 
       - name: Configure Git user
         run: |
@@ -54,4 +47,4 @@ jobs:
 
       - name: Deploy documentation
         run: |
-          poetry run mkdocs gh-deploy --force
+          uv run --extra docs mkdocs gh-deploy --force

.github/workflows/lint.yml

@@ -23,16 +23,15 @@ jobs:
       with:
         python-version: "3.13"
 
-    - name: Install Poetry
-      run: |
-        pip install poetry
+    - name: Install UV
+      uses: astral-sh/setup-uv@v4
 
     - name: Install dependencies
       run: |
-        poetry install --with dev
+        uv sync --extra dev
 
     - name: Run Ruff on changed files
       run: |
         # Filter Python files from changed files and run Ruff
-        echo "${{ steps.changed-files.outputs.all_changed_files }}" | tr ' ' '\n' | grep '\.py$' | xargs -r poetry run ruff check
-        echo "${{ steps.changed-files.outputs.all_changed_files }}" | tr ' ' '\n' | grep '\.py$' | xargs -r poetry run ruff format --check
+        echo "${{ steps.changed-files.outputs.all_changed_files }}" | tr ' ' '\n' | grep '\.py$' | xargs -r uv run ruff check
+        echo "${{ steps.changed-files.outputs.all_changed_files }}" | tr ' ' '\n' | grep '\.py$' | xargs -r uv run ruff format --check

.github/workflows/publish.yml

@@ -17,14 +17,19 @@ jobs:
       with:
         python-version: 3.13
 
-    - name: Install Poetry
+    - name: Install UV
+      uses: astral-sh/setup-uv@v4
+
+    - name: Update version in pyproject.toml
       run: |
-        pip install poetry
+        # Extract version from tag
+        VERSION=${GITHUB_REF#refs/tags/}
+        # Update version in pyproject.toml
+        sed -i "s/^version = .*/version = \"$VERSION\"/" pyproject.toml
 
     - name: Build and Publish to PyPI
       env:
-        POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}
+        UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
       run: |
-        poetry version ${GITHUB_REF#refs/tags/}
-        poetry build
-        poetry publish
+        uv build
+        uv publish

.github/workflows/tests.yml

@@ -17,22 +17,18 @@ jobs:
     - uses: actions/checkout@v4
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
 
-    - name: Install Poetry
-      uses: snok/install-poetry@v1
-      with:
-        virtualenvs-create: true
-        virtualenvs-in-project: true
+    - name: Install UV
+      uses: astral-sh/setup-uv@v4
 
-    - name: Cache Poetry virtualenv
-      uses: actions/cache@v3
-      id: cache
+    - name: Cache UV
+      uses: actions/cache@v4
       with:
-        path: .venv
-        key: venv-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}
+        path: ~/.cache/uv
+        key: uv-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
 
     - name: Install dependencies
       run: make install-dev

.pre-commit-config.yaml

@@ -3,91 +3,86 @@ repos:
     hooks:
       - id: check-added-large-files
         name: check-added-large-files
-        entry: poetry run check-added-large-files
+        entry: uv run check-added-large-files
         language: system
       - id: check-yaml
         name: check-yaml
-        entry: poetry run check-yaml
+        entry: uv run check-yaml
         types:
           - yaml
         language: system
       - id: check-toml
         name: check-toml
-        entry: poetry run check-toml
+        entry: uv run check-toml
         types:
           - toml
         language: system
       - id: check-json
         name: check-json
-        entry: poetry run check-json
+        entry: uv run check-json
         types:
           - json
         language: system
       - id: pretty-format-json
         name: pretty-format-json
-        entry: poetry run pretty-format-json
+        entry: uv run pretty-format-json
         types:
           - json
         language: system
       - id: end-of-file-fixer
         name: end-of-file-fixer
-        entry: poetry run end-of-file-fixer
+        entry: uv run end-of-file-fixer
         language: system
       - id: trailing-whitespace-fixer
         name: trailing-whitespace-fixer
-        entry: poetry run trailing-whitespace-fixer
+        entry: uv run trailing-whitespace-fixer
         language: system
-      - id: poetry-check
-        name: poetry-check
-        entry: poetry check
-        language: system
-        pass_filenames: false
-      - id: poetry-lock
-        name: poetry-lock
-        entry: poetry lock
+      - id: uv-lock
+        name: uv-lock
+        entry: uv lock
         language: system
         pass_filenames: false
         stages:
           - post-checkout
           - post-merge
-      - id: poetry-install
-        name: poetry-install
-        entry: poetry install
+      - id: uv-sync
+        name: uv-sync
+        entry: uv sync --extra dev
         language: system
         pass_filenames: false
         stages:
           - post-checkout
           - post-merge
       - id: codespell
         name: codespell
-        entry: poetry run codespell --toml pyproject.toml
+        entry: uv run codespell --toml pyproject.toml
         files: \.(py|pyi)$
         language: system
       - id: black
         name: black
-        entry: poetry run black --config pyproject.toml
+        entry: uv run black --config pyproject.toml
         files: \.(py|pyi)$
         language: system
         exclude: ^(features|scripts)/
       - id: ruff
         name: ruff
-        entry: poetry run ruff check --config pyproject.toml --fix
+        entry: uv run ruff check --config pyproject.toml --fix
         files: \.(py|pyi)$
         language: system
         exclude: ^(features|scripts)/
       - id: add-trailing-comma
         name: add-trailing-comma
-        entry: poetry run add-trailing-comma
+        entry: uv run add-trailing-comma
         files: \.(py|pyi)$
         language: system
       - id: validate-pyproject
         name: validate-pyproject
-        entry: poetry run validate-pyproject pyproject.toml
+        entry: uv run validate-pyproject pyproject.toml
         language: system
         pass_filenames: false
       - id: mypy
         name: mypy
-        entry: poetry run mypy --config-file pyproject.toml
+        entry: uv run mypy --config-file pyproject.toml
         files: \.(py|pyi)$
         language: system
         exclude: ^(features|scripts)/

CONTRIBUTING.md

@@ -75,7 +75,7 @@ Documentation is crucial for user experience. You can help by:
 Before contributing, ensure you have:
 
 - **Python 3.13+**
-- **Poetry** (dependency management)
+- **UV** (dependency management)
 - **Git**
 - **make** (for running development commands)
 
@@ -89,7 +89,7 @@ Before contributing, ensure you have:
 
 2. **Set up the environment**:
    ```bash
-   # Set up project pre-requisites
+   # Set up project pre-requisites (installs UV)
    make setup
 
    # Install development dependencies

Makefile

@@ -1,7 +1,7 @@
 # Variables
-PYTHON := poetry run
-POETRY := poetry
-PRE_COMMIT := poetry run pre-commit
+PYTHON := uv run
+UV := uv
+PRE_COMMIT := uv run pre-commit
 PROJECT_NAME := archipy
 PYTHON_FILES := $(PROJECT_NAME) features/steps scripts
 
@@ -23,28 +23,28 @@ help: ## Show this help message
 .PHONY: setup
 setup: ## Setup project pre-requisites
 	@echo "${BLUE}Setup project pre-requisites...${NC}"
-	@echo "${GREEN}Installing poetry (may need your sudo password)...${NC}"
+	@echo "${GREEN}Installing uv (may need your sudo password)...${NC}"
 	sudo apt install pipx
-	pipx install poetry
+	pipx install uv
 	pipx ensurepath
-	poetry completions bash >> ~/.bash_completion
+	uv generate-shell-completion bash >> ~/.bash_completion
 
 .PHONY: install
 install: ## Install project dependencies
 	@echo "${BLUE}Installing project dependencies...${NC}"
-	$(POETRY) install
+	$(UV) sync --extra dev
 	$(PRE_COMMIT) install
 
 .PHONY: install-dev
-install-dev: ## Install project dependencies
-	@echo "${BLUE}Installing project dependencies...${NC}"
-	$(POETRY) install --with dev --all-extras
+install-dev: ## Install project dependencies with dev extras
+	@echo "${BLUE}Installing project dependencies with dev extras...${NC}"
+	$(UV) sync --all-extras
 	$(PRE_COMMIT) install
 
 .PHONY: update
 update: ## Update dependencies to their latest versions
 	@echo "${BLUE}Updating dependencies...${NC}"
-	$(POETRY) update
+	$(UV) lock --upgrade
 
 .PHONY: clean
 clean: ## Remove build artifacts and cache directories
@@ -77,45 +77,48 @@ security: ## Run security scan with Bandit
 .PHONY: behave
 behave: ## Run tests with behave
 	@echo "${BLUE}Running tests...${NC}"
-	$(PYTHON) behave
+	$(UV) run --extra behave behave
+
+.PHONY: test
+test: behave ## Run tests (alias for behave)
 
 .PHONY: build
 build: clean ## Build project distribution
 	@echo "${BLUE}Building project distribution...${NC}"
-	$(POETRY) build
+	$(UV) build
 
 .PHONY: version
 version: ## Display current version
 	@echo "${BLUE}Current version:${NC}"
-	@$(POETRY) version
-	@echo "${YELLOW}Current tag(Fetching...):${NC}"
-	@git fetch && git describe --tags  --abbrev=0
+	@$(UV) run python -c "import tomllib; print(f\"archipy {tomllib.load(open('pyproject.toml', 'rb'))['project']['version']}\")"
+	@echo "${YELLOW}Current tag:${NC}"
+	@git describe --tags --abbrev=0 2>/dev/null || echo "No tags found"
 
 .PHONY: bump-patch
 bump-patch: ## Bump patch version
 	@echo "${BLUE}Bumping patch version...${NC}"
 	@if [ -n "$(message)" ]; then \
-		$(PYTHON) python scripts/bump_version.py patch -m "$(message)"; \
+		$(UV) run python scripts/bump_version.py patch -m "$(message)"; \
 	else \
-		$(PYTHON) python scripts/bump_version.py patch -m "$$(git log -1 --pretty=%s)"; \
+		$(UV) run python scripts/bump_version.py patch -m "$$(git log -1 --pretty=%s)"; \
 	fi
 
 .PHONY: bump-minor
 bump-minor: ## Bump minor version
 	@echo "${BLUE}Bumping minor version...${NC}"
 	@if [ -n "$(message)" ]; then \
-		$(PYTHON) python scripts/bump_version.py minor -m "$(message)"; \
+		$(UV) run python scripts/bump_version.py minor -m "$(message)"; \
 	else \
-		$(PYTHON) python scripts/bump_version.py minor -m "$$(git log -1 --pretty=%s)"; \
+		$(UV) run python scripts/bump_version.py minor -m "$$(git log -1 --pretty=%s)"; \
 	fi
 
 .PHONY: bump-major
 bump-major: ## Bump major version
 	@echo "${BLUE}Bumping major version...${NC}"
 	@if [ -n "$(message)" ]; then \
-		$(PYTHON) python scripts/bump_version.py major -m "$(message)"; \
+		$(UV) run python scripts/bump_version.py major -m "$(message)"; \
 	else \
-		$(PYTHON) python scripts/bump_version.py major -m "$$(git log -1 --pretty=%s)"; \
+		$(UV) run python scripts/bump_version.py major -m "$$(git log -1 --pretty=%s)"; \
 	fi
 
 .PHONY: docker-build
@@ -134,7 +137,7 @@ pre-commit: ## Run pre-commit hooks
 	$(PRE_COMMIT) run --all-files
 
 .PHONY: check
-check: lint security test ## Run all checks (linting, security, and tests)
+check: lint security behave ## Run all checks (linting, security, and tests)
 
 .PHONY: ci
 ci: ## Run CI pipeline locally
@@ -143,22 +146,22 @@ ci: ## Run CI pipeline locally
 	$(MAKE) install
 	$(MAKE) lint
 	$(MAKE) security
-	$(MAKE) test
+	$(MAKE) behave
 	$(MAKE) build
 
 .PHONY: docs-serve
 docs-serve: ## Serve MkDocs documentation locally
 	@echo "${BLUE}Serving documentation...${NC}"
-	$(POETRY) run mkdocs serve
+	$(UV) run --extra docs mkdocs serve
 
 .PHONY: docs-build
 docs-build: ## Build MkDocs documentation
 	@echo "${BLUE}Building documentation...${NC}"
-	$(POETRY) run mkdocs build
+	$(UV) run --extra docs mkdocs build
 
 .PHONY: docs-deploy
 docs-deploy: ## Deploy MkDocs to GitHub Pages
 	@echo "${BLUE}Deploying documentation...${NC}"
-	$(POETRY) run mkdocs gh-deploy --force
+	$(UV) run --extra docs mkdocs gh-deploy --force
 
 .DEFAULT_GOAL := help