Developer Environment Setup

Relevant source files

The following files were used as context for generating this wiki page:

• requirements-dev.txt
• pyproject.toml
• constraints/py311.txt
• Makefile
• .pre-commit-config.yaml
• pytest.ini
• .github/workflows/qa.yml
• .coveragerc

The Aldeci project utilizes a standardized Python development environment to ensure consistency and code quality. The setup relies on pip for dependency management, make for orchestrating common tasks, and a suite of linting and formatting tools integrated via pre-commit hooks.

This guide outlines the necessary steps and tools for setting up a local development environment, running tests, and maintaining code quality, as defined within the project's configuration files. The environment is built for Python 3.11 and is replicated in the CI/CD pipeline for automated checks.

1. Prerequisites and Installation

The project is designed to run on Python 3.11. A Makefile is provided to streamline the setup process, including virtual environment creation and dependency installation.

1.1. Python Version

The project's dependencies are constrained for Python 3.11. This ensures that all developers and CI/CD environments use a consistent set of package versions, preventing "works on my machine" issues.

Sources: constraints/py311.txt

1.2. Initial Setup

The primary method for setting up the development environment is through the make install-dev command. This command automates the following steps:

1. Creates a Python virtual environment in the .venv directory.
2. Installs core application dependencies from requirements.txt.
3. Installs development-specific dependencies from requirements-dev.txt.
4. Installs pre-commit hooks for automated code quality checks.

The following diagram illustrates the developer setup workflow.

1.3. Development Dependencies

In addition to the core application dependencies, the development environment includes tools for testing, linting, and formatting. These are specified in requirements-dev.txt.

Package	Version	Description
black	24.4.2	The uncompromising Python code formatter.
ruff	0.4.4	An extremely fast Python linter and code formatter.
mypy	1.10.0	Optional static type checker for Python.
pytest	8.2.1	A framework for writing and running tests.
pytest-cov	5.0.0	Pytest plugin for measuring code coverage.
pre-commit	3.7.1	A framework for managing and maintaining multi-language pre-commit hooks.
pyright	1.1.366	Static type checker for Python.

Sources: requirements-dev.txt

2. Code Quality and Tooling

The project enforces a strict code quality standard using a combination of automated tools for formatting, linting, and static analysis. These are configured in pyproject.toml and executed via pre-commit hooks and Makefile commands.

2.1. Pre-commit Hooks

The project uses pre-commit to run checks automatically before each commit. This ensures that all committed code adheres to the project's style and quality standards. The hooks are defined in .pre-commit-config.yaml.

After running make install-dev, the hooks are ready. They will run on any staged files when you execute git commit.

The diagram below shows the sequence of actions during a git commit operation with pre-commit hooks enabled.

The following table details the configured pre-commit hooks.

Hook ID	Repository	Description
check-yaml	pre-commit-hooks	Checks YAML files for parseable syntax.
check-toml	pre-commit-hooks	Checks TOML files for parseable syntax.
black	psf/black	Formats Python code consistently.
ruff	astral-sh/ruff-pre-commit	Lints and formats Python code.
mypy	pre-commit/mirrors-mypy	Performs static type analysis.

Sources: .pre-commit-config.yaml

2.2. Tool Configuration (pyproject.toml)

The pyproject.toml file serves as a central configuration point for many development tools, ensuring consistent behavior.

• Black: Configured to target Python 3.11 and exclude the .venv directory.
• Ruff: Configured to target Python 3.11, with specific rules selected and ignored. It is also set to fix issues automatically where possible.
• MyPy: Configured with strict settings, such as disallow_untyped_defs and warn_return_any, to enforce strong typing. It excludes test files and the .venv directory.

Sources: pyproject.toml:13-64

3. Testing

Testing is managed using pytest and pytest-cov. The configuration is defined in pytest.ini, and tests are executed using a Makefile command.

3.1. Test Configuration

The pytest.ini file specifies the following configurations:

• Test Path: Tests are located in the tests/ directory.
• Python Files: Test files are identified by the pattern test_*.py.
• Markers: A wip marker is defined to mark "work-in-progress" tests, which can be run or skipped selectively.

Sources: pytest.ini:1-5

3.2. Running Tests

Tests are executed using the make test command. This command runs pytest and generates a coverage report.

make test

This command is an alias for pytest --cov --cov-report=term-missing --cov-report=xml:reports/coverage/coverage.xml. Coverage settings are further defined in .coveragerc, which excludes test files and the virtual environment from the report.

Sources: Makefile:27, .coveragerc:1-4, .github/workflows/qa.yml:57

4. Makefile Commands

The Makefile provides a convenient interface for common development tasks.

Command	Description
install-dev	Sets up the development environment by creating a venv and installing all dependencies.
test	Runs the test suite using pytest and generates a coverage report.
format	Formats the codebase using black and ruff.
lint	Lints the codebase using ruff and runs static type checking with mypy.
clean	Removes temporary files like .pyc files, coverage reports, and the virtual environment.
run-demo	Executes the demo pipeline in "demo" mode.
run-demo-enterprise	Executes the demo pipeline in "enterprise" mode.

Sources: Makefile