Sókrates Wiki

Grimoire Development Environment Setup

3 min read

Grimoire Development Environment Setup

Summary

This process documents the configuration and standardization of the development environment for the grimoire repository. It details the transition to a uv-managed workflow, the replacement of legacy type checkers with ty, and the enforcement of separate virtual environments to prevent dependency coupling between the Grimoire standalone repository and the Sokrates monorepo.

Details

The grimoire project, specifically located within the grimoire/sets_app/ directory, underwent a significant environment stabilization process to ensure it remains independent of the primary Sokrates monorepo. Although the Sokrates workspace includes grimoire as a member for eventual merging, the current development strategy maintains them as separate entities with distinct git histories and dependency trees.

Virtual Environment Strategy

A key architectural decision was the implementation of two distinct virtual environments (venvs). This separation ensures that the grimoire standalone repository does not inherit or conflict with the dependencies of the Sokrates monorepo. The environment is managed using uv, which provides high-performance dependency resolution and synchronization.

Tooling and Dependency Migration

The project migrated its core development and quality assurance tools to a modernized stack:

  • Type Checking: The project replaced pyright and basedpyright with ty. During the setup, ty was pinned to version 0.0.25 to establish a consistent baseline for type checking across the codebase.
  • Linting and Formatting: ruff was identified as the primary linter. During the environment refresh, ruff was upgraded from version 0.14.6 to 0.15.7 to leverage the latest rules and performance improvements.
  • Build System: The project utilizes hatchling as the build backend, defined within the pyproject.toml file.
  • Testing Suite: To support robust testing of the FastAPI-based application, several development dependencies were integrated:
    • pytest and pytest-asyncio for asynchronous test execution.
    • hypothesis for property-based testing.
    • httpx to serve as the test client for FastAPI endpoints.

Execution Workflow

The setup process followed a structured sequence to ensure environment integrity:

  1. Configuration Update: The pyproject.toml was modified to remove legacy type checkers, add ty configurations, and include the new testing dependencies.
  2. Synchronization: The command uv sync was executed to generate the virtual environment and install the exact versions specified in the lockfile.
  3. Baseline Establishment: Following the sync, both ty and ruff were executed against the source code to identify existing issues and establish a “clean” state for future development tickets. This baseline allows developers to distinguish between pre-existing technical debt and new issues introduced during feature development.

Graph View